x402 API

API documentation for x402 autonomous payment integration

Overview

x402 credit purchases use open HTTP endpoints (no API key). Agents typically buy credits this way or through Thirdfy product UI—not through execute-intent.

HTTP reference for x402 autonomous payments on Base.

Discovery Endpoint

Find Thirdfy's x402 service metadata:

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

Returns available credit packages and payment details.

Purchase Endpoint

Purchase credits using x402 protocol:

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

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

Credit Packages

SKUCreditsPrice (USDC)
credits_1001002.00
credits_10001,00018.00
credits_1000010,000160.00

Payment Flow

Step 1: Request Purchase

First call returns HTTP 402 with payment challenge:

{
  "x402Challenge": {
    "invoiceId": "inv_credits_1000_abc123",
    "amount": "18",
    "recipient": "0x572D1443f0aAfd492E396516ED26Dc269C516fd7",
    "currency": "USDC",
    "network": "base"
  }
}

Step 2: Pay USDC

Transfer USDC to the recipient address on Base:

const tx = await usdcContract.transfer(
  challenge.recipient,
  parseUnits(challenge.amount, 6)
);

Step 3: Confirm Purchase

Retry request with payment proof:

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

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

Response (HTTP 200):

{
  "success": true,
  "credits": 1000,
  "balance": 1000,
  "message": "✅ Successfully purchased 1000 credits"
}

Payment Details

  • Currency: USDC on Base
  • Network: Base (Chain ID 8453)
  • Settlement: ~2 seconds
  • Fees: No protocol fees
  • Payment Address: 0x572D1443f0aAfd492E396516ED26Dc269C516fd7

Example: Python Integration

import requests
from web3 import Web3

THIRDFY_API = "https://api.thirdfy.com"
MY_WALLET = "0xYOUR_WALLET_ADDRESS"

# 1. Request purchase
response = requests.post(
    f"{THIRDFY_API}/api/v1/credits/buy-with-x402",
    json={"sku": "credits_1000", "userAddress": MY_WALLET}
)

challenge = response.json()['x402Challenge']

# 2. Pay USDC on Base
w3 = Web3(Web3.HTTPProvider("https://mainnet.base.org"))
usdc = w3.eth.contract(address=USDC_BASE, abi=ERC20_ABI)

tx_hash = usdc.functions.transfer(
    challenge['recipient'],
    int(float(challenge['amount']) * 1e6)
).transact({'from': MY_WALLET})

w3.eth.wait_for_transaction_receipt(tx_hash)

# 3. Confirm purchase
response = requests.post(
    f"{THIRDFY_API}/api/v1/credits/buy-with-x402",
    json={"sku": "credits_1000", "userAddress": MY_WALLET},
    headers={
        "X-Payment-Receipt": tx_hash.hex(),
        "X-Invoice-Id": challenge['invoiceId']
    }
)

print(f"Credits: {response.json()['credits']}")
print(f"Balance: {response.json()['balance']}")

Resources

Delegation API
HTTP mirror for Gator/ERC-7710 delegation. Prefer MCP delegation tools or Agent CLI delegation commands.
Actions Reference
Full catalog of Execute Intent actions — schema, params, and examples. Always up to date from the API.