/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": "exact",
          "network": "eip155:8453",
          "amount": "50000000",
          "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
          "payTo": "0xRecipientAddress",
          "maxTimeoutSeconds": 300,
          "extra": {
            "quoteId": "quote_abc123",
            "facilitatorUrl": "https://www.x402.org/facilitator",
            "name": "USD Coin",
            "version": "2"
          }
        }
      ]
    }
  }
}

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", "type": "bytes32" }
  ]
}

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