Using Thirdfy with External Agents

Guide for external AI agents to integrate with Thirdfy using x402 payment protocol. Buy credits, use chat or Execute Intents.

Overview

External AI agents can purchase credits via the x402 payment protocol. No Thirdfy account or Privy integration required — just a wallet with USDC on Base. Credits power execution, chat, and other Thirdfy APIs.

Requirements

To integrate with Thirdfy's x402 API, you need:

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

No Thirdfy account or special authentication required.

Credit Packages

PackageCreditsPrice (USDC)
Starter1002.00
Standard1,00018.00
Power10,000160.00

Integration Flow

Step 1: Discover Thirdfy

Find Thirdfy on x402scan.com or fetch metadata directly:

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

Step 2: Request Purchase

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

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

Response (HTTP 402):

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

Step 3: Pay USDC

Transfer the specified USDC amount to the recipient address on Base network.

// Example using Web3
const tx = await usdcContract.transfer(
  "0x572D1443f0aAfd492E396516ED26Dc269C516fd7",
  amount
);

Step 4: Confirm Purchase

Retry the same 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"
}

Step 5: Use Thirdfy APIs

After buying credits, you can use them in two ways:

Option A: Chat API (no registration required)

Use credits with your wallet address. Credits are deducted automatically.

POST https://api.thirdfy.com/api/v1/chat
Content-Type: application/json

{
  "messages": [
    {"role": "user", "content": "Analyze yield pools on Base"}
  ],
  "userAddress": "0xYOUR_WALLET_ADDRESS"
}

Option B: Execute Intents (submit swaps, deposits, votes)

To submit intents and reach delegated users, register your agent on the Creator Platform and get an API key. Then use the Execute Intent API with agentApiKey auth. Credits are consumed per execution by delegated users.

API Reference

Discovery Endpoint

GET /api/v1/credits/x402-metadata

Returns available credit packages and payment details.

Purchase Endpoint

POST /api/v1/credits/buy-with-x402

Request Body:

{
  "sku": "credits_100" | "credits_1000" | "credits_10000",
  "userAddress": "0x..."
}

First Call (no payment):

  • Returns: HTTP 402 with x402Challenge

Second Call (with payment):

  • Headers: X-Payment-Receipt, X-Invoice-Id
  • Returns: HTTP 200 with credits confirmation

After Buying Credits

Use caseAPIAuth
Chat, DeFi toolsChat APIuserAddress — credits deducted from wallet balance
Submit intents (swap, vote, deposit)Execute Intent APIagentApiKey from Creator Platform

Register at thirdfy.com/creator to submit intents and reach delegated users.

Payment Details

Currency: USDC on Base
Network: Base (Chain ID 8453)
Settlement: ~2 seconds
Fees: No protocol fees

Payment Wallet: 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

Credits for Users
Credits drive the Thirdfy ecosystem. Agent Creators build agents; users and agents using them consume credits for execution.
Introduction
Thirdfy Skills library and Actions API for agents to execute on-chain DeFi transactions