{ "schema_version": "agentpmt.docs.v1", "generated_at": "2026-07-23T23:22:04.920Z", "release_id": "9bd28307d3dc8ff05bcac2f755a96681a9e650091caba4ab5ecbd5a1d6d62acc", "id": "generated-direct-x402-tool-payments-for-autonomous-agents", "page_url": "https://www.agentpmt.com/docs/autonomous-agents/x402-payments-for-tool-usage", "markdown_url": "https://www.agentpmt.com/docs/autonomous-agents/x402-payments-for-tool-usage?format=agent-md", "json_url": "https://www.agentpmt.com/docs/autonomous-agents/x402-payments-for-tool-usage?format=agent-json", "source_path": "content/docs/x402-payments-for-tool-usage.mdoc", "updated_at": "2026-07-23T01:20:26.647Z", "headings": [ { "depth": 2, "id": "endpoint", "title": "Endpoint" }, { "depth": 2, "id": "flow", "title": "Flow" }, { "depth": 2, "id": "initial-request", "title": "Initial Request" }, { "depth": 2, "id": "sign-the-payment", "title": "Sign the Payment" }, { "depth": 2, "id": "paid-retry", "title": "Paid Retry" }, { "depth": 2, "id": "successful-response", "title": "Successful Response" }, { "depth": 2, "id": "agentaddress-credit-alternative", "title": "AgentAddress Credit Alternative" }, { "depth": 2, "id": "related-references", "title": "Related References" } ], "related_products": [], "related_workflows": [], "doc": { "title": "X402 Payments For Tool Usage", "description": "Pay for a single eligible AgentPMT tool action with x402: read the 402 challenge, sign the EIP-712 authorization, and retry with X-PAYMENT.", "category": "Autonomous Agents", "image": null, "full_path": "autonomous-agents/x402-payments-for-tool-usage", "body_markdown": "# X402 Payments For Tool Usage\n\nUse direct x402 payment when an autonomous agent needs one eligible tool action. The agent sends action parameters, receives a `402 Payment Required` challenge, signs one token transfer authorization, and retries the exact same action body with `X-PAYMENT`.\n\nThe product action must be direct-x402-enabled.\n\n## Endpoint\n\n```text\nPOST https://www.agentpmt.com/api/external/tools/{productSlug}/actions/{actionSlug}/invoke\n```\n\nDirect x402 requests use the action parameters as the JSON request body.\n\n## Flow\n\n### Send the action parameters\n\nPOST the action's JSON parameters to the invoke endpoint without a payment header. If the action is direct-x402-enabled and payment is required, the server responds with `402`.\n\n### Decode the payment challenge\n\nRead the JSON response body and the base64 `PAYMENT-REQUIRED` header. Both describe the same payment challenge with `x402Version`, `resource`, and `accepts`.\n\n### Select the exact acceptance\n\nChoose an `accepts[]` entry by network, token asset, payee, amount, and resource URL. Do not blindly sign the first acceptance if the agent has a network or asset policy.\n\n### Sign the EIP-712 authorization\n\nBuild the `TransferWithAuthorization` typed-data domain from `acceptance.extra.name`, `acceptance.extra.version`, the numeric chain id parsed from `acceptance.network`, and `acceptance.asset`.\n\n### Retry the same body with X-PAYMENT\n\nBase64-encode the signed x402 envelope and retry the exact same action-parameter JSON body with `X-PAYMENT: `.\n\n## Initial Request\n\nThis example uses the live AI Writing Quality Check action tested on May 15, 2026.\n\n```bash\ncurl -i -s -X POST \"https://www.agentpmt.com/api/external/tools/ai-writing-quality-check/actions/check_for_banned_phrases/invoke\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"content\":\"Our customers love us. Ask our AI.\" }'\n```\n\nExpected response:\n\n- HTTP status `402 Payment Required`.\n- `PAYMENT-REQUIRED` header containing a base64 JSON challenge.\n- JSON body containing `x402Version`, `resource`, and `accepts`.\n\nThe decoded challenge includes one or more payment requirements similar to this shape:\n\n```json\n{\n \"x402Version\": 2,\n \"error\": \"Payment required\",\n \"resource\": {\n \"url\": \"https://www.agentpmt.com/api/external/tools/ai-writing-quality-check/actions/check_for_banned_phrases/invoke\",\n \"description\": \"AgentPMT tool action\",\n \"mimeType\": \"application/json\"\n },\n \"accepts\": [\n {\n \"scheme\": \"exact\",\n \"network\": \"eip155:8453\",\n \"asset\": \"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\",\n \"payTo\": \"0x7ed9057a8edec4496c902c9aecf1d30947d7cc09\",\n \"amount\": \"50000\",\n \"extra\": {\n \"name\": \"USD Coin\",\n \"version\": \"2\"\n }\n }\n ]\n}\n```\n\nThe example acceptance above is Base USDC. `amount` is in token minor units, so `50000` means `0.05` USDC for a six-decimal token.\n\n## Sign the Payment\n\nSign the selected acceptance with EIP-712 `TransferWithAuthorization` typed data.\n\nEIP-712 domain:\n\n| Field | Value |\n| --- | --- |\n| `name` | `acceptance.extra.name` |\n| `version` | `acceptance.extra.version` |\n| `chainId` | Numeric chain id parsed from `acceptance.network`, such as `8453` from `eip155:8453` |\n| `verifyingContract` | `acceptance.asset` |\nEIP-712 primary type:\n\n```json\n{\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\nAuthorization message:\n\n```json\n{\n \"from\": \"0xPAYER_WALLET\",\n \"to\": \"acceptance.payTo\",\n \"value\": \"acceptance.amount\",\n \"validAfter\": \"0\",\n \"validBefore\": \"\",\n \"nonce\": \"0x\"\n}\n```\n\n## Paid Retry\n\nThe signed x402 envelope is base64-encoded JSON. Use the selected acceptance's network and asset, and include the signature plus authorization values.\n\n```json\n{\n \"x402Version\": 2,\n \"scheme\": \"exact\",\n \"network\": \"eip155:8453\",\n \"asset\": \"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\",\n \"payload\": {\n \"signature\": \"0x\",\n \"authorization\": {\n \"from\": \"0xPAYER_WALLET\",\n \"to\": \"0x7ed9057a8edec4496c902c9aecf1d30947d7cc09\",\n \"value\": \"50000\",\n \"validAfter\": \"0\",\n \"validBefore\": \"\",\n \"nonce\": \"0x\"\n }\n }\n}\n```\n\nRetry the exact same action body:\n\n```bash\ncurl -s -X POST \"https://www.agentpmt.com/api/external/tools/ai-writing-quality-check/actions/check_for_banned_phrases/invoke\" \\\n -H \"Content-Type: application/json\" \\\n -H \"X-PAYMENT: \" \\\n -d '{ \"content\":\"Our customers love us. Ask our AI.\" }'\n```\n\nOn success, the response is the paid tool result with `x402` payment metadata.\n\n## Successful Response\n\nA successful direct x402 tool call returns the paid tool result and sets `PAYMENT-RESPONSE` with a base64-encoded JSON settlement payload. Decode that header to read the settlement transaction, network, payer, and the payment requirement that the broadcast satisfied.\n\n## AgentAddress Credit Alternative\n\nDirect x402 tool payments do not use the AgentAddress EIP-191 request-signing envelope. If the agent should buy stored credits once and then spend them through wallet-signed calls, use the credit-based AgentAddress guide. That guide contains the current signing rules, accepted path tolerance, canonical JSON hash forms, and `EXTERNAL_SIGNATURE_*` self-correction fields.\n\n## Related References\n\n### [Credit Based Tool Usage With AgentAddress](https://www.agentpmt.com/docs/autonomous-agents/credit-based-tool-usage-with-agentaddress)\n\nBuy reusable credits with x402, then spend them through signed AgentAddress calls.\n\n### [Endpoint Catalog](https://www.agentpmt.com/docs/api-reference/autonomous-agents)\n\nAuto-generated autonomous-agent API request and response schemas.\n" } }