x402 API

Overview

x402 credit purchases use open HTTP endpoints (no API key). Agents buy execution balance with USDC on Base. Users can also top up from thirdfy.com/credits or Thirdfy Console.

Discovery Endpoint

GET https://api.thirdfy.com/api/v1/credits/x402-metadata

Returns active top-up SKUs from x402_skus with USD labels (topup_usd_10, topup_usd_25, topup_usd_50, and custom bounds).

Purchase Endpoint

POST https://api.thirdfy.com/api/v1/credits/buy-with-x402
Content-Type: application/json

{
  "sku": "topup_usd_25",
  "userAddress": "0xYOUR_WALLET_ADDRESS"
}

Or custom amount:

{
  "usdAmount": 100,
  "userAddress": "0xYOUR_WALLET_ADDRESS"
}

Legacy credits_* SKUs are retired. Use topup_usd_* only.

Payment Flow (default v2 facilitator)

Step 1: Receive the challenge

The first POST with a valid sku or usdAmount and no payment proof returns HTTP 402.

Read the PAYMENT-REQUIRED response header (base64-encoded JSON). It includes x402 v2 accepts[] with:

• network: eip155:8453
• amount: USDC base units (6 decimals)
• payTo: Thirdfy payment wallet

Step 2: Sign EIP-3009

Sign TransferWithAuthorization for USDC on Base using the advertised amount and payTo.

Step 3: Retry with payment signature

POST https://api.thirdfy.com/api/v1/credits/buy-with-x402
Content-Type: application/json
PAYMENT-SIGNATURE: <base64 payment payload>

{
  "sku": "topup_usd_25",
  "userAddress": "0xYOUR_WALLET_ADDRESS"
}

On success the API returns HTTP 200 and a PAYMENT-RESPONSE header with settlement details.

Legacy fallback (txHash claim)

Use when your wallet cannot sign EIP-3009 (some autonomous agent runtimes).

1. Request a challenge for the selected SKU (do not rely on an empty body to pick an amount).
2. Send a direct USDC transfer on Base to payTo.
3. Retry with the transaction hash:

POST https://api.thirdfy.com/api/v1/credits/buy-with-x402
Content-Type: application/json
X-Payment-Receipt: 0xYOUR_TX_HASH

{
  "sku": "topup_usd_25",
  "userAddress": "0xYOUR_WALLET_ADDRESS",
  "txHash": "0xYOUR_TX_HASH",
  "x402Mode": "txhash-claim"
}

If the transaction is not indexed yet, the API may return 202 PAYMENT_SETTLEMENT_PENDING. Retry with the same txHash.

Payment Details

• Currency: USDC on Base
• Network: Base (Chain ID 8453)
• Display: Users see USD balance; credits are the internal ledger unit
• Fees: No protocol fees on the listed top-up price

Error codes (common)