telnyx-x402-payment

name	telnyx-x402-payment
description	Make cryptocurrency payments to fund a Telnyx account using the x402 protocol (USDC on Base). Covers quoting, EIP-712 signing, and settlement.
metadata	{"author":"telnyx","product":"payments","requires":{"bins":["curl","jq"],"env":["TELNYX_API_KEY"]}}

Telnyx x402 Cryptocurrency Payment

Fund a Telnyx account with USDC on the Base blockchain using the x402 payment protocol. The flow has three steps: get a quote, sign the payment client-side, and submit for settlement.

Feature Flag: x402 payments are gated behind the X402_PAYMENTS_ENABLED feature flag. If not enabled for the account, the API returns 403 Forbidden.

Prerequisites

• Telnyx API key (TELNYX_API_KEY)
• Crypto wallet with USDC on Base network (chain ID: eip155:8453)
• USDC contract on Base: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

Environment Variables

Variable	Required	Description
TELNYX_API_KEY	Yes	Telnyx API v2 key

Step 1: Get a Quote

Request a quote for the USD amount to fund. Per-payment minimum and maximum limits apply; they are configurable and may change, and the API's 422 error messages state the current values. Quotes expire after 5 minutes.

curl -s -X POST "https://api.telnyx.com/v2/x402/credit_account/quote" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_usd": "50.00"}' | jq .

Response:

