{ "type": "skill", "id": "pay-with-x402", "title": "Pay with x402", "summary": "Read an x402 v2 402 response, check it against a spending policy, pay with an SDK or CLI, and verify the PAYMENT-RESPONSE receipt.", "author": "Agentica Author", "tags": [ "x402", "payments", "usdc", "http-402", "agent-commerce" ], "published": "2026-10-02", "last_verified": "2026-10-02", "entries": [ "x402", "cdp-x402", "x402-bazaar", "coinbase-agentic-wallet", "coinbase-agentic-wallet-skills", "usdc" ], "links": { "html": "https://indexagentica.com/skills/pay-with-x402/", "markdown": "https://indexagentica.com/skills/pay-with-x402.md", "json": "https://indexagentica.com/api/longform/skills/pay-with-x402.json", "skill_md": "https://indexagentica.com/skills/pay-with-x402/SKILL.md", "zip": "https://indexagentica.com/skills/pay-with-x402.zip", "source": "https://github.com/Drudley/indexagentica/blob/main/content-long/skills/pay-with-x402/SKILL.md" }, "status": "published", "skill": { "name": "pay-with-x402", "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.", "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.", "version": "1.0", "files": [ { "path": "scripts/inspect-402.sh", "url": "https://indexagentica.com/skills/pay-with-x402/scripts/inspect-402.sh" }, { "path": "SKILL.md", "url": "https://indexagentica.com/skills/pay-with-x402/SKILL.md" } ], "skill_md": "https://indexagentica.com/skills/pay-with-x402/SKILL.md", "zip": "https://indexagentica.com/skills/pay-with-x402.zip" }, "entries_detail": [ { "id": "x402", "name": "x402", "summary": "Open standard for internet-native payments built on HTTP 402, letting APIs and agents pay per request across crypto and fiat networks.", "url": "https://indexagentica.com/entries/x402/", "json": "https://indexagentica.com/api/entries/x402.json" }, { "id": "cdp-x402", "name": "Coinbase CDP x402 Facilitator", "summary": "Coinbase Developer Platform's x402 offering: a hosted facilitator that verifies and settles x402 payments, plus seller and buyer SDK quickstarts.", "url": "https://indexagentica.com/entries/cdp-x402/", "json": "https://indexagentica.com/api/entries/cdp-x402.json" }, { "id": "x402-bazaar", "name": "x402 Bazaar", "summary": "Public catalog of x402 payment-gated services discovered by the CDP Facilitator; search by intent, browse resources or look up by merchant address.", "url": "https://indexagentica.com/entries/x402-bazaar/", "json": "https://indexagentica.com/api/entries/x402-bazaar.json" }, { "id": "coinbase-agentic-wallet", "name": "Coinbase Agentic Wallet", "summary": "Wallet tooling that lets AI agents hold, spend, trade and earn stablecoins with guardrails, via the awal CLI + skills or an MCP server.", "url": "https://indexagentica.com/entries/coinbase-agentic-wallet/", "json": "https://indexagentica.com/api/entries/coinbase-agentic-wallet.json" }, { "id": "coinbase-agentic-wallet-skills", "name": "Coinbase Agentic Wallet Skills", "summary": "Pre-built agent skills for wallet operations (authenticate, fund, send USDC, trade, pay for x402 services) via Coinbase's awal CLI.", "url": "https://indexagentica.com/entries/coinbase-agentic-wallet-skills/", "json": "https://indexagentica.com/api/entries/coinbase-agentic-wallet-skills.json" }, { "id": "usdc", "name": "USDC", "summary": "Fully reserved dollar stablecoin issued by Circle, the settlement asset used by many agent payment rails including x402.", "url": "https://indexagentica.com/entries/usdc/", "json": "https://indexagentica.com/api/entries/usdc.json" } ], "related": [ { "type": "guide", "id": "pay-for-an-api-with-x402", "title": "Pay for an API as an agent with x402", "url": "https://indexagentica.com/guides/pay-for-an-api-with-x402/", "json": "https://indexagentica.com/api/longform/guides/pay-for-an-api-with-x402.json" }, { "type": "comparison", "id": "agent-payment-rails", "title": "Agent payment protocols compared", "url": "https://indexagentica.com/compare/agent-payment-rails/", "json": "https://indexagentica.com/api/longform/compare/agent-payment-rails.json" }, { "type": "stack", "id": "agent-that-can-buy-things", "title": "Agent that can buy things", "url": "https://indexagentica.com/stacks/agent-that-can-buy-things/", "json": "https://indexagentica.com/api/longform/stacks/agent-that-can-buy-things.json" } ], "sources": [ { "url": "https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v2.md" }, { "url": "https://github.com/x402-foundation/x402/blob/main/specs/transports-v2/http.md" }, { "url": "https://github.com/x402-foundation/x402/blob/main/specs/transports-v2/mcp.md" }, { "url": "https://docs.x402.org/getting-started/quickstart-for-buyers" }, { "url": "https://docs.x402.org/guides/migration-v1-to-v2" }, { "url": "https://docs.x402.org/extensions/bazaar" }, { "url": "https://docs.cdp.coinbase.com/x402/seller/facilitator" }, { "url": "https://github.com/coinbase/agentic-wallet-skills/blob/main/skills/agentic-wallet/references/x402-pay.md" } ], "front_matter": { "name": "pay-with-x402", "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.", "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.", "metadata": { "title": "Pay with x402", "summary": "Read an x402 v2 402 response, check it against a spending policy, pay with an SDK or CLI, and verify the PAYMENT-RESPONSE receipt.", "author": "Agentica Author", "version": "1.0", "last_verified": "2026-10-02", "published": "2026-10-02", "tags": "x402, payments, usdc, http-402, agent-commerce", "entries": "x402, cdp-x402, x402-bazaar, coinbase-agentic-wallet, coinbase-agentic-wallet-skills, usdc", "related": "pay-for-an-api-with-x402, agent-payment-rails, agent-that-can-buy-things", "sources": "https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v2.md https://github.com/x402-foundation/x402/blob/main/specs/transports-v2/http.md https://github.com/x402-foundation/x402/blob/main/specs/transports-v2/mcp.md https://docs.x402.org/getting-started/quickstart-for-buyers https://docs.x402.org/guides/migration-v1-to-v2 https://docs.x402.org/extensions/bazaar https://docs.cdp.coinbase.com/x402/seller/facilitator https://github.com/coinbase/agentic-wallet-skills/blob/main/skills/agentic-wallet/references/x402-pay.md" } }, "markdown": "\n# Pay with x402\n\nx402 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.\n\n## Rules before you spend anything\n\n1. **Only pay if your user or operator has authorized paid calls** and given a budget. If no budget was given, stop and ask.\n2. **Never exceed the per-call cap** (default $1, the SDK default) or the session budget. Keep a running total.\n3. **Pay only in an allowlisted asset and network**, by default USDC on `eip155:8453` (Base) or `eip155:84532` (Base Sepolia, testnet).\n4. **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.\n5. **Never print, log or paste a private key.** Read it from the environment.\n6. **Record every payment**: URL, amount, network, transaction hash and payer.\n\n## Step 1: Detect and read the price\n\nA v2 server returns `402` with a base64 JSON `PAYMENT-REQUIRED` header. Decode it without paying:\n\n```bash\ncurl -s -D - -o /dev/null \"$URL\" | grep -i '^payment-required:' | cut -d' ' -f2 | tr -d '\\r' | base64 -d | jq .\n```\n\nOr run the bundled helper: `scripts/inspect-402.sh `.\n\nRead `accepts[]` (a menu, so pick one entry):\n\n| Field | Meaning |\n|---|---|\n| `scheme` | `exact` = fixed price. `upto` = you authorize a maximum and the seller charges actual usage. `batch-settlement` = escrow plus vouchers |\n| `network` | CAIP-2 id. `eip155:8453` Base, `eip155:84532` Base Sepolia, `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` Solana |\n| `amount` | **Atomic units** of `asset`. USDC has 6 decimals: `10000` = $0.01, `1000000` = $1.00 |\n| `asset` | Token contract. USDC on Base is `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`; on Base Sepolia it is `0x036CbD53842c5426634e7929541eC2318f3dCF7e` |\n| `payTo` | Recipient address |\n| `maxTimeoutSeconds` | How long the signed authorization stays usable |\n\nConvert the amount to USD and compare it with your cap **before** paying. Prefer `exact`. With `upto`, treat the authorized maximum as the price.\n\n**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\"]`.\n\n## Step 2: Pay\n\nChoose the first option that is available.\n\n### A. The Coinbase awal CLI (wallet already set up)\n\n```bash\nnpx awal@2.12.1 status # must be signed in\nnpx awal@2.12.1 x402 pay \"$URL\" --max-amount 100000 --json # ceiling $0.10 in USDC atomic units\nnpx awal@2.12.1 x402 pay \"$URL\" -X POST -d '{\"q\":\"example\"}' --max-amount 50000\n```\n\nValidate 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.\n\n### B. TypeScript SDK\n\n```bash\nnpm install @x402/fetch @x402/core @x402/evm viem\n```\n\n```typescript\nimport { wrapFetchWithPayment, x402HTTPClient } from \"@x402/fetch\";\nimport { x402Client } from \"@x402/core/client\";\nimport { ExactEvmScheme } from \"@x402/evm/exact/client\";\nimport { privateKeyToAccount } from \"viem/accounts\";\n\nconst signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);\nconst client = x402Client.fromConfig({\n schemes: [{ network: \"eip155:*\", client: new ExactEvmScheme(signer) }],\n spendControls: { maxAmountPerPayment: \"$0.10\" }, // keep caps on; never set spendControls: false\n});\nconst pay = wrapFetchWithPayment(fetch, client);\nconst res = await pay(process.env.URL!);\nconst result = await new x402HTTPClient(client).processResponse(res);\nconsole.log(res.status, result.paymentStatus, result.header);\n```\n\n### C. Python SDK\n\n```bash\npip install \"x402[httpx]\" eth_account\n```\n\n```python\nimport asyncio, os\nfrom eth_account import Account\nfrom x402 import x402Client\nfrom x402.http import x402HTTPClient\nfrom x402.http.clients import x402HttpxClient\nfrom x402.mechanisms.evm import EthAccountSigner\nfrom x402.mechanisms.evm.exact.register import register_exact_evm_client\n\nasync def main():\n client = x402Client()\n register_exact_evm_client(client, EthAccountSigner(Account.from_key(os.environ[\"EVM_PRIVATE_KEY\"])))\n async with x402HttpxClient(client) as http:\n r = await http.get(os.environ[\"URL\"])\n await r.aread()\n print(r.status_code, r.text[:500])\n if r.is_success:\n print(x402HTTPClient(client).get_payment_settle_response(lambda n: r.headers.get(n)))\n\nasyncio.run(main())\n```\n\nGo: `go get github.com/x402-foundation/x402/go/v2`. See https://docs.x402.org/getting-started/quickstart-for-buyers.\n\n## Step 3: Check the receipt\n\n- `200` plus a `PAYMENT-RESPONSE` header (base64 JSON) with `\"success\": true` and a `transaction` hash means you paid and got the resource. Log it.\n- `402` with `PAYMENT-RESPONSE` `\"success\": false` means the payment failed. Read `errorReason` (for example `insufficient_funds`). Don't retry in a loop.\n- `400` means the payload was malformed or doesn't match the requirements. Check the network, asset and scheme registration.\n- Settled, but the response is bad: report it to the user with the transaction hash. x402 has no built-in refund.\n\n## Finding paid services\n\nQuery a facilitator's Bazaar catalog (public, no payment needed). It lists HTTP endpoints and MCP tools with prices:\n\n```bash\ncurl -s \"https://api.cdp.coinbase.com/platform/v2/x402/discovery/resources?limit=10\" \\\n | jq '.items[] | {resource, description, accepts: [.accepts[] | {network, scheme, amount}]}'\n```\n\nThe Bazaar is early-stage, so check prices with Step 1 before paying.\n\n## Testing without real money\n\nUse 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.\n\n## Troubleshooting\n\n| Symptom | Likely cause |\n|---|---|\n| `402` again after paying | v1 server (expects `X-PAYMENT`), or the wrong network was registered |\n| SDK refuses to pay | The amount exceeds `maxAmountPerPayment`, or the asset is not in the default USD-stablecoin list. Ask the user before raising the cap |\n| `insufficient_funds` | Top up the agent wallet with USDC on the network you chose |\n| No `PAYMENT-REQUIRED` header | Not an x402 v2 endpoint. Check the body for a v1 `accepts` JSON, or use a different service |\n\nMore: https://indexagentica.com/entries/x402/ and https://docs.x402.org\n", "raw": "---\nname: pay-with-x402\ndescription: 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.\nlicense: MIT\ncompatibility: 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.\nmetadata:\n title: Pay with x402\n summary: Read an x402 v2 402 response, check it against a spending policy, pay with an SDK or CLI, and verify the PAYMENT-RESPONSE receipt.\n author: Agentica Author\n version: \"1.0\"\n last_verified: 2026-10-02\n published: 2026-10-02\n tags: x402, payments, usdc, http-402, agent-commerce\n entries: x402, cdp-x402, x402-bazaar, coinbase-agentic-wallet, coinbase-agentic-wallet-skills, usdc\n related: pay-for-an-api-with-x402, agent-payment-rails, agent-that-can-buy-things\n sources: https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v2.md https://github.com/x402-foundation/x402/blob/main/specs/transports-v2/http.md https://github.com/x402-foundation/x402/blob/main/specs/transports-v2/mcp.md https://docs.x402.org/getting-started/quickstart-for-buyers https://docs.x402.org/guides/migration-v1-to-v2 https://docs.x402.org/extensions/bazaar https://docs.cdp.coinbase.com/x402/seller/facilitator https://github.com/coinbase/agentic-wallet-skills/blob/main/skills/agentic-wallet/references/x402-pay.md\n---\n\n# Pay with x402\n\nx402 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.\n\n## Rules before you spend anything\n\n1. **Only pay if your user or operator has authorized paid calls** and given a budget. If no budget was given, stop and ask.\n2. **Never exceed the per-call cap** (default $1, the SDK default) or the session budget. Keep a running total.\n3. **Pay only in an allowlisted asset and network**, by default USDC on `eip155:8453` (Base) or `eip155:84532` (Base Sepolia, testnet).\n4. **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.\n5. **Never print, log or paste a private key.** Read it from the environment.\n6. **Record every payment**: URL, amount, network, transaction hash and payer.\n\n## Step 1: Detect and read the price\n\nA v2 server returns `402` with a base64 JSON `PAYMENT-REQUIRED` header. Decode it without paying:\n\n```bash\ncurl -s -D - -o /dev/null \"$URL\" | grep -i '^payment-required:' | cut -d' ' -f2 | tr -d '\\r' | base64 -d | jq .\n```\n\nOr run the bundled helper: `scripts/inspect-402.sh `.\n\nRead `accepts[]` (a menu, so pick one entry):\n\n| Field | Meaning |\n|---|---|\n| `scheme` | `exact` = fixed price. `upto` = you authorize a maximum and the seller charges actual usage. `batch-settlement` = escrow plus vouchers |\n| `network` | CAIP-2 id. `eip155:8453` Base, `eip155:84532` Base Sepolia, `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` Solana |\n| `amount` | **Atomic units** of `asset`. USDC has 6 decimals: `10000` = $0.01, `1000000` = $1.00 |\n| `asset` | Token contract. USDC on Base is `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`; on Base Sepolia it is `0x036CbD53842c5426634e7929541eC2318f3dCF7e` |\n| `payTo` | Recipient address |\n| `maxTimeoutSeconds` | How long the signed authorization stays usable |\n\nConvert the amount to USD and compare it with your cap **before** paying. Prefer `exact`. With `upto`, treat the authorized maximum as the price.\n\n**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\"]`.\n\n## Step 2: Pay\n\nChoose the first option that is available.\n\n### A. The Coinbase awal CLI (wallet already set up)\n\n```bash\nnpx awal@2.12.1 status # must be signed in\nnpx awal@2.12.1 x402 pay \"$URL\" --max-amount 100000 --json # ceiling $0.10 in USDC atomic units\nnpx awal@2.12.1 x402 pay \"$URL\" -X POST -d '{\"q\":\"example\"}' --max-amount 50000\n```\n\nValidate 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.\n\n### B. TypeScript SDK\n\n```bash\nnpm install @x402/fetch @x402/core @x402/evm viem\n```\n\n```typescript\nimport { wrapFetchWithPayment, x402HTTPClient } from \"@x402/fetch\";\nimport { x402Client } from \"@x402/core/client\";\nimport { ExactEvmScheme } from \"@x402/evm/exact/client\";\nimport { privateKeyToAccount } from \"viem/accounts\";\n\nconst signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);\nconst client = x402Client.fromConfig({\n schemes: [{ network: \"eip155:*\", client: new ExactEvmScheme(signer) }],\n spendControls: { maxAmountPerPayment: \"$0.10\" }, // keep caps on; never set spendControls: false\n});\nconst pay = wrapFetchWithPayment(fetch, client);\nconst res = await pay(process.env.URL!);\nconst result = await new x402HTTPClient(client).processResponse(res);\nconsole.log(res.status, result.paymentStatus, result.header);\n```\n\n### C. Python SDK\n\n```bash\npip install \"x402[httpx]\" eth_account\n```\n\n```python\nimport asyncio, os\nfrom eth_account import Account\nfrom x402 import x402Client\nfrom x402.http import x402HTTPClient\nfrom x402.http.clients import x402HttpxClient\nfrom x402.mechanisms.evm import EthAccountSigner\nfrom x402.mechanisms.evm.exact.register import register_exact_evm_client\n\nasync def main():\n client = x402Client()\n register_exact_evm_client(client, EthAccountSigner(Account.from_key(os.environ[\"EVM_PRIVATE_KEY\"])))\n async with x402HttpxClient(client) as http:\n r = await http.get(os.environ[\"URL\"])\n await r.aread()\n print(r.status_code, r.text[:500])\n if r.is_success:\n print(x402HTTPClient(client).get_payment_settle_response(lambda n: r.headers.get(n)))\n\nasyncio.run(main())\n```\n\nGo: `go get github.com/x402-foundation/x402/go/v2`. See https://docs.x402.org/getting-started/quickstart-for-buyers.\n\n## Step 3: Check the receipt\n\n- `200` plus a `PAYMENT-RESPONSE` header (base64 JSON) with `\"success\": true` and a `transaction` hash means you paid and got the resource. Log it.\n- `402` with `PAYMENT-RESPONSE` `\"success\": false` means the payment failed. Read `errorReason` (for example `insufficient_funds`). Don't retry in a loop.\n- `400` means the payload was malformed or doesn't match the requirements. Check the network, asset and scheme registration.\n- Settled, but the response is bad: report it to the user with the transaction hash. x402 has no built-in refund.\n\n## Finding paid services\n\nQuery a facilitator's Bazaar catalog (public, no payment needed). It lists HTTP endpoints and MCP tools with prices:\n\n```bash\ncurl -s \"https://api.cdp.coinbase.com/platform/v2/x402/discovery/resources?limit=10\" \\\n | jq '.items[] | {resource, description, accepts: [.accepts[] | {network, scheme, amount}]}'\n```\n\nThe Bazaar is early-stage, so check prices with Step 1 before paying.\n\n## Testing without real money\n\nUse 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.\n\n## Troubleshooting\n\n| Symptom | Likely cause |\n|---|---|\n| `402` again after paying | v1 server (expects `X-PAYMENT`), or the wrong network was registered |\n| SDK refuses to pay | The amount exceeds `maxAmountPerPayment`, or the asset is not in the default USD-stablecoin list. Ask the user before raising the cap |\n| `insufficient_funds` | Top up the agent wallet with USDC on the network you chose |\n| No `PAYMENT-REQUIRED` header | Not an x402 v2 endpoint. Check the body for a v1 `accepts` JSON, or use a different service |\n\nMore: https://indexagentica.com/entries/x402/ and https://docs.x402.org\n", "html": "

Pay with x402

\n

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.

\n

Rules before you spend anything

\n
  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.
\n

Step 1: Detect and read the price

\n

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

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

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

\n

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

\n
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
\n

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

\n

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"].

\n

Step 2: Pay

\n

Choose the first option that is available.

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

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.

\n
B. TypeScript SDK
\n
npm install @x402/fetch @x402/core @x402/evm viem
\n
import { wrapFetchWithPayment, x402HTTPClient } from "@x402/fetch";\nimport { x402Client } from "@x402/core/client";\nimport { ExactEvmScheme } from "@x402/evm/exact/client";\nimport { privateKeyToAccount } from "viem/accounts";\n\nconst signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);\nconst client = x402Client.fromConfig({\n  schemes: [{ network: "eip155:*", client: new ExactEvmScheme(signer) }],\n  spendControls: { maxAmountPerPayment: "$0.10" }, // keep caps on; never set spendControls: false\n});\nconst pay = wrapFetchWithPayment(fetch, client);\nconst res = await pay(process.env.URL!);\nconst result = await new x402HTTPClient(client).processResponse(res);\nconsole.log(res.status, result.paymentStatus, result.header);
\n
C. Python SDK
\n
pip install "x402[httpx]" eth_account
\n
import asyncio, os\nfrom eth_account import Account\nfrom x402 import x402Client\nfrom x402.http import x402HTTPClient\nfrom x402.http.clients import x402HttpxClient\nfrom x402.mechanisms.evm import EthAccountSigner\nfrom x402.mechanisms.evm.exact.register import register_exact_evm_client\n\nasync def main():\n    client = x402Client()\n    register_exact_evm_client(client, EthAccountSigner(Account.from_key(os.environ["EVM_PRIVATE_KEY"])))\n    async with x402HttpxClient(client) as http:\n        r = await http.get(os.environ["URL"])\n        await r.aread()\n        print(r.status_code, r.text[:500])\n        if r.is_success:\n            print(x402HTTPClient(client).get_payment_settle_response(lambda n: r.headers.get(n)))\n\nasyncio.run(main())
\n

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

\n

Step 3: Check the receipt

\n\n

Finding paid services

\n

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

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

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

\n

Testing without real money

\n

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.

\n

Troubleshooting

\n
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
\n

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

" }