Back to SDKs

For Agent Developers

Agent Quickstart

Make your first paid API call in under 5 minutes. No SDK required — just HTTP.

0

Get Testnet USDC (Free)

Get free test USDC on Base Sepolia from the Coinbase Faucet. No real money needed for testing.

When ready for production, just change base-sepolia to base. Same code, real payments.

1

Call an API (Get 402)

Call any Obolo endpoint without payment headers. You'll get a 402 Payment Required response with exact payment instructions.

bash
# Discover available APIs
curl https://gateflow-proxy.7crypto-jo.workers.dev/v1/weather-provider/forecast

Response (402):

json
{
  "error": "Payment Required",
  "payment_options": [
    {
      "chain": "base",
      "token": "USDC",
      "amount": "1000",
      "recipient": "0xTREASURY...",
      "contract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
    }
  ]
}
2

Pay + Retry

Send USDC to the recipient address on the specified chain. Then retry your request with three headers:

X-Payment-Hash — transaction hash proving your on-chain payment
X-Payment-Chain — which blockchain (base, arbitrum, solana, etc.)
X-Agent-Wallet — your wallet address (for reputation tracking)
bash
# After sending USDC on Base, retry with payment proof + wallet proof.
# Sign the GateFlow-Wallet-Proof-v1 challenge first (see /docs/wallet-proof).
curl https://gateflow-proxy.7crypto-jo.workers.dev/v1/weather-provider/forecast?q=London \
  -H "X-Payment-Hash: 0xYOUR_TX_HASH" \
  -H "X-Payment-Chain: base" \
  -H "X-Agent-Wallet: 0xYOUR_WALLET" \
  -H "X-Wallet-Signature: 0xYOUR_EIP191_SIGNATURE" \
  -H "X-Wallet-Proof-Issued: 1730000000"

Response (200):

json
{
  "temp": 15.2,
  "humidity": 72,
  "condition": "cloudy",
  "wind_speed": 12.5
}

Headers:
  X-Payment-Verified: true
  X-GateFlow-Cache: MISS

Full Examples

JavaScript / TypeScript
javascript
// Full agent payment flow in JavaScript
const PROXY = 'https://gateflow-proxy.7crypto-jo.workers.dev';

// Step 1: Get payment requirements
const info = await fetch(`${PROXY}/v1/weather-provider/forecast`);
const { payment_options } = await info.json();
// payment_options[0] = { chain: "base", token: "USDC", amount: "1000", recipient: "0x..." }

// Step 2: Send USDC on-chain (use ethers, viem, or any wallet library)
const tx = await sendUSDC(payment_options[0].recipient, payment_options[0].amount);

// Step 3: Prove you control the paying wallet (EIP-191) — required whenever
// you send X-Agent-Wallet. See /docs/wallet-proof for the full spec.
const issued = Math.floor(Date.now() / 1000);
const challenge = [
  'GateFlow-Wallet-Proof-v1',
  `wallet=${myWallet.address.toLowerCase()}`,
  'method=GET',
  'path=weather-provider/forecast',
  `payment=${tx.hash}`,
  `issued=${issued}`,
].join('\n');
const sig = await myWallet.signMessage(challenge); // EIP-191 personal_sign

// Step 4: Retry with payment proof + wallet proof
const data = await fetch(`${PROXY}/v1/weather-provider/forecast?q=London`, {
  headers: {
    'X-Payment-Hash': tx.hash,
    'X-Payment-Chain': 'base',
    'X-Agent-Wallet': myWallet.address,
    'X-Wallet-Signature': sig,
    'X-Wallet-Proof-Issued': String(issued),
  },
}).then(r => r.json());

console.log(data); // { temp: 15.2, humidity: 72, ... }
Python
python
import httpx

PROXY = "https://gateflow-proxy.7crypto-jo.workers.dev"

# Step 1: Get payment requirements
info = httpx.get(f"{PROXY}/v1/weather-provider/forecast").json()
option = info["payment_options"][0]
# option = { "chain": "base", "token": "USDC", "amount": "1000", "recipient": "0x..." }

# Step 2: Send USDC on-chain (use web3.py, solders, etc.)
tx_hash = send_usdc(option["recipient"], option["amount"])

# Step 3: Prove wallet control (EIP-191) — required whenever you send
# X-Agent-Wallet. See /docs/wallet-proof for the full spec.
from eth_account import Account
from eth_account.messages import encode_defunct
import time

issued = int(time.time())
challenge = "\n".join([
    "GateFlow-Wallet-Proof-v1",
    f"wallet={my_wallet.lower()}",
    "method=GET",
    "path=weather-provider/forecast",
    f"payment={tx_hash}",
    f"issued={issued}",
])
sig = Account.from_key(PRIVATE_KEY).sign_message(encode_defunct(text=challenge))

# Step 4: Retry with payment proof + wallet proof
data = httpx.get(
    f"{PROXY}/v1/weather-provider/forecast",
    params={"q": "London"},
    headers={
        "X-Payment-Hash": tx_hash,
        "X-Payment-Chain": "base",
        "X-Agent-Wallet": my_wallet,
        "X-Wallet-Signature": sig.signature.hex(),
        "X-Wallet-Proof-Issued": str(issued),
    },
).json()

print(data)  # {"temp": 15.2, "humidity": 72, ...}

What's Next