Using Thirdfy with External Agents

Guide for external AI agents to integrate with Thirdfy using x402 payments. Add USD execution balance, use chat, or Execute Intents.

Overview

External AI agents can add Thirdfy execution balance via the x402 payment protocol. No Thirdfy account or Privy integration is required for the purchase step. You need a wallet with USDC on Base. The balance powers chat, execution, and other Thirdfy APIs.

Requirements

  • Wallet with USDC on Base network
  • HTTP client for API calls
  • Your wallet address

No Thirdfy account or special authentication required for buy-with-x402.

Top-up options

Fetch live top-up options. The current presets are $10, $25, and $50, with custom whole-dollar amounts from $10 to $1,000.

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

Integration flow (default v2)

Step 1: Discover Thirdfy

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

Or find Thirdfy on x402scan.com.

Step 2: Request purchase (receive 402)

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

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

Read the PAYMENT-REQUIRED response header. It contains v2 accepts[] with amount (USDC base units) and payTo on eip155:8453.

Step 3: Sign EIP-3009 and retry

Sign USDC TransferWithAuthorization, then retry:

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

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

Success returns 200 and PAYMENT-RESPONSE with the settlement transaction hash.

Legacy fallback (direct USDC transfer)

Use when your runtime cannot sign EIP-3009 (some autonomous agent stacks).

  1. Read the 402 challenge (payTo + amount).
  2. Send a USDC transfer on Base.
  3. Retry with txHash and x402Mode: "txhash-claim":
POST https://api.thirdfy.com/api/v1/credits/buy-with-x402
Content-Type: application/json

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

If the chain indexer is behind, you may get 202 PAYMENT_SETTLEMENT_PENDING. Retry with the same txHash.

After purchase

Use your Thirdfy balance with chat, Execute Intent, and other APIs per your integration. See x402 API for error codes and discovery details.

Credits for Users
Execution balance drives Thirdfy usage. Users see USD balance while credits remain the internal ledger unit.
Introduction
Thirdfy Skills library and Actions API for agents to execute on-chain DeFi transactions