Telnyx x402 Payment Transactions API
Operations for x402 cryptocurrency payment transactions. Fund your Telnyx account using USDC stablecoin payments via the x402 protocol.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/telnyx-x402-payment-transactions-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
OpenAPI Specification
openapi: 3.1.0
info:
contact:
email: support@telnyx.com
description: Telnyx provides global communications and connectivity APIs for developers — including SIP trunking, programmable voice, SMS, MMS, WhatsApp Business Messaging, Call Control, Fax, Wireless (IoT & eSIM), Phone Numbers (DID provisioning & porting), Emergency Services, and Network APIs for private interconnects and edge connectivity. Build, scale, and manage voice, messaging, and data networks with Telnyx's carrier-grade global infrastructure and API-first platform.
title: Telnyx Access Tokens x402 Payment Transactions API
version: 2.0.0
x-endpoint-cost: light
servers:
- description: Version 2.0.0 of the Telnyx API
url: https://api.telnyx.com/v2
security:
- bearerAuth: []
tags:
- description: Operations for x402 cryptocurrency payment transactions. Fund your Telnyx account using USDC stablecoin payments via the x402 protocol.
name: x402 Payment Transactions
paths:
/v2/x402/credit_account:
post:
description: Settles an x402 payment using the quote ID and a signed payment authorization. The payment signature can be provided via the `PAYMENT-SIGNATURE` header or the `payment_signature` body parameter. Settlement is idempotent — submitting the same quote ID multiple times returns the existing transaction.
operationId: settleX402Payment
parameters:
- description: Signed payment authorization for the quote. Alternative to providing `payment_signature` in the request body.
in: header
name: PAYMENT-SIGNATURE
required: false
schema:
type: string
requestBody:
content:
application/json:
example:
id: quote_abc123
payment_signature: 0xabc123...
schema:
$ref: '#/components/schemas/X402SettleRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/X402TransactionResponse'
description: Payment already settled (idempotent response)
'201':
content:
application/json:
example:
data:
amount: '50.00'
created_at: '2026-03-13T15:00:00Z'
currency: USD
id: de06811a-2e43-4561-af5a-7d0a26e20aaa
quote_id: quote_abc123
record_type: x402_transaction
status: settled
tx_hash: 0xabc123def456...
schema:
$ref: '#/components/schemas/X402TransactionResponse'
description: Payment settled successfully
'400':
content:
application/json:
examples:
expired_authorization:
summary: Expired payment authorization
value:
errors:
- code: expired_authorization
detail: 'Payment failed: the payment authorization has expired. Please request a new quote and try again.'
title: Payment Failed
invalid_signature:
summary: Invalid payment signature
value:
errors:
- code: invalid_signature
detail: 'Payment failed: the payment signature is invalid. Please sign a new payment authorization.'
title: Payment Failed
schema:
$ref: '#/components/schemas/X402SettlementErrorResponse'
description: Bad request — invalid signature, expired authorization, invalid nonce, or malformed payment payload
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/x402-transactions_ErrorResponse'
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/x402-transactions_ErrorResponse'
description: Forbidden — x402 payments not enabled, account tier ineligible, or account suspended
'422':
content:
application/json:
examples:
insufficient_balance:
summary: Insufficient wallet balance
value:
errors:
- code: insufficient_balance
detail: 'Payment failed: your wallet does not have enough USDC to complete this transaction. Please add funds and try again.'
title: Payment Failed
validation_error:
summary: Missing required parameter
value:
errors:
- code: unknown
detail: id is required
title: Invalid request
schema:
$ref: '#/components/schemas/X402SettlementErrorResponse'
description: Unprocessable entity — missing required parameters or insufficient funds/allowance
'500':
content:
application/json:
example:
errors:
- code: transaction_failed
detail: Payment transaction failed on-chain. Your funds have not been transferred. Please try again or contact support.
title: Payment Failed
schema:
$ref: '#/components/schemas/X402SettlementErrorResponse'
description: Internal server error — facilitator unavailable, transaction failed on-chain, or unknown error
'502':
content:
application/json:
schema:
$ref: '#/components/schemas/x402-transactions_ErrorResponse'
description: Bad gateway — upstream settlement service error
'503':
content:
application/json:
example:
errors:
- code: facilitator_timeout
detail: Payment processing timed out. Your funds have not been transferred. Please try again.
title: Payment Failed
schema:
$ref: '#/components/schemas/X402SettlementErrorResponse'
description: Service unavailable — facilitator or settlement timeout
summary: Settle a payment
tags:
- x402 Payment Transactions
x-endpoint-cost: light
x-latency-category: responsive
/v2/x402/credit_account/quote:
post:
description: Creates a payment quote for the specified USD amount. Returns payment details including the x402 payment requirements, network, and expiration time. The quote must be settled before it expires.
operationId: createX402Quote
requestBody:
content:
application/json:
example:
amount_usd: '50.00'
schema:
$ref: '#/components/schemas/X402QuoteRequest'
required: true
responses:
'200':
content:
application/json:
example:
data:
amount_crypto: '50000000'
amount_usd: '50.00'
expires_at: '2026-03-13T15:05:00Z'
id: quote_abc123
network: eip155:8453
payment_requirements:
accepts:
- amount: '50000000'
asset: '0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'
extra:
facilitatorUrl: https://api.cdp.coinbase.com/platform/v2/x402
name: USD Coin
quoteId: quote_abc123
version: '2'
maxTimeoutSeconds: 900
network: eip155:8453
payTo: '0x1234567890abcdef1234567890abcdef12345678'
scheme: exact
resource:
description: Payment of $50.00 USD
mimeType: application/json
url: https://api.telnyx.com/v2/x402/credit_account
x402Version: 2
record_type: quote
schema:
$ref: '#/components/schemas/X402QuoteResponse'
description: Quote created successfully
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/x402-transactions_ErrorResponse'
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/x402-transactions_ErrorResponse'
description: Forbidden — x402 payments not enabled, account tier ineligible, or account suspended
'422':
content:
application/json:
example:
errors:
- code: unknown
detail: amount_usd must be at least 5.00
title: Invalid request
schema:
$ref: '#/components/schemas/x402-transactions_ErrorResponse'
description: Unprocessable entity — invalid amount
'502':
content:
application/json:
schema:
$ref: '#/components/schemas/x402-transactions_ErrorResponse'
description: Bad gateway — upstream payment service failed to create quote
summary: Create a payment quote
tags:
- x402 Payment Transactions
x-endpoint-cost: light
x-latency-category: responsive
components:
schemas:
x402-transactions_ErrorResponse:
properties:
errors:
items:
properties:
code:
type: string
detail:
type: string
meta:
properties:
url:
type: string
type: object
source:
properties:
pointer:
type: string
type: object
title:
type: string
type: object
type: array
type: object
X402QuoteRequest:
properties:
amount_usd:
description: Amount in USD to fund (minimum 5.00, maximum 10000.00).
example: '50.00'
type: string
required:
- amount_usd
type: object
X402SettlementErrorResponse:
description: Error response for x402 settlement failures. Uses string error codes from the x402 error handling system.
properties:
errors:
items:
properties:
code:
description: Machine-readable error code.
enum:
- invalid_signature
- expired_authorization
- invalid_nonce
- insufficient_balance
- insufficient_funds
- insufficient_allowance
- facilitator_unavailable
- facilitator_timeout
- settlement_timeout
- transaction_failed
- unknown
type: string
detail:
description: Human-readable error description with guidance.
type: string
title:
description: Short error title (e.g. "Payment Failed").
type: string
type: object
type: array
type: object
X402SettleRequest:
properties:
id:
description: The quote ID to settle.
type: string
payment_signature:
description: Base64-encoded signed payment authorization (x402 PaymentPayload). Can alternatively be provided via the PAYMENT-SIGNATURE header.
type: string
required:
- id
type: object
X402PaymentRequirements:
description: x402 protocol v2 payment requirements. Contains all information needed to construct and sign a payment authorization.
properties:
accepts:
description: Accepted payment schemes. Currently only the `exact` EVM scheme is supported.
items:
properties:
amount:
description: Amount in the token's smallest unit.
type: string
asset:
description: Token contract address (e.g. USDC on Base).
type: string
extra:
description: Additional scheme-specific parameters including EIP-712 domain info and the facilitator URL.
properties:
facilitatorUrl:
type: string
name:
description: EIP-712 domain name (e.g. "USD Coin").
type: string
quoteId:
type: string
version:
description: EIP-712 domain version.
type: string
type: object
maxTimeoutSeconds:
description: Maximum time in seconds before the payment authorization expires.
type: integer
network:
description: Blockchain network identifier in CAIP-2 format (e.g. "eip155:8453" for Base).
type: string
payTo:
description: Recipient wallet address.
type: string
scheme:
description: Payment scheme (e.g. "exact").
type: string
type: object
type: array
resource:
description: The resource being paid for. Included in the payment signature.
properties:
description:
description: Human-readable description of the payment.
type: string
mimeType:
description: MIME type of the resource.
type: string
url:
description: Canonical URL of the payment resource.
type: string
type: object
x402Version:
description: x402 protocol version. Currently always 2.
enum:
- 2
type: integer
type: object
X402QuoteResponse:
properties:
data:
properties:
amount_crypto:
description: The equivalent amount in the payment cryptocurrency's smallest unit (e.g. USDC has 6 decimals, so $50.00 = "50000000").
type: string
amount_usd:
description: The quoted amount in USD.
type: string
expires_at:
description: ISO 8601 timestamp when the quote expires.
format: date-time
type: string
id:
description: Unique quote identifier. Use this to settle the payment.
type: string
network:
description: The blockchain network for the payment in CAIP-2 format (e.g. eip155:8453 for Base).
type: string
payment_requirements:
$ref: '#/components/schemas/X402PaymentRequirements'
record_type:
enum:
- quote
type: string
type: object
type: object
X402TransactionResponse:
properties:
data:
properties:
amount:
description: The transaction amount in the specified currency.
type: string
created_at:
description: ISO 8601 timestamp when the transaction was created.
format: date-time
type: string
currency:
description: The currency of the transaction amount (e.g. USD).
type: string
id:
description: Unique transaction identifier.
type: string
quote_id:
description: The original quote ID associated with this transaction.
type: string
record_type:
enum:
- x402_transaction
type: string
status:
description: The settlement status of the transaction.
enum:
- settled
type: string
tx_hash:
description: The on-chain transaction hash, if available.
nullable: true
type: string
type: object
type: object
securitySchemes:
bearerAuth:
scheme: bearer
type: http
branded-calling_bearerAuth:
description: API key passed as a Bearer token in the Authorization header
scheme: bearer
type: http
oauthClientAuth:
description: OAuth 2.0 authentication for Telnyx API and MCP integrations
flows:
authorizationCode:
authorizationUrl: https://api.telnyx.com/v2/oauth/authorize
refreshUrl: https://api.telnyx.com/v2/oauth/token
scopes:
admin: Administrative access to Telnyx resources
tokenUrl: https://api.telnyx.com/v2/oauth/token
clientCredentials:
scopes:
admin: Administrative access to Telnyx resources
tokenUrl: https://api.telnyx.com/v2/oauth/token
type: oauth2
outbound-voice-profiles_bearerAuth:
bearerFormat: JWT
scheme: bearer
type: http
pronunciation-dicts_bearerAuth:
description: Telnyx API v2 key. Obtain from https://portal.telnyx.com
scheme: bearer
type: http
stored-payment-transactions_bearerAuth:
bearerFormat: JWT
scheme: bearer
type: http