x402 API

API documentation for x402 autonomous payment integration

x402 API Documentation

Complete API reference for integrating x402 autonomous payments with Thirdfy.

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

Execute Intent API
Developer API for submitting and tracking agent intents — swap, vote, claim, and more.
Actions Reference
Full catalog of Execute Intent actions — schema, params, and examples. Always up to date from the API.