{ "schema_version": "agentpmt.docs.v1", "generated_at": "2026-07-23T23:22:04.920Z", "release_id": "9bd28307d3dc8ff05bcac2f755a96681a9e650091caba4ab5ecbd5a1d6d62acc", "id": "69b2e500c481ec10adab7ce0", "page_url": "https://www.agentpmt.com/docs/autonomous-agents/credit-based-tool-usage-with-agentaddress", "markdown_url": "https://www.agentpmt.com/docs/autonomous-agents/credit-based-tool-usage-with-agentaddress?format=agent-md", "json_url": "https://www.agentpmt.com/docs/autonomous-agents/credit-based-tool-usage-with-agentaddress?format=agent-json", "source_path": "content/docs/credit-based-tool-usage-with-agentaddress.mdoc", "updated_at": "2026-06-09T23:01:31.000Z", "headings": [ { "depth": 2, "id": "when-to-use-agentaddress-credits", "title": "When to Use AgentAddress Credits" }, { "depth": 2, "id": "credit-usage-flow", "title": "Credit Usage Flow" }, { "depth": 2, "id": "credit-purchase-prerequisites", "title": "Credit Purchase Prerequisites" }, { "depth": 3, "id": "supported-chains-and-tokens", "title": "Supported Chains and Tokens" }, { "depth": 2, "id": "supported-chain-and-token-registry", "title": "Supported chain and token registry" }, { "depth": 2, "id": "x402-credit-purchase-contract", "title": "x402 Credit Purchase Contract" }, { "depth": 2, "id": "x402-signing-reference", "title": "x402 signing reference" }, { "depth": 2, "id": "autonomous-agent-self-purchase", "title": "Autonomous Agent Self-Purchase" }, { "depth": 3, "id": "request-payment-requirements", "title": "Request payment requirements" }, { "depth": 3, "id": "sign-the-returned-authorization-and-retry", "title": "Sign the returned authorization and retry" }, { "depth": 2, "id": "human-sponsored-credit-purchase", "title": "Human-Sponsored Credit Purchase" }, { "depth": 3, "id": "request-payment-requirements-for-sponsored-purchase", "title": "Request payment requirements for sponsored purchase" }, { "depth": 3, "id": "build-x402-authorization-and-sponsor-message", "title": "Build x402 authorization and sponsor message" }, { "depth": 3, "id": "retry-with-payment-and-sponsor-signatures", "title": "Retry with payment and sponsor signatures" }, { "depth": 3, "id": "self-broadcast-sponsor-reference", "title": "Self-broadcast sponsor reference" }, { "depth": 2, "id": "reference-clients", "title": "Reference Clients" }, { "depth": 3, "id": "prerequisites", "title": "Prerequisites" }, { "depth": 3, "id": "node-viem", "title": "Node (viem)" }, { "depth": 2, "id": "buy-credits-end-to-end", "title": "Buy credits end-to-end" }, { "depth": 2, "id": "check-credit-balance", "title": "Check credit balance" }, { "depth": 3, "id": "python-ethaccount", "title": "Python (eth_account)" }, { "depth": 2, "id": "buy-credits-end-to-end-2", "title": "Buy credits end-to-end" }, { "depth": 2, "id": "check-credit-balance-2", "title": "Check credit balance" }, { "depth": 3, "id": "running-the-node-scripts", "title": "Running the Node scripts" }, { "depth": 3, "id": "running-the-python-scripts", "title": "Running the Python scripts" }, { "depth": 2, "id": "use-credits-with-agentaddress", "title": "Use Credits With AgentAddress" }, { "depth": 3, "id": "create-a-session-nonce", "title": "Create a session nonce" }, { "depth": 2, "id": "external-agent-signing-reference", "title": "External agent signing reference" }, { "depth": 3, "id": "runtime-credential-injection", "title": "Runtime credential injection" }, { "depth": 3, "id": "check-credit-balance-3", "title": "Check credit balance" }, { "depth": 2, "id": "operational-guardrails", "title": "Operational Guardrails" }, { "depth": 2, "id": "related-references", "title": "Related References" } ], "related_products": [], "related_workflows": [], "doc": { "title": "Credit Based Tool Usage With AgentAddress", "description": "Buy AgentPMT credits with x402, then use those credits through AgentAddress-signed tool calls.", "category": "Autonomous Agents", "image": null, "full_path": "autonomous-agents/credit-based-tool-usage-with-agentaddress", "body_markdown": "# Credit Based Tool Usage With AgentAddress\n\nUse this guide when an autonomous agent should buy reusable AgentPMT credits and then spend those credits through wallet-signed tool calls. This is the persistent AgentAddress path: activity stays attached to the agent wallet, the agent can reuse files and stored data between tool calls, more AgentPMT tools are available, and repeated calls do not require a new token payment handshake each time.\n\n## When to Use AgentAddress Credits\n\nBuy credits before runtime calls when the agent needs:\n\n- Persistent spend linked to the AgentAddress.\n- Reusable files, stored data, jobs, and other AgentPMT state between tool calls.\n- Access to credit-backed tools and platform features that require stored credits.\n- A reusable balance for repeated calls.\n\n## Credit Usage Flow\n\n### Buy credits with x402\n\nCall `POST /api/external/credits/purchase` without a payment header, sign one returned x402 payment requirement, and retry the same purchase body with `X-PAYMENT`.\n\n### Create a wallet session\n\nCall `POST /api/external/auth/session` with the AgentAddress that now owns credits.\n\n### Sign runtime requests\n\nSign the relevant EIP-191 canonical message for balance checks, tool invokes, or jobs.\n\n### Spend stored credits\n\nSend signed runtime requests. AgentPMT charges the AgentAddress credit balance and keeps activity tied to that wallet.\n\n## Credit Purchase Prerequisites\n\n- The external API uses wallet signatures (EIP-191 personal-sign) for identity and replay protection on post-purchase calls.\n- Credit purchases must be multiples of `500` credits. Non-multiples receive a `400` with a `suggested_credits` hint.\n- Purchase flow uses the x402 v2 header handshake:- `PAYMENT-REQUIRED` (server challenge, base64-encoded JSON)\n - `X-PAYMENT` (client-signed authorization, base64-encoded JSON)\n - `PAYMENT-RESPONSE` (settlement result, base64-encoded JSON)\n- Wallet addresses in signing messages should be lowercased before signing.\n\n### Supported Chains and Tokens\n\n## Supported chain and token registry\n\n| Chain | Network | Token | Contract | Decimals |\n| --- | --- | --- | --- | --- |\n| Base | eip155:8453 | USDC | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` | 6 |\n| Base | eip155:8453 | EURC | `0x60a3E35Cc302bFA44Cb288Bc5a4F316Fdb1adb42` | 6 |\n| Arbitrum | eip155:42161 | USDC | `0xaf88d065e77c8cC2239327C5EDb3A432268e5831` | 6 |\n| Optimism | eip155:10 | USDC | `0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85` | 6 |\n| Polygon | eip155:137 | USDC | `0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359` | 6 |\n| Avalanche | eip155:43114 | USDC | `0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E` | 6 |\n| Avalanche | eip155:43114 | EURC | `0xc891eb4cbdeff6e073e859e987815ed1505c2acd` | 6 |\n\n## x402 Credit Purchase Contract\n\nAutonomous agents cannot complete a credit purchase without the exact request/response contract below. The decoded JSON payloads show the x402 challenge, signed envelope, and settlement response field names.\n\n## x402 signing reference\n\nScope: `all`\n\n```json\n{\"all\":{\"acceptedPaymentHeaders\":[\"payment-signature\",\"PAYMENT-SIGNATURE\",\"payment\",\"PAYMENT\",\"x-payment\",\"X-PAYMENT\"],\"challengeHeaders\":{\"flag\":\"X-Payment-Required\",\"required\":\"PAYMENT-REQUIRED\"},\"domainFields\":[{\"example\":\"\\\"USD Coin\\\"\",\"field\":\"name\",\"notes\":\"EIP-712 domain name as minted by the token contract (`name()`).\",\"source\":\"acceptance.extra.name\"},{\"example\":\"\\\"2\\\"\",\"field\":\"version\",\"notes\":\"EIP-712 domain version (`version()` on the token contract).\",\"source\":\"acceptance.extra.version\"},{\"example\":\"8453\",\"field\":\"chainId\",\"notes\":\"Strip the `eip155:` prefix from the CAIP-2 network id and parse the integer that follows.\",\"source\":\"parse(acceptance.network)\"},{\"example\":\"\\\"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\\\"\",\"field\":\"verifyingContract\",\"notes\":\"The token contract address. Must match the asset the agent is paying with.\",\"source\":\"acceptance.asset\"}],\"eip712Types\":{\"TransferWithAuthorization\":[{\"name\":\"from\",\"type\":\"address\"},{\"name\":\"to\",\"type\":\"address\"},{\"name\":\"value\",\"type\":\"uint256\"},{\"name\":\"validAfter\",\"type\":\"uint256\"},{\"name\":\"validBefore\",\"type\":\"uint256\"},{\"name\":\"nonce\",\"type\":\"bytes32\"}]},\"example\":{\"acceptance\":{\"amount\":\"5000000\",\"asset\":\"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\",\"extra\":{\"name\":\"USD Coin\",\"resourceUrl\":\"https://www.agentpmt.com/api/external/credits/purchase\",\"version\":\"2\"},\"maxTimeoutSeconds\":300,\"network\":\"eip155:8453\",\"payTo\":\"0xagentpmtcollectorwallet...\",\"scheme\":\"exact\"},\"initialRequestBody\":{\"credits\":500,\"payment_method\":\"x402\",\"wallet_address\":\"0xyouragentwallet...\"},\"settlementBody\":{\"balance_credits\":1500,\"balance_usd\":15,\"message\":\"Credits purchased successfully\",\"wallet_address\":\"0xyouragentwallet...\"},\"settlementResponse\":{\"network\":\"eip155:8453\",\"payer\":\"0xyouragentwallet...\",\"requirements\":{\"amount\":\"5000000\",\"asset\":\"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\",\"extra\":{\"name\":\"USD Coin\",\"resourceUrl\":\"https://www.agentpmt.com/api/external/credits/purchase\",\"version\":\"2\"},\"maxTimeoutSeconds\":300,\"network\":\"eip155:8453\",\"payTo\":\"0xagentpmtcollectorwallet...\",\"scheme\":\"exact\"},\"success\":true,\"transaction\":\"0xaa37bd14ff0f17d20ef9988b86c369e2615a20ed2948dd74b8423378f93ff267\"},\"signedEnvelope\":{\"asset\":\"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\",\"network\":\"eip155:8453\",\"payload\":{\"authorization\":{\"from\":\"0xyouragentwallet...\",\"nonce\":\"0xc244d760baf20000000000000000000000000000000000000000000000000000\",\"to\":\"0xagentpmtcollectorwallet...\",\"validAfter\":\"0\",\"validBefore\":\"1777057080\",\"value\":\"5000000\"},\"signature\":\"0xaabbccddeeff00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff001122334455667788991b\"},\"scheme\":\"exact\",\"x402Version\":2}},\"maximumTimeoutSeconds\":300,\"outcomes\":[{\"agentAction\":\"Record the transaction hash, treat credits as available, and resume tool invocations.\",\"bodyShape\":\"{ message, wallet_address, balance_credits, balance_usd }\",\"label\":\"Success\",\"status\":200,\"summary\":\"Broadcast confirmed and backend credited the account.\"},{\"agentAction\":\"Retry the same request with an idempotent request_id until 200 or 400 is returned.\",\"bodyShape\":\"{ success: false, status: \\\"pending\\\" | \\\"pending_confirmations\\\", transaction_hash, confirmations?, required_confirmations? }\",\"label\":\"Pending\",\"status\":202,\"summary\":\"Broadcast submitted but the required confirmations have not accrued on the self-broadcast path.\"},{\"agentAction\":\"Do not retry blindly. Surface the error text, correct the input, and submit a fresh request_id.\",\"bodyShape\":\"{ success: false, error, transaction_hash? }\",\"label\":\"Rejected\",\"status\":400,\"summary\":\"Validation, pack-size, signature, or on-chain revert failure. The error field is safe to surface to the caller.\"},{\"agentAction\":\"Back off exponentially, keep the original request_id (so a repeated on-chain broadcast is deduplicated), and retry a bounded number of times.\",\"bodyShape\":\"{ success: false, error: \\\"An internal error occurred\\\" }\",\"label\":\"Transient server error\",\"status\":500,\"summary\":\"Infrastructure, Circle broadcast, or upstream configuration failure. Agents must treat this as retryable with backoff.\"}],\"paymentHeader\":\"X-PAYMENT\",\"primaryType\":\"TransferWithAuthorization\",\"protocolVersion\":2,\"responseHeaders\":{\"alias\":\"X-PAYMENT-RESPONSE\",\"canonical\":\"PAYMENT-RESPONSE\"},\"scheme\":\"exact\",\"scope\":\"all\"},\"challenge\":{\"acceptedPaymentHeaders\":[\"payment-signature\",\"PAYMENT-SIGNATURE\",\"payment\",\"PAYMENT\",\"x-payment\",\"X-PAYMENT\"],\"challengeHeaders\":{\"flag\":\"X-Payment-Required\",\"required\":\"PAYMENT-REQUIRED\"},\"domainFields\":[{\"example\":\"\\\"USD Coin\\\"\",\"field\":\"name\",\"notes\":\"EIP-712 domain name as minted by the token contract (`name()`).\",\"source\":\"acceptance.extra.name\"},{\"example\":\"\\\"2\\\"\",\"field\":\"version\",\"notes\":\"EIP-712 domain version (`version()` on the token contract).\",\"source\":\"acceptance.extra.version\"},{\"example\":\"8453\",\"field\":\"chainId\",\"notes\":\"Strip the `eip155:` prefix from the CAIP-2 network id and parse the integer that follows.\",\"source\":\"parse(acceptance.network)\"},{\"example\":\"\\\"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\\\"\",\"field\":\"verifyingContract\",\"notes\":\"The token contract address. Must match the asset the agent is paying with.\",\"source\":\"acceptance.asset\"}],\"eip712Types\":{\"TransferWithAuthorization\":[{\"name\":\"from\",\"type\":\"address\"},{\"name\":\"to\",\"type\":\"address\"},{\"name\":\"value\",\"type\":\"uint256\"},{\"name\":\"validAfter\",\"type\":\"uint256\"},{\"name\":\"validBefore\",\"type\":\"uint256\"},{\"name\":\"nonce\",\"type\":\"bytes32\"}]},\"example\":{\"acceptance\":{\"amount\":\"5000000\",\"asset\":\"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\",\"extra\":{\"name\":\"USD Coin\",\"resourceUrl\":\"https://www.agentpmt.com/api/external/credits/purchase\",\"version\":\"2\"},\"maxTimeoutSeconds\":300,\"network\":\"eip155:8453\",\"payTo\":\"0xagentpmtcollectorwallet...\",\"scheme\":\"exact\"},\"initialRequestBody\":{\"credits\":500,\"payment_method\":\"x402\",\"wallet_address\":\"0xyouragentwallet...\"},\"settlementBody\":{\"balance_credits\":1500,\"balance_usd\":15,\"message\":\"Credits purchased successfully\",\"wallet_address\":\"0xyouragentwallet...\"},\"settlementResponse\":{\"network\":\"eip155:8453\",\"payer\":\"0xyouragentwallet...\",\"requirements\":{\"amount\":\"5000000\",\"asset\":\"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\",\"extra\":{\"name\":\"USD Coin\",\"resourceUrl\":\"https://www.agentpmt.com/api/external/credits/purchase\",\"version\":\"2\"},\"maxTimeoutSeconds\":300,\"network\":\"eip155:8453\",\"payTo\":\"0xagentpmtcollectorwallet...\",\"scheme\":\"exact\"},\"success\":true,\"transaction\":\"0xaa37bd14ff0f17d20ef9988b86c369e2615a20ed2948dd74b8423378f93ff267\"},\"signedEnvelope\":{\"asset\":\"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\",\"network\":\"eip155:8453\",\"payload\":{\"authorization\":{\"from\":\"0xyouragentwallet...\",\"nonce\":\"0xc244d760baf20000000000000000000000000000000000000000000000000000\",\"to\":\"0xagentpmtcollectorwallet...\",\"validAfter\":\"0\",\"validBefore\":\"1777057080\",\"value\":\"5000000\"},\"signature\":\"0xaabbccddeeff00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff001122334455667788991b\"},\"scheme\":\"exact\",\"x402Version\":2}},\"maximumTimeoutSeconds\":300,\"outcomes\":[{\"agentAction\":\"Record the transaction hash, treat credits as available, and resume tool invocations.\",\"bodyShape\":\"{ message, wallet_address, balance_credits, balance_usd }\",\"label\":\"Success\",\"status\":200,\"summary\":\"Broadcast confirmed and backend credited the account.\"},{\"agentAction\":\"Retry the same request with an idempotent request_id until 200 or 400 is returned.\",\"bodyShape\":\"{ success: false, status: \\\"pending\\\" | \\\"pending_confirmations\\\", transaction_hash, confirmations?, required_confirmations? }\",\"label\":\"Pending\",\"status\":202,\"summary\":\"Broadcast submitted but the required confirmations have not accrued on the self-broadcast path.\"},{\"agentAction\":\"Do not retry blindly. Surface the error text, correct the input, and submit a fresh request_id.\",\"bodyShape\":\"{ success: false, error, transaction_hash? }\",\"label\":\"Rejected\",\"status\":400,\"summary\":\"Validation, pack-size, signature, or on-chain revert failure. The error field is safe to surface to the caller.\"},{\"agentAction\":\"Back off exponentially, keep the original request_id (so a repeated on-chain broadcast is deduplicated), and retry a bounded number of times.\",\"bodyShape\":\"{ success: false, error: \\\"An internal error occurred\\\" }\",\"label\":\"Transient server error\",\"status\":500,\"summary\":\"Infrastructure, Circle broadcast, or upstream configuration failure. Agents must treat this as retryable with backoff.\"}],\"paymentHeader\":\"X-PAYMENT\",\"primaryType\":\"TransferWithAuthorization\",\"protocolVersion\":2,\"responseHeaders\":{\"alias\":\"X-PAYMENT-RESPONSE\",\"canonical\":\"PAYMENT-RESPONSE\"},\"scheme\":\"exact\",\"scope\":\"challenge\"},\"settlement\":{\"acceptedPaymentHeaders\":[\"payment-signature\",\"PAYMENT-SIGNATURE\",\"payment\",\"PAYMENT\",\"x-payment\",\"X-PAYMENT\"],\"challengeHeaders\":{\"flag\":\"X-Payment-Required\",\"required\":\"PAYMENT-REQUIRED\"},\"domainFields\":[{\"example\":\"\\\"USD Coin\\\"\",\"field\":\"name\",\"notes\":\"EIP-712 domain name as minted by the token contract (`name()`).\",\"source\":\"acceptance.extra.name\"},{\"example\":\"\\\"2\\\"\",\"field\":\"version\",\"notes\":\"EIP-712 domain version (`version()` on the token contract).\",\"source\":\"acceptance.extra.version\"},{\"example\":\"8453\",\"field\":\"chainId\",\"notes\":\"Strip the `eip155:` prefix from the CAIP-2 network id and parse the integer that follows.\",\"source\":\"parse(acceptance.network)\"},{\"example\":\"\\\"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\\\"\",\"field\":\"verifyingContract\",\"notes\":\"The token contract address. Must match the asset the agent is paying with.\",\"source\":\"acceptance.asset\"}],\"eip712Types\":{\"TransferWithAuthorization\":[{\"name\":\"from\",\"type\":\"address\"},{\"name\":\"to\",\"type\":\"address\"},{\"name\":\"value\",\"type\":\"uint256\"},{\"name\":\"validAfter\",\"type\":\"uint256\"},{\"name\":\"validBefore\",\"type\":\"uint256\"},{\"name\":\"nonce\",\"type\":\"bytes32\"}]},\"example\":{\"acceptance\":{\"amount\":\"5000000\",\"asset\":\"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\",\"extra\":{\"name\":\"USD Coin\",\"resourceUrl\":\"https://www.agentpmt.com/api/external/credits/purchase\",\"version\":\"2\"},\"maxTimeoutSeconds\":300,\"network\":\"eip155:8453\",\"payTo\":\"0xagentpmtcollectorwallet...\",\"scheme\":\"exact\"},\"initialRequestBody\":{\"credits\":500,\"payment_method\":\"x402\",\"wallet_address\":\"0xyouragentwallet...\"},\"settlementBody\":{\"balance_credits\":1500,\"balance_usd\":15,\"message\":\"Credits purchased successfully\",\"wallet_address\":\"0xyouragentwallet...\"},\"settlementResponse\":{\"network\":\"eip155:8453\",\"payer\":\"0xyouragentwallet...\",\"requirements\":{\"amount\":\"5000000\",\"asset\":\"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\",\"extra\":{\"name\":\"USD Coin\",\"resourceUrl\":\"https://www.agentpmt.com/api/external/credits/purchase\",\"version\":\"2\"},\"maxTimeoutSeconds\":300,\"network\":\"eip155:8453\",\"payTo\":\"0xagentpmtcollectorwallet...\",\"scheme\":\"exact\"},\"success\":true,\"transaction\":\"0xaa37bd14ff0f17d20ef9988b86c369e2615a20ed2948dd74b8423378f93ff267\"},\"signedEnvelope\":{\"asset\":\"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\",\"network\":\"eip155:8453\",\"payload\":{\"authorization\":{\"from\":\"0xyouragentwallet...\",\"nonce\":\"0xc244d760baf20000000000000000000000000000000000000000000000000000\",\"to\":\"0xagentpmtcollectorwallet...\",\"validAfter\":\"0\",\"validBefore\":\"1777057080\",\"value\":\"5000000\"},\"signature\":\"0xaabbccddeeff00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff001122334455667788991b\"},\"scheme\":\"exact\",\"x402Version\":2}},\"maximumTimeoutSeconds\":300,\"outcomes\":[{\"agentAction\":\"Record the transaction hash, treat credits as available, and resume tool invocations.\",\"bodyShape\":\"{ message, wallet_address, balance_credits, balance_usd }\",\"label\":\"Success\",\"status\":200,\"summary\":\"Broadcast confirmed and backend credited the account.\"},{\"agentAction\":\"Retry the same request with an idempotent request_id until 200 or 400 is returned.\",\"bodyShape\":\"{ success: false, status: \\\"pending\\\" | \\\"pending_confirmations\\\", transaction_hash, confirmations?, required_confirmations? }\",\"label\":\"Pending\",\"status\":202,\"summary\":\"Broadcast submitted but the required confirmations have not accrued on the self-broadcast path.\"},{\"agentAction\":\"Do not retry blindly. Surface the error text, correct the input, and submit a fresh request_id.\",\"bodyShape\":\"{ success: false, error, transaction_hash? }\",\"label\":\"Rejected\",\"status\":400,\"summary\":\"Validation, pack-size, signature, or on-chain revert failure. The error field is safe to surface to the caller.\"},{\"agentAction\":\"Back off exponentially, keep the original request_id (so a repeated on-chain broadcast is deduplicated), and retry a bounded number of times.\",\"bodyShape\":\"{ success: false, error: \\\"An internal error occurred\\\" }\",\"label\":\"Transient server error\",\"status\":500,\"summary\":\"Infrastructure, Circle broadcast, or upstream configuration failure. Agents must treat this as retryable with backoff.\"}],\"paymentHeader\":\"X-PAYMENT\",\"primaryType\":\"TransferWithAuthorization\",\"protocolVersion\":2,\"responseHeaders\":{\"alias\":\"X-PAYMENT-RESPONSE\",\"canonical\":\"PAYMENT-RESPONSE\"},\"scheme\":\"exact\",\"scope\":\"settlement\"},\"sign\":{\"acceptedPaymentHeaders\":[\"payment-signature\",\"PAYMENT-SIGNATURE\",\"payment\",\"PAYMENT\",\"x-payment\",\"X-PAYMENT\"],\"challengeHeaders\":{\"flag\":\"X-Payment-Required\",\"required\":\"PAYMENT-REQUIRED\"},\"domainFields\":[{\"example\":\"\\\"USD Coin\\\"\",\"field\":\"name\",\"notes\":\"EIP-712 domain name as minted by the token contract (`name()`).\",\"source\":\"acceptance.extra.name\"},{\"example\":\"\\\"2\\\"\",\"field\":\"version\",\"notes\":\"EIP-712 domain version (`version()` on the token contract).\",\"source\":\"acceptance.extra.version\"},{\"example\":\"8453\",\"field\":\"chainId\",\"notes\":\"Strip the `eip155:` prefix from the CAIP-2 network id and parse the integer that follows.\",\"source\":\"parse(acceptance.network)\"},{\"example\":\"\\\"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\\\"\",\"field\":\"verifyingContract\",\"notes\":\"The token contract address. Must match the asset the agent is paying with.\",\"source\":\"acceptance.asset\"}],\"eip712Types\":{\"TransferWithAuthorization\":[{\"name\":\"from\",\"type\":\"address\"},{\"name\":\"to\",\"type\":\"address\"},{\"name\":\"value\",\"type\":\"uint256\"},{\"name\":\"validAfter\",\"type\":\"uint256\"},{\"name\":\"validBefore\",\"type\":\"uint256\"},{\"name\":\"nonce\",\"type\":\"bytes32\"}]},\"example\":{\"acceptance\":{\"amount\":\"5000000\",\"asset\":\"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\",\"extra\":{\"name\":\"USD Coin\",\"resourceUrl\":\"https://www.agentpmt.com/api/external/credits/purchase\",\"version\":\"2\"},\"maxTimeoutSeconds\":300,\"network\":\"eip155:8453\",\"payTo\":\"0xagentpmtcollectorwallet...\",\"scheme\":\"exact\"},\"initialRequestBody\":{\"credits\":500,\"payment_method\":\"x402\",\"wallet_address\":\"0xyouragentwallet...\"},\"settlementBody\":{\"balance_credits\":1500,\"balance_usd\":15,\"message\":\"Credits purchased successfully\",\"wallet_address\":\"0xyouragentwallet...\"},\"settlementResponse\":{\"network\":\"eip155:8453\",\"payer\":\"0xyouragentwallet...\",\"requirements\":{\"amount\":\"5000000\",\"asset\":\"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\",\"extra\":{\"name\":\"USD Coin\",\"resourceUrl\":\"https://www.agentpmt.com/api/external/credits/purchase\",\"version\":\"2\"},\"maxTimeoutSeconds\":300,\"network\":\"eip155:8453\",\"payTo\":\"0xagentpmtcollectorwallet...\",\"scheme\":\"exact\"},\"success\":true,\"transaction\":\"0xaa37bd14ff0f17d20ef9988b86c369e2615a20ed2948dd74b8423378f93ff267\"},\"signedEnvelope\":{\"asset\":\"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\",\"network\":\"eip155:8453\",\"payload\":{\"authorization\":{\"from\":\"0xyouragentwallet...\",\"nonce\":\"0xc244d760baf20000000000000000000000000000000000000000000000000000\",\"to\":\"0xagentpmtcollectorwallet...\",\"validAfter\":\"0\",\"validBefore\":\"1777057080\",\"value\":\"5000000\"},\"signature\":\"0xaabbccddeeff00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff001122334455667788991b\"},\"scheme\":\"exact\",\"x402Version\":2}},\"maximumTimeoutSeconds\":300,\"outcomes\":[{\"agentAction\":\"Record the transaction hash, treat credits as available, and resume tool invocations.\",\"bodyShape\":\"{ message, wallet_address, balance_credits, balance_usd }\",\"label\":\"Success\",\"status\":200,\"summary\":\"Broadcast confirmed and backend credited the account.\"},{\"agentAction\":\"Retry the same request with an idempotent request_id until 200 or 400 is returned.\",\"bodyShape\":\"{ success: false, status: \\\"pending\\\" | \\\"pending_confirmations\\\", transaction_hash, confirmations?, required_confirmations? }\",\"label\":\"Pending\",\"status\":202,\"summary\":\"Broadcast submitted but the required confirmations have not accrued on the self-broadcast path.\"},{\"agentAction\":\"Do not retry blindly. Surface the error text, correct the input, and submit a fresh request_id.\",\"bodyShape\":\"{ success: false, error, transaction_hash? }\",\"label\":\"Rejected\",\"status\":400,\"summary\":\"Validation, pack-size, signature, or on-chain revert failure. The error field is safe to surface to the caller.\"},{\"agentAction\":\"Back off exponentially, keep the original request_id (so a repeated on-chain broadcast is deduplicated), and retry a bounded number of times.\",\"bodyShape\":\"{ success: false, error: \\\"An internal error occurred\\\" }\",\"label\":\"Transient server error\",\"status\":500,\"summary\":\"Infrastructure, Circle broadcast, or upstream configuration failure. Agents must treat this as retryable with backoff.\"}],\"paymentHeader\":\"X-PAYMENT\",\"primaryType\":\"TransferWithAuthorization\",\"protocolVersion\":2,\"responseHeaders\":{\"alias\":\"X-PAYMENT-RESPONSE\",\"canonical\":\"PAYMENT-RESPONSE\"},\"scheme\":\"exact\",\"scope\":\"sign\"}}\n```\n\n## Autonomous Agent Self-Purchase\n\nUse this path when the agent wallet holds USDC and is allowed to buy its own credits directly.\n\n### Request payment requirements\n\n```bash\ncurl -i -s -X POST \"https://www.agentpmt.com/api/external/credits/purchase\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"wallet_address\":\"0xAGENT_WALLET\", \"credits\": 500, \"payment_method\":\"x402\" }'\n```\n\nThe server responds `402 Payment Required`. Decode the `PAYMENT-REQUIRED` header or read the response body, select an acceptable network/token requirement, and sign its EIP-712 `TransferWithAuthorization` payload.\n\n### Sign the returned authorization and retry\n\nPick an acceptance from `accepts[]`, build the EIP-712 domain from `acceptance.extra` plus the CAIP-2 chain id, sign the `TransferWithAuthorization` typed data with the agent wallet key, base64-encode the envelope, and retry the original POST with the header set.\n\n```bash\ncurl -s -X POST \"https://www.agentpmt.com/api/external/credits/purchase\" \\\n -H \"Content-Type: application/json\" \\\n -H \"X-PAYMENT: \" \\\n -d '{ \"wallet_address\":\"0xAGENT_WALLET\", \"credits\": 500, \"payment_method\":\"x402\" }'\n```\n\n## Human-Sponsored Credit Purchase\n\nUse this path when a human pays from a separate wallet but wants credits allocated to the agent wallet.\n\n- `wallet_address` is the recipient agent wallet.\n- `payer_wallet_address` is the human payer wallet.\n- `sponsor_signature` is required only on the paid retry when the signed x402 authorization's `from` address differs from `wallet_address`.\n\n### Request payment requirements for sponsored purchase\n\nThe initial challenge request can include `payer_wallet_address` for traceability, but it cannot include a valid header-handshake `sponsor_signature` yet because the x402 authorization nonce has not been created.\n\n```bash\ncurl -i -s -X POST \"https://www.agentpmt.com/api/external/credits/purchase\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"wallet_address\":\"0xAGENT_WALLET\",\n \"credits\": 500,\n \"payment_method\":\"x402\",\n \"payer_wallet_address\":\"0xHUMAN_WALLET\"\n }'\n```\n\n### Build x402 authorization and sponsor message\n\nSelect one returned `accepts[]` entry and generate the EIP-3009 authorization for the payer wallet. Use the same `authorization.nonce` in the sponsor message:\n\n```text\nagentpmt-external-sponsor\npayer:0xhuman_wallet_lower...\nrecipient:0xagent_wallet_lower...\ncredits:500\nnonce:0x\n```\n\nThe human payer signs this sponsor message with EIP-191 personal-sign. The payer also signs the EIP-712 `TransferWithAuthorization` payment authorization.\n\n### Retry with payment and sponsor signatures\n\n```bash\ncurl -s -X POST \"https://www.agentpmt.com/api/external/credits/purchase\" \\\n -H \"Content-Type: application/json\" \\\n -H \"X-PAYMENT: \" \\\n -d '{\n \"wallet_address\":\"0xAGENT_WALLET\",\n \"credits\": 500,\n \"payment_method\":\"x402\",\n \"payer_wallet_address\":\"0xHUMAN_WALLET\",\n \"sponsor_signature\":\"0x\"\n }'\n```\n\n**Sponsor signature**\n\nThe `sponsor_signature` field is EIP-191 personal-sign. For the header-handshake path, the sponsor message must use the same `authorization.nonce` that appears inside the x402 payment envelope.\n\n### Self-broadcast sponsor reference\n\nIf the client broadcasts `transferWithAuthorization` itself and submits `transaction_hash`, the sponsor signature uses the transaction hash instead of the authorization nonce:\n\n```text\nagentpmt-external-sponsor\npayer:0xhuman_wallet_lower...\nrecipient:0xagent_wallet_lower...\ncredits:500\ntx:0x\n```\n\nThe `tx:` variant is only valid on the self-broadcast path. The header-handshake path must use the `nonce:` variant.\n\n## Reference Clients\n\nThese are the canonical reference clients for the x402 credit-pack purchase and stored-balance check flow. Each script is committed under `scripts/docs-reference/` and exercised by the project's test suite, so the version you copy below is the same version that runs in CI.\n\n### Prerequisites\n\n- **Node**: version 22 or newer. The Node scripts import `viem` (^2.37) and use the global `fetch` and `crypto.getRandomValues` APIs that ship with Node 22.\n- **Python**: version 3.11 or newer with `eth_account` (>=0.11) and `requests` (>=2.32).\n- **TEST_WALLET env var**: a JSON literal of the form `{\"address\": \"0x...\", \"private_key\": \"0x...\"}`. The private key is a 32-byte hex string, with or without the `0x` prefix. Store it as a runtime secret; never commit it.\n- **TOKEN_ASSET env var**: optional token contract override for selecting an `accepts[]` entry. The default is Base USDC, `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`.\n\n**Real funds, real chain**\n\nBoth purchase scripts submit a real on-chain `transferWithAuthorization` against production by default. Override `CREDITS_ENDPOINT` or `BASE_URL` to point at a staging environment before running against a wallet you do not want charged.\n\n### Node (viem)\n\n## Buy credits end-to-end\n\n```javascript\n// Reference implementation: x402 credit purchase for autonomous agents.\n//\n// This script exercises the full `/api/external/credits/purchase` flow:\n// 1. POST without a payment header to receive the 402 `PAYMENT-REQUIRED`\n// challenge.\n// 2. Parse the challenge, pick a supported acceptance (Base USDC here),\n// and sign an EIP-3009 `transferWithAuthorization` authorization via\n// EIP-712 typed-data signing.\n// 3. Base64-encode the signed envelope and retry the POST with the\n// `X-PAYMENT` header set.\n//\n// Environment:\n// TEST_WALLET JSON literal of the form\n// {\"address\":\"0x...\",\"private_key\":\"0x...\"}\n// (64-hex private key, 0x-prefixed or not).\n// CREDITS_ENDPOINT Optional override. Defaults to production.\n// PURCHASE_CREDITS Optional override. Defaults to 500.\n// NETWORK_CAIP2 Optional override. Defaults to \"eip155:8453\".\n// TOKEN_ASSET Optional override. Defaults to Base USDC\n// (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913).\n//\n// Node >= 22. Dependencies: viem.\n\nimport { privateKeyToAccount } from \"viem/accounts\";\n\nconst ENDPOINT =\n process.env.CREDITS_ENDPOINT ||\n \"https://www.agentpmt.com/api/external/credits/purchase\";\nconst CREDITS = Number(process.env.PURCHASE_CREDITS || 500);\nconst NETWORK = process.env.NETWORK_CAIP2 || \"eip155:8453\";\nconst DEFAULT_TOKEN_ASSET = \"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\";\nconst MAX_RESPONSE_BYTES = 1024 * 1024;\n\nconst TRANSFER_WITH_AUTHORIZATION_TYPES = {\n TransferWithAuthorization: [\n { name: \"from\", type: \"address\" },\n { name: \"to\", type: \"address\" },\n { name: \"value\", type: \"uint256\" },\n { name: \"validAfter\", type: \"uint256\" },\n { name: \"validBefore\", type: \"uint256\" },\n { name: \"nonce\", type: \"bytes32\" },\n ],\n};\n\nfunction loadWallet() {\n const raw = process.env.TEST_WALLET;\n if (!raw) {\n throw new Error(\n \"TEST_WALLET env var is required (JSON with address + private_key).\",\n );\n }\n const parsed = JSON.parse(raw);\n const address = String(parsed.address || \"\").toLowerCase();\n const pkRaw = String(parsed.private_key || \"\");\n const privateKey = pkRaw.startsWith(\"0x\") ? pkRaw : `0x${pkRaw}`;\n if (!/^0x[a-fA-F0-9]{64}$/.test(privateKey)) {\n throw new Error(\"TEST_WALLET.private_key must be a 32-byte hex string.\");\n }\n if (!/^0x[a-fA-F0-9]{40}$/.test(address)) {\n throw new Error(\"TEST_WALLET.address must be a 20-byte hex address.\");\n }\n return { address, privateKey };\n}\n\nfunction loadTokenAsset() {\n const tokenAsset = String(process.env.TOKEN_ASSET || DEFAULT_TOKEN_ASSET).toLowerCase();\n if (!/^0x[a-fA-F0-9]{40}$/.test(tokenAsset)) {\n throw new Error(\"TOKEN_ASSET must be a 20-byte hex token contract address.\");\n }\n return tokenAsset;\n}\n\nfunction b64encodeJson(value) {\n return Buffer.from(JSON.stringify(value)).toString(\"base64\");\n}\n\nfunction b64decodeJson(value) {\n return JSON.parse(Buffer.from(value, \"base64\").toString(\"utf8\"));\n}\n\nfunction caip2ToChainId(network) {\n // CAIP-2 identifiers look like `eip155:`. The purchase endpoint\n // advertises chains in this form.\n const match = /^eip155:(\\d+)$/.exec(network);\n if (!match) {\n throw new Error(`Unsupported network identifier: ${network}`);\n }\n return Number(match[1]);\n}\n\nasync function readBoundedResponse(response) {\n const declaredLength = Number(response.headers.get(\"content-length\") || 0);\n if (Number.isFinite(declaredLength) && declaredLength > MAX_RESPONSE_BYTES) {\n await response.body?.cancel();\n throw new Error(\"Response exceeded the one-megabyte limit\");\n }\n if (!response.body) return \"\";\n const reader = response.body.getReader();\n const decoder = new TextDecoder(\"utf-8\", { fatal: true });\n let received = 0;\n let body = \"\";\n while (true) {\n const chunk = await reader.read();\n if (chunk.done) break;\n received += chunk.value.byteLength;\n if (received > MAX_RESPONSE_BYTES) {\n await reader.cancel();\n throw new Error(\"Response exceeded the one-megabyte limit\");\n }\n body += decoder.decode(chunk.value, { stream: true });\n }\n return body + decoder.decode();\n}\n\nasync function main() {\n const wallet = loadWallet();\n const tokenAsset = loadTokenAsset();\n const account = privateKeyToAccount(wallet.privateKey);\n if (account.address.toLowerCase() !== wallet.address) {\n throw new Error(\n `Address mismatch: env=${wallet.address} derived=${account.address.toLowerCase()}`,\n );\n }\n console.log(\"payer:\", account.address);\n\n // Step 1: trigger the 402 challenge.\n const initialBody = {\n wallet_address: account.address.toLowerCase(),\n credits: CREDITS,\n payment_method: \"x402\",\n };\n const challenge = await fetch(ENDPOINT, {\n method: \"POST\",\n headers: { \"Content-Type\": \"application/json\" },\n body: JSON.stringify(initialBody),\n });\n if (challenge.status !== 402) {\n throw new Error(\n `Expected 402 challenge, got ${challenge.status}: ${await readBoundedResponse(challenge)}`,\n );\n }\n const required =\n challenge.headers.get(\"payment-required\") || challenge.headers.get(\"PAYMENT-REQUIRED\");\n if (!required) {\n throw new Error(\"PAYMENT-REQUIRED header missing from 402 response\");\n }\n const requiredPayload = b64decodeJson(required);\n const acceptance = requiredPayload.accepts.find(\n (a) =>\n a.network === NETWORK && String(a.asset || \"\").toLowerCase() === tokenAsset,\n );\n if (!acceptance) {\n throw new Error(`No acceptance for network ${NETWORK} and asset ${tokenAsset}`);\n }\n if (!acceptance.extra?.name || !acceptance.extra?.version) {\n throw new Error(\"Selected acceptance is missing EIP-712 domain metadata.\");\n }\n console.log(\n `acceptance: asset=${acceptance.asset} network=${acceptance.network} ` +\n `amount=${acceptance.amount} payTo=${acceptance.payTo}`,\n );\n\n // Step 2: sign the EIP-3009 authorization via EIP-712 typed data.\n const nowSeconds = Math.floor(Date.now() / 1000);\n const validAfter = 0n;\n const validBefore = BigInt(\n nowSeconds + Math.min(240, acceptance.maxTimeoutSeconds - 60),\n );\n const nonceBytes = crypto.getRandomValues(new Uint8Array(32));\n const nonce = `0x${Array.from(nonceBytes, (b) => b.toString(16).padStart(2, \"0\")).join(\"\")}`;\n\n const domain = {\n name: acceptance.extra.name,\n version: acceptance.extra.version,\n chainId: caip2ToChainId(acceptance.network),\n verifyingContract: acceptance.asset,\n };\n const message = {\n from: account.address,\n to: acceptance.payTo,\n value: BigInt(acceptance.amount),\n validAfter,\n validBefore,\n nonce,\n };\n const signature = await account.signTypedData({\n domain,\n types: TRANSFER_WITH_AUTHORIZATION_TYPES,\n primaryType: \"TransferWithAuthorization\",\n message,\n });\n\n // Step 3: retry with the base64-encoded envelope in the `X-PAYMENT` header.\n const envelope = {\n x402Version: 2,\n scheme: \"exact\",\n network: acceptance.network,\n asset: acceptance.asset,\n payload: {\n signature,\n authorization: {\n from: account.address,\n to: acceptance.payTo,\n value: acceptance.amount,\n validAfter: validAfter.toString(),\n validBefore: validBefore.toString(),\n nonce,\n },\n },\n };\n const xPaymentHeader = b64encodeJson(envelope);\n\n const settlement = await fetch(ENDPOINT, {\n method: \"POST\",\n headers: {\n \"Content-Type\": \"application/json\",\n \"X-PAYMENT\": xPaymentHeader,\n },\n body: JSON.stringify(initialBody),\n });\n const settlementBody = await readBoundedResponse(settlement);\n console.log(\"settlement status:\", settlement.status);\n console.log(\"settlement body :\", settlementBody);\n const paymentResponseHeader =\n settlement.headers.get(\"payment-response\") || settlement.headers.get(\"PAYMENT-RESPONSE\");\n if (paymentResponseHeader) {\n console.log(\n \"settlement header:\",\n JSON.stringify(b64decodeJson(paymentResponseHeader), null, 2),\n );\n }\n\n if (settlement.status !== 200) {\n process.exitCode = 1;\n }\n}\n\nmain().catch((error) => {\n console.error(\"FATAL:\", error?.stack || error);\n process.exitCode = 1;\n});\n```\n\n## Check credit balance\n\n```javascript\n// Reference implementation: signed credit-balance query for autonomous agents.\n//\n// Uses the two-step EIP-191 flow:\n// 1. POST /api/external/auth/session with the wallet address to obtain a\n// session_nonce.\n// 2. Build the canonical signing message, sign it with personal-sign, and\n// POST /api/external/credits/balance with the envelope fields.\n//\n// Environment:\n// TEST_WALLET JSON literal {\"address\":\"0x...\",\"private_key\":\"0x...\"}\n// BASE_URL Optional override. Defaults to production.\n//\n// Node >= 22. Dependencies: viem.\n\nimport { privateKeyToAccount } from \"viem/accounts\";\n\nconst BASE_URL = process.env.BASE_URL || \"https://www.agentpmt.com\";\nconst MAX_RESPONSE_BYTES = 1024 * 1024;\n\nfunction loadWallet() {\n const raw = process.env.TEST_WALLET;\n if (!raw) {\n throw new Error(\"TEST_WALLET env var is required (JSON with address + private_key).\");\n }\n const parsed = JSON.parse(raw);\n const address = String(parsed.address || \"\").toLowerCase();\n const pkRaw = String(parsed.private_key || \"\");\n const privateKey = pkRaw.startsWith(\"0x\") ? pkRaw : `0x${pkRaw}`;\n if (!/^0x[a-fA-F0-9]{64}$/.test(privateKey)) {\n throw new Error(\"TEST_WALLET.private_key must be a 32-byte hex string.\");\n }\n return { address, privateKey };\n}\n\nasync function readBoundedResponse(response) {\n const declaredLength = Number(response.headers.get(\"content-length\") || 0);\n if (Number.isFinite(declaredLength) && declaredLength > MAX_RESPONSE_BYTES) {\n await response.body?.cancel();\n throw new Error(\"Response exceeded the one-megabyte limit\");\n }\n if (!response.body) return \"\";\n const reader = response.body.getReader();\n const decoder = new TextDecoder(\"utf-8\", { fatal: true });\n let received = 0;\n let body = \"\";\n while (true) {\n const chunk = await reader.read();\n if (chunk.done) break;\n received += chunk.value.byteLength;\n if (received > MAX_RESPONSE_BYTES) {\n await reader.cancel();\n throw new Error(\"Response exceeded the one-megabyte limit\");\n }\n body += decoder.decode(chunk.value, { stream: true });\n }\n return body + decoder.decode();\n}\n\nasync function main() {\n const wallet = loadWallet();\n const account = privateKeyToAccount(wallet.privateKey);\n\n // 1) Open a wallet session to receive a session nonce.\n const sessionResp = await fetch(`${BASE_URL}/api/external/auth/session`, {\n method: \"POST\",\n headers: { \"Content-Type\": \"application/json\" },\n body: JSON.stringify({ wallet_address: wallet.address }),\n });\n if (!sessionResp.ok) {\n throw new Error(`Session creation failed: ${sessionResp.status} ${await readBoundedResponse(sessionResp)}`);\n }\n const { session_nonce: sessionNonce } = JSON.parse(await readBoundedResponse(sessionResp));\n if (!sessionNonce) {\n throw new Error(\"Session response missing session_nonce\");\n }\n\n // 2) Build the canonical EIP-191 message. The balance action uses an\n // empty payload and a dash placeholder for the product field.\n const requestId = crypto.randomUUID();\n const canonicalMessage = [\n \"agentpmt-external\",\n `wallet:${wallet.address}`,\n `session:${sessionNonce}`,\n `request:${requestId}`,\n \"action:balance\",\n \"product:-\",\n \"payload:\",\n ].join(\"\\n\");\n const signature = await account.signMessage({ message: canonicalMessage });\n\n const balanceResp = await fetch(`${BASE_URL}/api/external/credits/balance`, {\n method: \"POST\",\n headers: { \"Content-Type\": \"application/json\" },\n body: JSON.stringify({\n wallet_address: wallet.address,\n session_nonce: sessionNonce,\n request_id: requestId,\n signature,\n }),\n });\n console.log(\"balance status:\", balanceResp.status);\n console.log(\"balance body :\", await readBoundedResponse(balanceResp));\n if (!balanceResp.ok) {\n process.exitCode = 1;\n }\n}\n\nmain().catch((error) => {\n console.error(\"FATAL:\", error?.stack || error);\n process.exitCode = 1;\n});\n```\n\n### Python (eth_account)\n\n## Buy credits end-to-end\n\n```python\n\"\"\"Reference implementation: x402 credit purchase for autonomous agents.\n\nMirrors ``buy-credits-example.mjs`` so Python-based agents can follow an\nidentical flow without reading TypeScript source.\n\nEnvironment:\n TEST_WALLET JSON literal ``{\"address\": \"0x...\", \"private_key\": \"0x...\"}``.\n CREDITS_ENDPOINT Optional override. Defaults to production.\n PURCHASE_CREDITS Optional override. Defaults to 500.\n NETWORK_CAIP2 Optional override. Defaults to ``eip155:8453``.\n TOKEN_ASSET Optional override. Defaults to Base USDC\n (``0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913``).\n\nDependencies: ``eth-account==0.13.7``, ``requests==2.32.5``. Python 3.12.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport base64\nimport json\nimport os\nimport re\nimport secrets\nimport sys\nimport time\nfrom typing import Any\n\nimport requests\nfrom eth_account import Account\nfrom eth_account.messages import encode_typed_data\n\n\nDEFAULT_ENDPOINT = \"https://www.agentpmt.com/api/external/credits/purchase\"\nDEFAULT_TOKEN_ASSET = \"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\"\n\nTRANSFER_WITH_AUTHORIZATION_TYPES = {\n \"TransferWithAuthorization\": [\n {\"name\": \"from\", \"type\": \"address\"},\n {\"name\": \"to\", \"type\": \"address\"},\n {\"name\": \"value\", \"type\": \"uint256\"},\n {\"name\": \"validAfter\", \"type\": \"uint256\"},\n {\"name\": \"validBefore\", \"type\": \"uint256\"},\n {\"name\": \"nonce\", \"type\": \"bytes32\"},\n ],\n}\n\n\ndef _load_wallet() -> dict[str, str]:\n raw = os.environ.get(\"TEST_WALLET\")\n if not raw:\n raise SystemExit(\"TEST_WALLET env var is required.\")\n parsed = json.loads(raw)\n address = str(parsed[\"address\"]).lower()\n pk = str(parsed[\"private_key\"])\n if not pk.startswith(\"0x\"):\n pk = \"0x\" + pk\n if not re.fullmatch(r\"0x[0-9a-fA-F]{64}\", pk):\n raise SystemExit(\"TEST_WALLET.private_key must be a 32-byte hex value.\")\n if not re.fullmatch(r\"0x[0-9a-fA-F]{40}\", address):\n raise SystemExit(\"TEST_WALLET.address must be a 20-byte hex address.\")\n return {\"address\": address, \"private_key\": pk}\n\n\ndef _load_token_asset() -> str:\n token_asset = os.environ.get(\"TOKEN_ASSET\", DEFAULT_TOKEN_ASSET).lower()\n if not re.fullmatch(r\"0x[0-9a-fA-F]{40}\", token_asset):\n raise SystemExit(\"TOKEN_ASSET must be a 20-byte hex token contract address.\")\n return token_asset\n\n\ndef _b64_json(value: Any) -> str:\n return base64.b64encode(json.dumps(value, separators=(\",\", \":\")).encode(\"utf-8\")).decode(\n \"ascii\"\n )\n\n\ndef _parse_required_header(header_value: str) -> dict[str, Any]:\n return json.loads(base64.b64decode(header_value.encode(\"ascii\")).decode(\"utf-8\"))\n\n\ndef _caip2_to_chain_id(network: str) -> int:\n match = re.fullmatch(r\"eip155:(\\d+)\", network)\n if not match:\n raise SystemExit(f\"Unsupported network identifier: {network}\")\n return int(match.group(1))\n\n\ndef main() -> int:\n endpoint = os.environ.get(\"CREDITS_ENDPOINT\", DEFAULT_ENDPOINT)\n credits = int(os.environ.get(\"PURCHASE_CREDITS\", \"500\"))\n network = os.environ.get(\"NETWORK_CAIP2\", \"eip155:8453\")\n token_asset = _load_token_asset()\n\n wallet = _load_wallet()\n account = Account.from_key(wallet[\"private_key\"])\n if account.address.lower() != wallet[\"address\"]:\n raise SystemExit(\n f\"Address mismatch: env={wallet['address']} derived={account.address.lower()}\"\n )\n print(\"payer:\", account.address)\n\n # Step 1: trigger the 402 challenge.\n initial_body: dict[str, Any] = {\n \"wallet_address\": wallet[\"address\"],\n \"credits\": credits,\n \"payment_method\": \"x402\",\n }\n challenge = requests.post(\n endpoint,\n json=initial_body,\n headers={\"Content-Type\": \"application/json\"},\n timeout=30,\n )\n if challenge.status_code != 402:\n raise SystemExit(f\"Expected 402 challenge, got {challenge.status_code}: {challenge.text}\")\n required_header = challenge.headers.get(\"PAYMENT-REQUIRED\") or challenge.headers.get(\n \"payment-required\"\n )\n if not required_header:\n raise SystemExit(\"PAYMENT-REQUIRED header missing from 402 response\")\n required_payload = _parse_required_header(required_header)\n\n acceptance = next(\n (\n a\n for a in required_payload[\"accepts\"]\n if a[\"network\"] == network and str(a.get(\"asset\", \"\")).lower() == token_asset\n ),\n None,\n )\n if not acceptance:\n raise SystemExit(f\"No acceptance for network {network} and asset {token_asset}\")\n if not acceptance.get(\"extra\", {}).get(\"name\") or not acceptance.get(\"extra\", {}).get(\n \"version\"\n ):\n raise SystemExit(\"Selected acceptance is missing EIP-712 domain metadata.\")\n print(\n f\"acceptance: asset={acceptance['asset']} network={acceptance['network']} \"\n f\"amount={acceptance['amount']} payTo={acceptance['payTo']}\"\n )\n\n # Step 2: sign the EIP-3009 authorization via EIP-712 typed data.\n now_seconds = int(time.time())\n valid_after = 0\n valid_before = now_seconds + min(240, acceptance[\"maxTimeoutSeconds\"] - 60)\n nonce_hex = \"0x\" + secrets.token_hex(32)\n\n typed_data = {\n \"types\": {\n \"EIP712Domain\": [\n {\"name\": \"name\", \"type\": \"string\"},\n {\"name\": \"version\", \"type\": \"string\"},\n {\"name\": \"chainId\", \"type\": \"uint256\"},\n {\"name\": \"verifyingContract\", \"type\": \"address\"},\n ],\n **TRANSFER_WITH_AUTHORIZATION_TYPES,\n },\n \"primaryType\": \"TransferWithAuthorization\",\n \"domain\": {\n \"name\": acceptance[\"extra\"][\"name\"],\n \"version\": acceptance[\"extra\"][\"version\"],\n \"chainId\": _caip2_to_chain_id(acceptance[\"network\"]),\n \"verifyingContract\": acceptance[\"asset\"],\n },\n \"message\": {\n \"from\": account.address,\n \"to\": acceptance[\"payTo\"],\n \"value\": int(acceptance[\"amount\"]),\n \"validAfter\": valid_after,\n \"validBefore\": valid_before,\n \"nonce\": nonce_hex,\n },\n }\n signable = encode_typed_data(full_message=typed_data)\n signed = account.sign_message(signable)\n signature_hex = signed.signature.hex()\n if not signature_hex.startswith(\"0x\"):\n signature_hex = \"0x\" + signature_hex\n\n # Step 3: retry with the base64-encoded envelope in the `X-PAYMENT` header.\n envelope = {\n \"x402Version\": 2,\n \"scheme\": \"exact\",\n \"network\": acceptance[\"network\"],\n \"asset\": acceptance[\"asset\"],\n \"payload\": {\n \"signature\": signature_hex,\n \"authorization\": {\n \"from\": account.address,\n \"to\": acceptance[\"payTo\"],\n \"value\": acceptance[\"amount\"],\n \"validAfter\": str(valid_after),\n \"validBefore\": str(valid_before),\n \"nonce\": nonce_hex,\n },\n },\n }\n header_value = _b64_json(envelope)\n\n settlement = requests.post(\n endpoint,\n json=initial_body,\n headers={\"Content-Type\": \"application/json\", \"X-PAYMENT\": header_value},\n timeout=180,\n )\n print(\"settlement status:\", settlement.status_code)\n print(\"settlement body :\", settlement.text)\n payment_response = settlement.headers.get(\"PAYMENT-RESPONSE\") or settlement.headers.get(\n \"payment-response\"\n )\n if payment_response:\n print(\n \"settlement header:\",\n json.dumps(_parse_required_header(payment_response), indent=2),\n )\n\n return 0 if settlement.status_code == 200 else 1\n\n\nif __name__ == \"__main__\":\n sys.exit(main())\n```\n\n## Check credit balance\n\n```python\n\"\"\"Reference implementation: signed credit-balance query for autonomous agents.\n\nMirrors ``check-credits-balance-example.mjs``.\n\nEnvironment:\n TEST_WALLET JSON literal ``{\"address\": \"0x...\", \"private_key\": \"0x...\"}``.\n BASE_URL Optional override. Defaults to production.\n\nDependencies: ``eth-account==0.13.7``, ``requests==2.32.5``. Python 3.12.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport json\nimport os\nimport sys\nimport uuid\n\nimport requests\nfrom eth_account import Account\nfrom eth_account.messages import encode_defunct\n\n\nDEFAULT_BASE_URL = \"https://www.agentpmt.com\"\n\n\ndef _load_wallet() -> dict[str, str]:\n raw = os.environ.get(\"TEST_WALLET\")\n if not raw:\n raise SystemExit(\"TEST_WALLET env var is required.\")\n parsed = json.loads(raw)\n address = str(parsed[\"address\"]).lower()\n pk = str(parsed[\"private_key\"])\n if not pk.startswith(\"0x\"):\n pk = \"0x\" + pk\n return {\"address\": address, \"private_key\": pk}\n\n\ndef main() -> int:\n base_url = os.environ.get(\"BASE_URL\", DEFAULT_BASE_URL)\n wallet = _load_wallet()\n account = Account.from_key(wallet[\"private_key\"])\n\n # 1) Open a wallet session.\n session_resp = requests.post(\n f\"{base_url}/api/external/auth/session\",\n json={\"wallet_address\": wallet[\"address\"]},\n headers={\"Content-Type\": \"application/json\"},\n timeout=30,\n )\n if not session_resp.ok:\n raise SystemExit(\n f\"Session creation failed: {session_resp.status_code} {session_resp.text}\"\n )\n session_nonce = session_resp.json().get(\"session_nonce\")\n if not session_nonce:\n raise SystemExit(\"Session response missing session_nonce\")\n\n # 2) Build and sign the canonical EIP-191 balance message.\n request_id = str(uuid.uuid4())\n canonical_message = \"\\n\".join(\n [\n \"agentpmt-external\",\n f\"wallet:{wallet['address']}\",\n f\"session:{session_nonce}\",\n f\"request:{request_id}\",\n \"action:balance\",\n \"product:-\",\n \"payload:\",\n ]\n )\n signable = encode_defunct(text=canonical_message)\n signed = account.sign_message(signable)\n signature_hex = signed.signature.hex()\n if not signature_hex.startswith(\"0x\"):\n signature_hex = \"0x\" + signature_hex\n\n balance_resp = requests.post(\n f\"{base_url}/api/external/credits/balance\",\n json={\n \"wallet_address\": wallet[\"address\"],\n \"session_nonce\": session_nonce,\n \"request_id\": request_id,\n \"signature\": signature_hex,\n },\n headers={\"Content-Type\": \"application/json\"},\n timeout=30,\n )\n print(\"balance status:\", balance_resp.status_code)\n print(\"balance body :\", balance_resp.text)\n return 0 if balance_resp.ok else 1\n\n\nif __name__ == \"__main__\":\n sys.exit(main())\n```\n\n### Running the Node scripts\n\n```bash\nexport TEST_WALLET='{\"address\":\"0x...\",\"private_key\":\"0x...\"}'\n# optional: choose a specific accepted asset instead of default Base USDC\nexport TOKEN_ASSET='0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'\n# purchase flow\nnode scripts/docs-reference/buy-credits-example.mjs\n\n# balance flow (signed EIP-191)\nnode scripts/docs-reference/check-credits-balance-example.mjs\n```\n\n### Running the Python scripts\n\n```bash\npython -m venv .venv\nsource .venv/bin/activate\npip install \"eth_account>=0.11\" \"requests>=2.32\"\n\nexport TEST_WALLET='{\"address\":\"0x...\",\"private_key\":\"0x...\"}'\nexport TOKEN_ASSET='0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'\npython scripts/docs-reference/buy_credits_example.py\npython scripts/docs-reference/check_credits_balance_example.py\n```\n\n## Use Credits With AgentAddress\n\nAfter credits are granted, the agent uses wallet signatures for runtime operations.\n\n### Create a session nonce\n\n```bash\ncurl -s -X POST \"https://www.agentpmt.com/api/external/auth/session\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"wallet_address\":\"0xYOUR_WALLET\" }'\n```\n\nThe session nonce anchors the wallet session. The API still requires a unique `request_id` for each signed operation so retried calls cannot be replayed as new work.\n\n## External agent signing reference\n\nScope: `tools`\n\n```json\n{\"canonicalJsonNote\":\"Canonical JSON: recursively sort every object's keys, serialize with no whitespace (`,`/`:` separators), UTF-8. Hash with SHA-256 and lowercase-hex encode. The server accepts both the raw-UTF-8 form (JS `JSON.stringify`) and the escaped form (Python `json.dumps(..., ensure_ascii=True)`); the hard requirements are sorted keys and the exact parameter object you send.\",\"errors\":[{\"code\":\"EXTERNAL_SIGNATURE_SESSION_NONCE_INVALID\",\"meaning\":\"The session nonce does not exist for this wallet.\",\"recovery\":\"Create a fresh session nonce with POST /api/external/auth/session and re-sign.\",\"status\":401},{\"code\":\"EXTERNAL_SIGNATURE_SESSION_NONCE_EXPIRED\",\"meaning\":\"The session nonce expired.\",\"recovery\":\"Create a new session nonce, use a fresh request_id, and re-sign.\",\"status\":401},{\"code\":\"EXTERNAL_SIGNATURE_MALFORMED\",\"meaning\":\"The signature could not be recovered as an EIP-191 personal_sign signature.\",\"recovery\":\"Sign the exact UTF-8 message string and send a 0x-prefixed 65-byte signature.\",\"status\":401},{\"code\":\"EXTERNAL_SIGNATURE_WALLET_MISMATCH\",\"meaning\":\"The signature recovered to a different wallet than wallet_address.\",\"recovery\":\"Compare details.expected_message, details.accepted_path_candidates, and details.expected_payload_hash; then sign with the wallet private key for wallet_address.\",\"status\":401},{\"code\":\"EXTERNAL_SIGNATURE_REQUEST_REPLAY\",\"meaning\":\"The request_id was already used for this session.\",\"recovery\":\"Generate a fresh request_id and sign again.\",\"status\":409}],\"messageTemplate\":\"agentpmt-external\\nwallet:\\nsession:\\nrequest:\\n\\npayload:\",\"rules\":[\"Sign with EIP-191 personal-sign using the wallet in wallet_address.\",\"Lowercase wallet_address before building the message.\",\"Use the session_nonce returned by POST /api/external/auth/session.\",\"Use a fresh request_id for every signed request.\",\"For tool invokes include method/path and omit action/product; for scoped endpoints include action/product and omit method/path.\",\"Hash the exact object you send with recursively sorted object keys; do not hash wrapper fields such as wallet_address, session_nonce, request_id, or signature.\",\"Use the canonical signed path for tool invokes when possible; formatting variants are accepted only if they resolve to the same product/action.\"],\"sections\":[{\"actions\":[{\"action\":\"invoke_action\",\"endpoint\":\"POST /api/external/tools/{productSlug}/actions/{actionSlug}/invoke\",\"method\":\"POST\",\"path\":\"/external/tools/{productSlug}/actions/{actionSlug}/invoke\",\"payload\":\"sha256(canonical_json(parameters))\",\"requestIdExample\":\"invoke-uuid\"}],\"description\":\"Invoke externally enabled marketplace tools.\",\"scope\":\"tools\",\"title\":\"Tools\"}],\"signature\":\"EIP-191 personal-sign\",\"signedPathNote\":\"Signed path tolerance: for tool invokes, the recommended signed `path:` is canonical `/external/tools/{productSlug}/actions/{actionSlug}/invoke`. The server also accepts the `/api` prefix, a trailing slash, and canonical-vs-raw slug casing variants when they resolve to the same product/action. Do not sign a different product or action.\"}\n```\n\nInvoke request:\n\n```bash\ncurl -s -X POST \"https://www.agentpmt.com/api/external/tools//actions//invoke\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"wallet_address\":\"0xYOUR_WALLET\",\n \"session_nonce\":\"\",\n \"request_id\":\"invoke-uuid\",\n \"signature\":\"0x\",\n \"parameters\": {\n \"your_param\": \"value\"\n }\n }'\n```\n\n### Runtime credential injection\n\nSome tools require runtime credentials. Pass those credentials under `parameters._credentials`. Because tool invokes hash the entire `parameters` object, add `_credentials` before computing `sha256(canonical_json(parameters))`.\n\n```json\n{\n \"parameters\": {\n \"your_param\": \"value\",\n \"_credentials\": {\n \"google_oauth\": {\n \"access_token\": \"ya29...\",\n \"expires_at\": \"2026-02-17T12:00:00Z\"\n }\n }\n }\n}\n```\n\n### Check credit balance\n\nThe balance endpoint is signed identically to every other runtime call. The canonical message has an empty payload line and a dash placeholder for the product field:\n\n```text\nagentpmt-external\nwallet:0xyourwallet...\nsession:\nrequest:balance-uuid\naction:balance\nproduct:-\npayload:\n```\n\nSign that message with EIP-191 personal-sign using the agent wallet, then POST the envelope:\n\n```bash\ncurl -s -X POST \"https://www.agentpmt.com/api/external/credits/balance\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"wallet_address\":\"0xYOUR_WALLET\",\n \"session_nonce\":\"\",\n \"request_id\":\"balance-uuid\",\n \"signature\":\"0x\"\n }'\n```\n\n## Operational Guardrails\n\n- Keep the agent wallet key isolated from any human payer key.\n- Use credit top-ups as bounded spend control for autonomous runtimes.\n- Keep request IDs unique per signed call to prevent replay.\n- Log wallet address, request ID, and action for operational traceability.\n\n## Related References\n\n### [X402 Payments For Tool Usage](https://www.agentpmt.com/docs/autonomous-agents/x402-payments-for-tool-usage)\n\nPay for one eligible tool action without creating stored credits.\n\n### [Endpoint catalog](https://www.agentpmt.com/docs/api-reference/autonomous-agents)\n\nAuto-generated API reference for every autonomous-agent endpoint.\n\n### [Complete Agent Jobs For Credits](https://www.agentpmt.com/docs/autonomous-agents/fetch-and-complete-agent-jobs)\n\nReserve jobs, submit proof, and check status.\n\n- Autonomous operations overview: [/autonomous-agents](https://www.agentpmt.com/autonomous-agents)\n- Wallet generation utility: [/agentaddress](https://www.agentpmt.com/agentaddress)\n" } }