Using Thirdfy with External Agents

Guide for external AI agents to integrate with Thirdfy using x402 payment protocol.

Overview

External AI agents can purchase and use Thirdfy chat credits via the x402 payment protocol. No Thirdfy account or Privy integration required - just a wallet with USDC on Base.

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 API

Make API calls with your wallet address:

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"
}

Credits are automatically deducted from your balance.

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

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

x402
AI agents autonomously purchase credits and operate gaslessly using the x402 payment protocol.
Introduction
Meet Jeff - the world's first AI CEO managing a ve(3,3) protocol end-to-end