{
  "data": {
    "id": "quote_abc123",
    "record_type": "quote",
    "amount_usd": "50.00",
    "amount_crypto": "50000000",
    "network": "eip155:8453",
    "expires_at": "2026-03-09T19:00:00Z",
    "payment_requirements": {
      "x402Version": 2,
      "resource": {
        "url": "payment:quote_abc123",
        "description": "Payment of $50.00 USD",
        "mimeType": "application/json"
      },
      "accepts": [
        {
          "scheme" 
           
           
           
           
           
           
             
             
             
             
          
        
      
    
  

Quote Response Fields

Field	Description
id	Quote identifier (use in submission)
record_type	Always "quote"
amount_usd	Requested USD amount
amount_crypto	USDC amount in smallest unit (6 decimals: $50.00 → "50000000")
network	CAIP-2 network identifier (e.g. "eip155:8453")
expires_at	ISO 8601 quote expiry (5 minutes from creation)
payment_requirements	x402 V2 payment requirements (see below)

Payment Requirements (x402 V2)

The payment_requirements object follows the x402 protocol V2 structure:

• x402Version — Protocol version (2)
• resource — The resource being paid for:
  • url — Canonical resource URL (included in the payment signature)
  • description — Human-readable description
  • mimeType — Response content type
• accepts — Array of accepted payment methods, each containing:
  • scheme — Payment scheme ("exact" for fixed-amount transfers)
  • network — CAIP-2 network (e.g. "eip155:8453")
  • amount — Amount in token smallest units
  • asset — Token contract address
  • payTo — Recipient wallet address
  • maxTimeoutSeconds — Maximum time before quote expires
  • extra — Additional metadata: quoteId, facilitatorUrl, and EIP-712 domain fields name and version. Note: chainId is derived from network (e.g., eip155:8453 → 8453) and verifyingContract is the same as asset

Step 2: Sign the Payment (Client-Side)

The user must sign an EIP-712 typed data message authorizing a USDC transferWithAuthorization (EIP-3009). This is done client-side using ethers.js, viem, or any EIP-712 signing library.

⚠️ Security: Never hardcode private keys in source code or commit them to version control. Use environment variables, a hardware wallet, or a secure key management service.

Required inputs:

• Payer wallet's private key
• Quote details from payment_requirements.accepts[0]: payTo, amount, and the EIP-712 domain from extra
• A random 32-byte nonce
• Validity period (current time → quote expiry)

EIP-712 domain (assembled from multiple sources):

{
  "name": "USD Coin",              // ← from quote: accepts[0].extra.name
  "version": "2",                  // ← from quote: accepts[0].extra.version
  "chainId": 8453,                 // ← client must know: Base mainnet chain ID (NOT in quote response)
  "verifyingContract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"  // ← client must know: USDC contract address on Base (NOT in quote response)
}

Important: Only name and version are provided in the quote response (accepts[0].extra). The client must derive the remaining EIP-712 domain fields:

• chainId: Parse from the CAIP-2 network string in accepts[0].network (e.g., "eip155:8453" → 8453)
• verifyingContract: Same as accepts[0].asset — the USDC token contract address

These are not included in the quote response; they are derived from other fields in accepts[0].

EIP-712 types (TransferWithAuthorization):

{
  "TransferWithAuthorization": [
    { "name": "from", "type": "address" },
    { "name": "to", "type": "address" },
    { "name": "value", "type": "uint256" },
    { "name": "validAfter", "type": "uint256" },
    { "name": "validBefore", "type": "uint256" },
    { "name": "nonce",   
  

The signing produces a signature (r, s, v) that authorizes the USDC transfer without requiring an on-chain transaction from the user.

This step cannot be done with curl alone — it requires a crypto signing library. Guide the user to use ethers.js, viem, or a similar tool.

Building the payment_signature Payload

After signing, you must construct the payment payload JSON and base64-encode it.

⚠️ Critical: The PaymentPayload v2 has THREE top-level keys: x402Version, accepted, and payload. The payload (signature + authorization) is a top-level sibling of accepted, NOT nested inside it.

PaymentPayload v2 structure:

PaymentPayload v2:
├── x402Version: 2
├── resource (optional): ← What is being paid for
│   ├── url
│   ├── description
│   └── mimeType
├── accepted:          ← WHAT is being paid (exact copy of accepts[0])
│   ├── scheme
│   ├── network
│   ├── amount
│   ├── asset
│   ├── payTo
│   ├── maxTimeoutSeconds
│   └── extra: { quoteId, facilitatorUrl, name, version }
└── payload:           ← PROOF of payment authorization (top-level!)
    ├── signature
    └── authorization: { from, to, value, validAfter, validBefore, nonce }

Correct v2 format (complete example with realistic values):

{
  "x402Version": 2,
  "resource": {
    "url": "https://api.telnyx.com/v2/x402/credit_account",
    "description": "Credit account via x402 payment",
    "mimeType": "application/json"
  },
  "accepted": {
    "scheme": "exact",
    "network": "eip155:8453",
    "amount": "50000000",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97",
    "maxTimeoutSeconds": 300,
    "extra": {
      "quoteId": "quote_abc123",
      "facilitatorUrl" 
       
       
    
  
   
     
     
       
       
       
       
       
       
    
  

Note: The resource field is optional per the @x402/core schema, but the working e2e implementation includes it. It describes the API endpoint being paid for.

Full Flow: Quote → PaymentPayload → Submit

1. You receive a quote response (from Step 1):

{
  "data": {
    "id": "quote_78ab4393-b7c1-4949-a6df-9ffa56642252",
    "amount_crypto": "50000000",
    "payment_requirements": {
      "accepts": [{
        "scheme": "exact",
        "network": "eip155:8453",
        "amount": "50000000",
        "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "payTo": "0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97",
        "maxTimeoutSeconds": 300,
        "extra": { "quoteId": "quote_78ab4393-b7c1-4949-a6df-9ffa56642252", "facilitatorUrl": "https://www.x402.org/facilitator", "name"    
      
    
  

2. You construct the PaymentPayload:

accepted — Copy payment_requirements.accepts[0] from your quote response exactly as the accepted value. Do not modify or omit any fields.

payload — Constructed by the client:

PaymentPayload field	Source
payload.signature	Your EIP-712 signature (0x-prefixed)
payload.authorization.from	Your wallet address
payload.authorization.to	Same as accepted.payTo
payload.authorization.value	Same as accepted.amount
payload.authorization.validAfter	"0" (immediate)
payload.authorization.validBefore	Unix timestamp (quote expiry)
payload.authorization.nonce	Random 32-byte hex (0x-prefixed)

resource (optional) — The working e2e implementation includes a top-level resource object describing the API endpoint being paid for. The @x402/core schema considers this optional, but including it is recommended.

3. Base64-encode and submit:

PAYMENT_PAYLOAD='{"x402Version":2,"resource":{"url":"https://api.telnyx.com/v2/x402/credit_account","description":"Credit account via x402 payment","mimeType":"application/json"},"accepted":{"scheme":"exact","network":"eip155:8453","amount":"50000000","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97","maxTimeoutSeconds":300,"extra":{"quoteId":"quote_78ab4393-b7c1-4949-a6df-9ffa56642252","facilitatorUrl":"https://www.x402.org/facilitator","name":"USD Coin","version":"2"}},"payload":{"signature":"0xe0fbde58a3c04dc2bae26f25ed36c7802f9214c88b3e26e6e9f79a2838a9c4651d2f7e8a90b45c31d8e5f720ca9d9b13f6d8a2e5c1b4f7e8d9a0b3c6d5e4f2a71b","authorization":{"from":"0x71C7656EC7ab88b098defB751B7401B5f6d8976F","to":"0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97","value":"50000000","validAfter":"0","validBefore":"1773166865","nonce":"0x8a3b5c7d9e1f2a4b6c8d0e2f4a6b8c0d2e4f6a8b0c2d4e6f8a0b2c4d6e8f0a1b"}}}'

# tr strips the line wraps GNU base64 inserts at 76 chars — they would corrupt the JSON below
ENCODED=$(echo -n "$PAYMENT_PAYLOAD" | base64 | tr -d '\n')

curl -X POST "https://api.telnyx.com/v2/x402/credit_account" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"quote_78ab4393-b7c1-4949-a6df-9ffa56642252","payment_signature":"'"$ENCODED"'"}' | jq .

Step 3: Submit the Payment

Request Body

POST /v2/x402/credit_account

The request body is a JSON object with exactly two required fields:

Field	Type	Required	Description
id	string	Yes	The quote ID returned from the quote endpoint. Format: quote_<uuid> (e.g. quote_78ab4393-b7c1-4949-a6df-9ffa56642252)
payment_signature	string	Yes	Base64-encoded JSON string of the PaymentPayload v2 structure (see Building the payment_signature Payload above)

Both fields are required. The id must reference a valid, unexpired quote. The payment_signature must be the entire PaymentPayload v2 JSON (with the accepted wrapper), base64-encoded.

Complete Example

See the full flow example in Step 2 above for the complete quote → payload → submit workflow.

Note: The PAYMENT-SIGNATURE header approach is not currently supported at the API gateway level. Use the payment_signature body parameter instead.

Settlement Status

Success response (201 Created):

{
  "data": {
    "id": "txn_uuid",
    "record_type": "x402_transaction",
    "amount": "50.00",
    "currency": "USD",
    "status": "settled",
    "quote_id": "quote_abc123",
    "tx_hash": "0x...",
    "created_at": "2026-03-09T19:00:00Z"
  }
}

The status field can be:

• verified — Payment signature verified, settlement pending on-chain
• settled — On-chain transaction confirmed, platform credit applied

Settlement is nearly instant (~2 seconds on Base L2). Platform credit is applied upon reaching settled status.

Error Handling

Error Code	HTTP Status	Meaning	Resolution
amount_usd must be at least <min>	422	Below the current minimum	Retry with an amount at or above the minimum the error states
amount_usd must not exceed <max>	422	Above the current maximum	Retry with an amount at or below the maximum the error states
insufficient_balance	422	Wallet lacks USDC	Fund the wallet with USDC on Base
insufficient_funds	422	Wallet lacks USDC (alias)	Fund the wallet with USDC on Base
insufficient_allowance	422	USDC token allowance insufficient	Approve USDC spending for the facilitator contract
expired_authorization	400	Quote/authorization expired	Request a new quote
invalid_signature	400	Signature check failed	Verify EIP-712 domain, types, and signing parameters
invalid_nonce	400	Authorization already used or cancelled	Generate a new nonce and re-sign
facilitator_unavailable	502	On-chain facilitator unreachable	Retry after a moment
facilitator_timeout	503	Payment processing timed out	Funds not transferred; retry
settlement_timeout	503	Settlement taking too long	Check wallet balance before retrying
transaction_failed	502	On-chain transaction failed	Funds not transferred; retry or contact support

Common Mistakes

❌ Wrong: Putting fields at root level (v1-style)

{
  "x402Version": 2,
  "scheme": "exact",
  "network": "eip155:8453",
  "payload": {
    "signature": "e0fbde...",
    "authorization": { "from": "...", "to": "...", "value": "..." }
  }
}

Error: "Invalid PaymentPayload structure: accepted: Required"

Fix: Wrap scheme, network, and payment requirement fields inside an accepted object. Keep payload at the top level alongside accepted.

❌ Wrong: Nesting payload inside accepted

{
  "x402Version": 2,
  "accepted": {
    "scheme": "exact",
    "network": "eip155:8453",
    "amount": "50000000",
    "payload": { "signature": "0x...", "authorization": { ... } }
  }
}

Error: "Invalid PaymentPayload structure: payload: Required"

Fix: payload is a top-level sibling of accepted, not nested inside it. Move payload out to the root level of the JSON object.

❌ Missing 0x prefix on signature

"signature": "e0fbde58a3..."

Fix: Always include the 0x prefix: "signature": "0xe0fbde58a3..."

❌ Mismatched values from the quote

If amount, payTo, or network in your payload don't match the quote's values, you'll get validation errors (e.g., amount mismatch, network mismatch). Always copy these values directly from payment_requirements.accepts[0].

Important Notes

• Payments are in USDC on the Base blockchain (Layer 2)
• The facilitator (x402.org) handles on-chain settlement
• The quote ID is idempotent — submitting the same quote twice returns the existing transaction
• This is a documentation-only skill; the signing step requires a crypto wallet library