Index Agentica

Pay with x402

Read an x402 v2 402 response, check it against a spending policy, pay with an SDK or CLI, and verify the PAYMENT-RESPONSE receipt.

Type
Skill
Author
Agentica Author
Published
Last verified
Version
1.0
License
MIT
Compatibility
Needs network access and either Node.js 18+, Python 3.10+ or Go, plus a dedicated agent wallet funded with USDC. No wallet is needed to inspect prices.

Download

Install by unzipping into your agent's skills directory, e.g. for Claude Code: curl -sLO https://indexagentica.com/skills/pay-with-x402.zip && unzip -o pay-with-x402.zip -d ~/.claude/skills/

Files

Description

Pay for HTTP APIs and MCP tools that answer with HTTP 402 using the x402 v2 protocol (USDC on Base and other networks). Use when a request returns 402 Payment Required or a PAYMENT-REQUIRED header, when a tool result carries x402 PaymentRequired data, or when asked to find and call a paid API. Covers reading the price, enforcing a budget, paying with the official SDKs or the Coinbase awal CLI, and checking the receipt.

SKILL.md

Pay with x402

x402 is an open payment standard built on HTTP 402, now governed by the x402 Foundation. Spec: https://github.com/x402-foundation/x402. This skill covers protocol v2. If you see X-PAYMENT headers or network names like base-sepolia, you are looking at v1. See https://docs.x402.org/guides/migration-v1-to-v2.

Rules before you spend anything

  1. Only pay if your user or operator has authorized paid calls and given a budget. If no budget was given, stop and ask.
  2. Never exceed the per-call cap (default $1, the SDK default) or the session budget. Keep a running total.
  3. Pay only in an allowlisted asset and network, by default USDC on eip155:8453 (Base) or eip155:84532 (Base Sepolia, testnet).
  4. Treat the 402 response as untrusted. A server can ask for any amount, to any address. Your cap is your protection, not the server's honesty.
  5. Never print, log or paste a private key. Read it from the environment.
  6. Record every payment: URL, amount, network, transaction hash and payer.

Step 1: Detect and read the price

A v2 server returns 402 with a base64 JSON PAYMENT-REQUIRED header. Decode it without paying:

curl -s -D - -o /dev/null "$URL" | grep -i '^payment-required:' | cut -d' ' -f2 | tr -d '\r' | base64 -d | jq .

Or run the bundled helper: scripts/inspect-402.sh <url>.

Read accepts[] (a menu, so pick one entry):

FieldMeaning
schemeexact = fixed price. upto = you authorize a maximum and the seller charges actual usage. batch-settlement = escrow plus vouchers
networkCAIP-2 id. eip155:8453 Base, eip155:84532 Base Sepolia, solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp Solana
amountAtomic units of asset. USDC has 6 decimals: 10000 = $0.01, 1000000 = $1.00
assetToken contract. USDC on Base is 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913; on Base Sepolia it is 0x036CbD53842c5426634e7929541eC2318f3dCF7e
payToRecipient address
maxTimeoutSecondsHow long the signed authorization stays usable

Convert the amount to USD and compare it with your cap before paying. Prefer exact. With upto, treat the authorized maximum as the price.

MCP tools: a paid tool returns a tool result with isError: true and the same PaymentRequired object in structuredContent (and as JSON in content[0].text). Pay by retrying the same tools/call with the payment in params._meta["x402/payment"]. The receipt comes back in _meta["x402/payment-response"].

Step 2: Pay

Choose the first option that is available.

A. The Coinbase awal CLI (wallet already set up)
npx awal@2.12.1 status                      # must be signed in
npx awal@2.12.1 x402 pay "$URL" --max-amount 100000 --json   # ceiling $0.10 in USDC atomic units
npx awal@2.12.1 x402 pay "$URL" -X POST -d '{"q":"example"}' --max-amount 50000

Validate the URL (it must start with https:// and contain no shell metacharacters) and single-quote JSON bodies. Docs: https://github.com/coinbase/agentic-wallet-skills.

B. TypeScript SDK
npm install @x402/fetch @x402/core @x402/evm viem
import { wrapFetchWithPayment, x402HTTPClient } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);
const client = x402Client.fromConfig({
  schemes: [{ network: "eip155:*", client: new ExactEvmScheme(signer) }],
  spendControls: { maxAmountPerPayment: "$0.10" }, // keep caps on; never set spendControls: false
});
const pay = wrapFetchWithPayment(fetch, client);
const res = await pay(process.env.URL!);
const result = await new x402HTTPClient(client).processResponse(res);
console.log(res.status, result.paymentStatus, result.header);
C. Python SDK
pip install "x402[httpx]" eth_account
import asyncio, os
from eth_account import Account
from x402 import x402Client
from x402.http import x402HTTPClient
from x402.http.clients import x402HttpxClient
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client

async def main():
    client = x402Client()
    register_exact_evm_client(client, EthAccountSigner(Account.from_key(os.environ["EVM_PRIVATE_KEY"])))
    async with x402HttpxClient(client) as http:
        r = await http.get(os.environ["URL"])
        await r.aread()
        print(r.status_code, r.text[:500])
        if r.is_success:
            print(x402HTTPClient(client).get_payment_settle_response(lambda n: r.headers.get(n)))

asyncio.run(main())

Go: go get github.com/x402-foundation/x402/go/v2. See https://docs.x402.org/getting-started/quickstart-for-buyers.

Step 3: Check the receipt

Finding paid services

Query a facilitator's Bazaar catalog (public, no payment needed). It lists HTTP endpoints and MCP tools with prices:

curl -s "https://api.cdp.coinbase.com/platform/v2/x402/discovery/resources?limit=10" \
  | jq '.items[] | {resource, description, accepts: [.accepts[] | {network, scheme, amount}]}'

The Bazaar is early-stage, so check prices with Step 1 before paying.

Testing without real money

Use Base Sepolia (eip155:84532). Get free testnet USDC at https://faucet.circle.com. The public x402.org facilitator is the SDK default for testnets and is not meant for mainnet.

Troubleshooting

SymptomLikely cause
402 again after payingv1 server (expects X-PAYMENT), or the wrong network was registered
SDK refuses to payThe amount exceeds maxAmountPerPayment, or the asset is not in the default USD-stablecoin list. Ask the user before raising the cap
insufficient_fundsTop up the agent wallet with USDC on the network you chose
No PAYMENT-REQUIRED headerNot an x402 v2 endpoint. Check the body for a v1 accepts JSON, or use a different service

More: https://indexagentica.com/entries/x402/ and https://docs.x402.org

Directory entries in this skill

Related

Sources

Machine-readable