This is the payment primitive of the Agent Kit. The agent presents a payment requirement (received from a 402-responding service), the API validates against all 3 budget layers + the kill switch, executes the on-chain USDC transfer, and returns a payment header the agent can attach to retry the original request.
Most users should use the SDK’s x402fetch() helper instead of calling this endpoint directly. x402fetch handles the full 402 → pay → retry loop transparently.
When to call this directly vs use x402fetch
Use case
Recommended
Calling a third-party API that may return 402
x402fetch — handles the loop for you
Building a custom client (non-Node.js, no SDK)
This endpoint — replicate the loop yourself
Paying for a resource without retrying (e.g. pre-paying for batch credit)
This endpoint — caller controls what to do with the payment header
Inspecting payment intent before executing
This endpoint — you can re-render the requirement to the user before submission
How the loop works (with x402fetch)
The whole loop is one await x402fetch(sdk, url, init) call in the SDK. This page covers what happens server-side during the middle step.
Authentication
This endpoint accepts either auth mode:
HMAC (X-Agent-Auth + x-agent-id + x-request-timestamp) — when called by the agent SDK at runtime. See Authentication for the payload spec.
API key (Authorization: ApiKey ...) — when called by your backend on behalf of the agent.
The {id} path param must match the calling agent (if HMAC) or be a valid agent in the API key’s workspace (if API key).
Request body
object
required
The payment terms received in the 402 response from the resource. Schema below.
The paymentRequirement object:
string
required
Decimal USDC amount as a string (e.g. "0.05"). String to avoid float precision issues.
string
required
Always "USDC" in v1. Reserved for future expansion.
string
required
Stablecoin network. Today: "solana". EVM chain support is planned.
string
required
The address that should receive the USDC. The API validates this matches the 402 response’s intent.
string
Optional human-readable description from the resource. Logged in the audit trail.
string
Optional URL of the resource being paid for. Logged in the audit trail.
Response
string
The opaque value to attach to your retry request as the X-Payment header. The resource will validate it and serve the protected content.
string
Optional. Set if the payment resulted in an on-chain transaction (vs. a pre-funded credit pull). Use with chain explorers to confirm.
What the API checks before executing
Authenticates the request (HMAC or API key).
Looks up the agent and validates it’s not killed or paused.
Polls the kill switch state — refuses on active kill switch.
Validates all 3 budget layers atomically (Lua script in Redis):
infra — does the agent have infrastructure budget left?
tokens — does the agent have LLM token budget left? (informational here)
payments — does the requested amount fit under monthlyUSDC AND perTxUSDC?
Checks approval threshold: if amount >= approvalThresholdUSDC, holds the payment and returns HTTP 202 with { approvalId } instead of executing. Wait for human approval, then retry.
Validates wallet balance: rejects if the agent wallet doesn’t have enough USDC.
Executes the on-chain USDC transfer atomically.
Emits a payment event to the agent event stream (visible at GET /v1/agents/{id}/audit).
Returns the payment header.
The budget deduction (step 4) is atomic: even if the agent makes 10 parallel x402-pay calls, the Lua deduction ensures no double-spend past the cap. The cap cannot be bypassed by code path manipulation in the agent.
Approval gate — HTTP 202
If the payment amount triggers the approval threshold, the response is:
The SDK’s x402fetch handles this transparently — it polls /v1/signing/approvals/{id} every 5s until resolved or approvalTimeout (default 5 minutes), then retries the original request.If you’re calling this endpoint directly, you must implement the same loop. Approvals can resolve in one of three states:
approved — proceed with the original retry using the payment header
rejected — surface the error to your agent’s reasoning; do not retry
expired — same as rejected; the threshold was set for a reason
Common errors
Status
Cause
Fix / Recovery
401 invalid_auth
HMAC headers missing or signature mismatch
Verify the SDK is correctly initialized; check secret rotation
401 agent_killed
Agent in killed state
Provision a new agent; this one is dead
402 budget_exhausted
One or more budget layers empty. Response body includes failedLayers
Top up the budget via POST /v1/agents/{id}/budget and retry
402 insufficient_wallet_balance
Budget OK but wallet has no USDC
Fund via POST /v1/agents/{id}/fund/prepare + /fund/confirm
503 kill_switch_active
Global kill switch tripped
Wait for resolution; do not retry until kill switch clears
202 approval_required
Above threshold
Poll the approval ID
Working with paymentRequirement
The exact format of paymentRequirement depends on the 402-responding service. The SDK normalizes common variants:
HTTP 402 with WWW-Authenticate: x402 header
HTTP 402 with paymentRequirement JSON body
HTTP 402 with Payment-Required body field
If you’re calling this endpoint without the SDK, parse the 402 response yourself and pass the requirement here as-is.
Recommended pattern
Use the SDK’s x402fetch wrapper. It handles 402 detection, this endpoint call, header injection, and retry transparently — your agent code calls a normal fetch and never deals with payment plumbing directly. See SDK Reference — x402fetch.
POST /v1/agents/{id}/budget — adjust spend limits if you hit them often
POST /v1/agents/{id}/fund/prepare — top up the agent wallet
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Relayer.fi","colors":{"primary":"#015F51","light":"#ECE6D6","dark":"#015F51"},"logo":{"light":"https://mintcdn.com/relayerfi/HPPc29pDPmX_uuYf/images/relayer-isotype-petrol.svg?fit=max\u0026auto=format\u0026n=HPPc29pDPmX_uuYf\u0026q=85\u0026s=4793c846712b8d1c6e643ece66ba100c","dark":"https://mintcdn.com/relayerfi/HPPc29pDPmX_uuYf/images/relayer-isotype-cream.svg?fit=max\u0026auto=format\u0026n=HPPc29pDPmX_uuYf\u0026q=85\u0026s=72ed743508c822637327cf1091b4ad24"},"favicon":{"light":"https://mintcdn.com/relayerfi/HPPc29pDPmX_uuYf/images/relayer-isotype-petrol.svg?fit=max\u0026auto=format\u0026n=HPPc29pDPmX_uuYf\u0026q=85\u0026s=4793c846712b8d1c6e643ece66ba100c","dark":"https://mintcdn.com/relayerfi/HPPc29pDPmX_uuYf/images/relayer-isotype-cream.svg?fit=max\u0026auto=format\u0026n=HPPc29pDPmX_uuYf\u0026q=85\u0026s=72ed743508c822637327cf1091b4ad24"},"appearance":{"default":"system"},"background":{"color":{"light":"#F6F6F4","dark":"#1A1A19"}},"navbar":{"links":[{"href":"mailto:dev@relayer.fi","label":"Support"}]},"footer":{"socials":{"x":"https://x.com/RelayerProtocol","github":"https://github.com/relayerfi"}},"fonts":{"family":"Archivo"},"contextual":{"options":["copy","view","chatgpt","claude","perplexity","mcp","cursor","vscode"],"display":"header"},"styling":{"latex":true},"navigation":{"global":{"anchors":[{"anchor":"Website","icon":"globe","href":"https://relayer.fi"},{"anchor":"GitHub","icon":"github","href":"https://github.com/relayerfi"}]},"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"relayerfi","hasAudioNarration":false,"actualSubdomain":"relayerfi","customDomains":["docs.relayer.fi"],"gitSource":{"type":"github","owner":"picklerfun","repo":"docs","deployBranch":"main","contentDirectory":"","isPrivate":false,"mountPath":"","label":""},"entitlements":{},"buildId":"6ae94b16d111843d72bcd8a4:success","clientVersion":"0.0.4248","searchFilterCounts":[{"language":"default","tag":"API Reference","count":37},{"language":"default","tag":"Get Started","count":16},{"language":"default","tag":"Agent Kit","count":10},{"language":"default","tag":"Agents","count":10},{"language":"default","tag":"Widget Kit","count":8},{"language":"default","tag":"Transactions","count":8},{"language":"default","tag":"Widget Actions","count":7},{"language":"default","tag":"Runtime (HMAC)","count":6},{"language":"default","tag":"Global Payout","count":6},{"language":"default","tag":"Payout Kit","count":6}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"site-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"starter-pricing","enabled":true,"variant":{"name":"control","enabled":true,"payload":{"type":"string","value":"control"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"wildcard-email-auth","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":true},"customCss":[]}
{"page":{"pagePath":"api-reference/flows/agent-x402-pay","slug":"/api-reference/flows/agent-x402-pay","pageMetadata":{"title":"Pay for an x402-gated resource","description":"The agent pays for a remote resource that requires USDC via the x402 protocol. Budget-checked, kill-switch-gated, atomically enforced.","sidebarTitle":"x402-pay","api":"POST /v1/agents/{id}/x402-pay","href":"/api-reference/flows/agent-x402-pay"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"The agent pays for a remote resource that requires USDC via the x402 protocol. Budget-checked, kill-switch-gated, atomically enforced.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,li:`li`,ol:`ol`,p:`p`,pre:`pre`,span:`span`,strong:`strong`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,ul:`ul`,..._provideComponents(),...props.components},{CodeBlock,Heading,Info,Mermaid,ParamField,ResponseField,Table}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Info)_missingMdxReference(`Info`,true);if(!Mermaid)_missingMdxReference(`Mermaid`,true);if(!ParamField)_missingMdxReference(`ParamField`,true);if(!ResponseField)_missingMdxReference(`ResponseField`,true);if(!Table)_missingMdxReference(`Table`,true);return _jsxs(_Fragment,{children:[_jsxs(_components.p,{children:[`This is the `,_jsx(_components.strong,{children:`payment primitive`}),` of the Agent Kit. The agent presents a payment requirement (received from a 402-responding service), the API validates against all 3 budget layers + the kill switch, executes the on-chain USDC transfer, and returns a payment header the agent can attach to retry the original request.`]}),`\n`,_jsx(Info,{children:_jsxs(_components.p,{children:[`Most users should use the SDK’s `,_jsx(_components.code,{children:`x402fetch()`}),` helper instead of calling this endpoint directly. `,_jsx(_components.code,{children:`x402fetch`}),` handles the full 402 → pay → retry loop transparently.`]})}),`\n`,_jsxs(Heading,{level:`2`,id:`when-to-call-this-directly-vs-use-x402fetch`,children:[`When to call this directly vs use `,_jsx(_components.code,{children:`x402fetch`})]}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Use case`}),_jsx(_components.th,{children:`Recommended`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Calling a third-party API that may return 402`}),_jsxs(_components.td,{children:[_jsx(_components.strong,{children:_jsx(_components.code,{children:`x402fetch`})}),` — handles the loop for you`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Building a custom client (non-Node.js, no SDK)`}),_jsxs(_components.td,{children:[_jsx(_components.strong,{children:`This endpoint`}),` — replicate the loop yourself`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Paying for a resource without retrying (e.g. pre-paying for batch credit)`}),_jsxs(_components.td,{children:[_jsx(_components.strong,{children:`This endpoint`}),` — caller controls what to do with the payment header`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Inspecting payment intent before executing`}),_jsxs(_components.td,{children:[_jsx(_components.strong,{children:`This endpoint`}),` — you can re-render the requirement to the user before submission`]})]})]})]}),`\n`,_jsxs(Heading,{level:`2`,id:`how-the-loop-works-with-x402fetch`,children:[`How the loop works (with `,_jsx(_components.code,{children:`x402fetch`}),`)`]}),`\n`,_jsx(Mermaid,{chart:`sequenceDiagram\n participant Agent as Agent Runtime\n participant Remote as Remote Remote\n participant API as Relayer API\n\n Agent->>Remote: Original request (no payment)\n Remote-->>Agent: 402 + paymentRequirement\n Agent->>API: POST /agents/{id}/x402-pay { paymentRequirement }\n Note over API: Check budgets + kill switch\n Note over API: Execute USDC transfer\n API-->>Agent: { paymentHeader, transactionId }\n Agent->>Remote: Original request + X-Payment header\n Remote-->>Agent: 200 + content`}),`\n`,_jsxs(_components.p,{children:[`The whole loop is one `,_jsx(_components.code,{children:`await x402fetch(sdk, url, init)`}),` call in the SDK. This page covers what happens server-side during the middle step.`]}),`\n`,_jsx(Heading,{level:`2`,id:`authentication`,children:`Authentication`}),`\n`,_jsxs(_components.p,{children:[`This endpoint accepts `,_jsx(_components.strong,{children:`either`}),` auth mode:`]}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`HMAC`}),` (`,_jsx(_components.code,{children:`X-Agent-Auth`}),` + `,_jsx(_components.code,{children:`x-agent-id`}),` + `,_jsx(_components.code,{children:`x-request-timestamp`}),`) — when called by the agent SDK at runtime. See `,_jsx(_components.a,{href:`/get-started/authentication`,children:`Authentication`}),` for the payload spec.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`API key`}),` (`,_jsx(_components.code,{children:`Authorization: ApiKey ...`}),`) — when called by your backend on behalf of the agent.`]}),`\n`]}),`\n`,_jsxs(_components.p,{children:[`The `,_jsx(_components.code,{children:`{id}`}),` path param must match the calling agent (if HMAC) or be a valid agent in the API key’s workspace (if API key).`]}),`\n`,_jsx(Heading,{level:`2`,id:`request-body`,children:`Request body`}),`\n`,_jsx(ParamField,{body:`paymentRequirement`,type:`object`,required:true,id:`param-payment-requirement`,children:_jsx(_components.p,{children:`The payment terms received in the 402 response from the resource. Schema below.`})}),`\n`,_jsxs(_components.p,{children:[`The `,_jsx(_components.code,{children:`paymentRequirement`}),` object:`]}),`\n`,_jsx(ParamField,{body:`paymentRequirement.amount`,type:`string`,required:true,id:`param-payment-requirement-amount`,children:_jsxs(_components.p,{children:[`Decimal USDC amount as a string (e.g. `,_jsx(_components.code,{children:`\"0.05\"`}),`). String to avoid float precision issues.`]})}),`\n`,_jsx(ParamField,{body:`paymentRequirement.currency`,type:`string`,required:true,id:`param-payment-requirement-currency`,children:_jsxs(_components.p,{children:[`Always `,_jsx(_components.code,{children:`\"USDC\"`}),` in v1. Reserved for future expansion.`]})}),`\n`,_jsx(ParamField,{body:`paymentRequirement.network`,type:`string`,required:true,id:`param-payment-requirement-network`,children:_jsxs(_components.p,{children:[`Stablecoin network. Today: `,_jsx(_components.code,{children:`\"solana\"`}),`. EVM chain support is planned.`]})}),`\n`,_jsx(ParamField,{body:`paymentRequirement.recipient`,type:`string`,required:true,id:`param-payment-requirement-recipient`,children:_jsx(_components.p,{children:`The address that should receive the USDC. The API validates this matches the 402 response’s intent.`})}),`\n`,_jsx(ParamField,{body:`paymentRequirement.description`,type:`string`,id:`param-payment-requirement-description`,children:_jsx(_components.p,{children:`Optional human-readable description from the resource. Logged in the audit trail.`})}),`\n`,_jsx(ParamField,{body:`paymentRequirement.resource`,type:`string`,id:`param-payment-requirement-resource`,children:_jsx(_components.p,{children:`Optional URL of the resource being paid for. Logged in the audit trail.`})}),`\n`,_jsx(Heading,{level:`2`,id:`response`,children:`Response`}),`\n`,_jsx(ResponseField,{name:`paymentHeader`,type:`string`,id:`param-payment-header`,children:_jsxs(_components.p,{children:[`The opaque value to attach to your retry request as the `,_jsx(_components.code,{children:`X-Payment`}),` header. The resource will validate it and serve the protected content.`]})}),`\n`,_jsx(ResponseField,{name:`transactionId`,type:`string`,id:`param-transaction-id`,children:_jsx(_components.p,{children:`Optional. Set if the payment resulted in an on-chain transaction (vs. a pre-funded credit pull). Use with chain explorers to confirm.`})}),`\n`,_jsx(Heading,{level:`2`,id:`what-the-api-checks-before-executing`,children:`What the API checks before executing`}),`\n`,_jsxs(_components.ol,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Authenticates`}),` the request (HMAC or API key).`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Looks up`}),` the agent and validates it’s not `,_jsx(_components.code,{children:`killed`}),` or `,_jsx(_components.code,{children:`paused`}),`.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Polls`}),` the kill switch state — refuses on active kill switch.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Validates`}),` all 3 budget layers atomically (Lua script in Redis):`,`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`infra`}),` — does the agent have infrastructure budget left?`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`tokens`}),` — does the agent have LLM token budget left? (informational here)`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`payments`}),` — does the requested `,_jsx(_components.code,{children:`amount`}),` fit under `,_jsx(_components.code,{children:`monthlyUSDC`}),` AND `,_jsx(_components.code,{children:`perTxUSDC`}),`?`]}),`\n`]}),`\n`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Checks approval threshold`}),`: if `,_jsx(_components.code,{children:`amount >= approvalThresholdUSDC`}),`, holds the payment and returns `,_jsx(_components.strong,{children:`HTTP 202`}),` with `,_jsx(_components.code,{children:`{ approvalId }`}),` instead of executing. Wait for human approval, then retry.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Validates wallet balance`}),`: rejects if the agent wallet doesn’t have enough USDC.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Executes`}),` the on-chain USDC transfer atomically.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Emits`}),` a `,_jsx(_components.code,{children:`payment`}),` event to the agent event stream (visible at `,_jsx(_components.code,{children:`GET /v1/agents/{id}/audit`}),`).`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Returns`}),` the payment header.`]}),`\n`]}),`\n`,_jsxs(_components.p,{children:[`The budget deduction (step 4) is `,_jsx(_components.strong,{children:`atomic`}),`: even if the agent makes 10 parallel `,_jsx(_components.code,{children:`x402-pay`}),` calls, the Lua deduction ensures no double-spend past the cap. The cap cannot be bypassed by code path manipulation in the agent.`]}),`\n`,_jsx(Heading,{level:`2`,id:`approval-gate-—-http-202`,children:`Approval gate — HTTP 202`}),`\n`,_jsx(_components.p,{children:`If the payment amount triggers the approval threshold, the response is:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`9`,language:`json`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`json`,children:_jsxs(_components.code,{language:`json`,numberOfLines:`9`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"success\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:`true`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"statusCode\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`202`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"data\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"approvalId\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"apr_xyz789\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"status\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"pending_approval\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:` \"expiresAt\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"2026-05-15T12:05:00.000Z\"`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`The SDK’s `,_jsx(_components.code,{children:`x402fetch`}),` handles this transparently — it polls `,_jsx(_components.code,{children:`/v1/signing/approvals/{id}`}),` every 5s until resolved or `,_jsx(_components.code,{children:`approvalTimeout`}),` (default 5 minutes), then retries the original request.`]}),`\n`,_jsx(_components.p,{children:`If you’re calling this endpoint directly, you must implement the same loop. Approvals can resolve in one of three states:`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`approved`}),` — proceed with the original retry using the payment header`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`rejected`}),` — surface the error to your agent’s reasoning; do not retry`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`expired`}),` — same as rejected; the threshold was set for a reason`]}),`\n`]}),`\n`,_jsx(Heading,{level:`2`,id:`common-errors`,children:`Common errors`}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Status`}),_jsx(_components.th,{children:`Cause`}),_jsx(_components.th,{children:`Fix / Recovery`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`401 invalid_auth`})}),_jsx(_components.td,{children:`HMAC headers missing or signature mismatch`}),_jsx(_components.td,{children:`Verify the SDK is correctly initialized; check secret rotation`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`401 agent_killed`})}),_jsxs(_components.td,{children:[`Agent in `,_jsx(_components.code,{children:`killed`}),` state`]}),_jsx(_components.td,{children:`Provision a new agent; this one is dead`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`402 budget_exhausted`})}),_jsxs(_components.td,{children:[`One or more budget layers empty. Response body includes `,_jsx(_components.code,{children:`failedLayers`})]}),_jsxs(_components.td,{children:[`Top up the budget via `,_jsx(_components.code,{children:`POST /v1/agents/{id}/budget`}),` and retry`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`402 insufficient_wallet_balance`})}),_jsx(_components.td,{children:`Budget OK but wallet has no USDC`}),_jsxs(_components.td,{children:[`Fund via `,_jsx(_components.code,{children:`POST /v1/agents/{id}/fund/prepare`}),` + `,_jsx(_components.code,{children:`/fund/confirm`})]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`503 kill_switch_active`})}),_jsx(_components.td,{children:`Global kill switch tripped`}),_jsx(_components.td,{children:`Wait for resolution; do not retry until kill switch clears`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`202 approval_required`})}),_jsx(_components.td,{children:`Above threshold`}),_jsx(_components.td,{children:`Poll the approval ID`})]})]})]}),`\n`,_jsxs(Heading,{level:`2`,id:`working-with-paymentrequirement`,children:[`Working with `,_jsx(_components.code,{children:`paymentRequirement`})]}),`\n`,_jsxs(_components.p,{children:[`The exact format of `,_jsx(_components.code,{children:`paymentRequirement`}),` depends on the 402-responding service. The SDK normalizes common variants:`]}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[`HTTP 402 with `,_jsx(_components.code,{children:`WWW-Authenticate: x402`}),` header`]}),`\n`,_jsxs(_components.li,{children:[`HTTP 402 with `,_jsx(_components.code,{children:`paymentRequirement`}),` JSON body`]}),`\n`,_jsxs(_components.li,{children:[`HTTP 402 with `,_jsx(_components.code,{children:`Payment-Required`}),` body field`]}),`\n`]}),`\n`,_jsx(_components.p,{children:`If you’re calling this endpoint without the SDK, parse the 402 response yourself and pass the requirement here as-is.`}),`\n`,_jsx(Heading,{level:`2`,id:`recommended-pattern`,children:`Recommended pattern`}),`\n`,_jsxs(_components.p,{children:[`Use the SDK’s `,_jsx(_components.code,{children:`x402fetch`}),` wrapper. It handles 402 detection, this endpoint call, header injection, and retry transparently — your agent code calls a normal `,_jsx(_components.code,{children:`fetch`}),` and never deals with payment plumbing directly. See `,_jsxs(_components.a,{href:`/agent/sdk#x402fetch`,children:[`SDK Reference — `,_jsx(_components.code,{children:`x402fetch`})]}),`.`]}),`\n`,_jsx(Heading,{level:`2`,id:`next-steps`,children:`Next steps`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsxs(_components.a,{href:`/agent/sdk#x402fetch`,children:[`SDK Reference — `,_jsx(_components.code,{children:`x402fetch`})]}),` — the recommended way to do this`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.a,{href:`/agent/flow-guide`,children:`Agent Kit Flow Guide`}),` — full agent lifecycle context`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`POST /v1/agents/{id}/budget`}),` — adjust spend limits if you hit them often`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`POST /v1/agents/{id}/fund/prepare`}),` — top up the agent wallet`]}),`\n`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Pay for an x402-gated resource","description":"The agent pays for a remote resource that requires USDC via the x402 protocol. Budget-checked, kill-switch-gated, atomically enforced.","sidebarTitle":"x402-pay","api":"POST /v1/agents/{id}/x402-pay","href":"/api-reference/flows/agent-x402-pay"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"When to call this directly vs use x402fetch","slug":"when-to-call-this-directly-vs-use-x402fetch","depth":2,"children":[]},{"title":"How the loop works (with x402fetch)","slug":"how-the-loop-works-with-x402fetch","depth":2,"children":[]},{"title":"Authentication","slug":"authentication","depth":2,"children":[]},{"title":"Request body","slug":"request-body","depth":2,"children":[]},{"title":"Response","slug":"response","depth":2,"children":[]},{"title":"What the API checks before executing","slug":"what-the-api-checks-before-executing","depth":2,"children":[]},{"title":"Approval gate — HTTP 202","slug":"approval-gate-—-http-202","depth":2,"children":[]},{"title":"Common errors","slug":"common-errors","depth":2,"children":[]},{"title":"Working with paymentRequirement","slug":"working-with-paymentrequirement","depth":2,"children":[]},{"title":"Recommended pattern","slug":"recommended-pattern","depth":2,"children":[]},{"title":"Next steps","slug":"next-steps","depth":2,"children":[]}],"codeExamples":{},"endpoint":{"title":"Pay for an x402-gated resource","path":"/v1/agents/{id}/x402-pay","method":"post","request":{"security":[],"parameters":{"query":{},"header":{},"cookie":{},"path":{}},"body":{"application/json":{"schemaArray":[{"type":"object","properties":{"paymentRequirement":[{"type":"object","properties":{},"description":"The payment terms received in the 402 response from the resource. Schema below.","required":true}],"paymentRequirement.amount":[{"type":"string","description":"Decimal USDC amount as a string (e.g. `\"0.05\"` ). String to avoid float precision issues.","required":true}],"paymentRequirement.currency":[{"type":"string","description":"Always `\"USDC\"` in v1. Reserved for future expansion.","required":true}],"paymentRequirement.network":[{"type":"string","description":"Stablecoin network. Today: `\"solana\"` . EVM chain support is planned.","required":true}],"paymentRequirement.recipient":[{"type":"string","description":"The address that should receive the USDC. The API validates this matches the 402 response’s intent.","required":true}],"paymentRequirement.description":[{"type":"string","description":"Optional human-readable description from the resource. Logged in the audit trail."}],"paymentRequirement.resource":[{"type":"string","description":"Optional URL of the resource being paid for. Logged in the audit trail."}]}}],"examples":{"example":{"value":{"paymentRequirement":{},"paymentRequirement.amount":"\u003cstring>","paymentRequirement.currency":"\u003cstring>","paymentRequirement.network":"\u003cstring>","paymentRequirement.recipient":"\u003cstring>","paymentRequirement.description":"\u003cstring>","paymentRequirement.resource":"\u003cstring>"}}}}}},"response":{"200":{"application/json":{"schemaArray":[{"type":"object","properties":{"paymentHeader":[{"type":"string","description":"The opaque value to attach to your retry request as the `X-Payment` header. The resource will validate it and serve the protected content."}],"transactionId":[{"type":"string","description":"Optional. Set if the payment resulted in an on-chain transaction (vs. a pre-funded credit pull). Use with chain explorers to confirm."}]}}],"examples":{"example":{"value":{"paymentHeader":"\u003cstring>","transactionId":"\u003cstring>"}}}}}},"deprecated":false}},"jsLinks":[],"subdomain":"relayerfi","siteName":"Relayer.fi","title":"Pay for an x402-gated resource - Relayer.fi","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-05-16T22:24:33.390Z","originalFileLocation":"api-reference/flows/agent-x402-pay.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"The agent pays for a remote resource that requires USDC via the x402 protocol. Budget-checked, kill-switch-gated, atomically enforced.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Relayer.fi\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/relayerfi/FmuHExnVftyvFhdQ/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/relayerfi/FmuHExnVftyvFhdQ/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/relayerfi/FmuHExnVftyvFhdQ/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/relayerfi/FmuHExnVftyvFhdQ/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/relayerfi/FmuHExnVftyvFhdQ/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/relayerfi/FmuHExnVftyvFhdQ/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/relayerfi/FmuHExnVftyvFhdQ/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/relayerfi/FmuHExnVftyvFhdQ/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/relayerfi/FmuHExnVftyvFhdQ/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Pay for an x402-gated resource - Relayer.fi\">\u003cmeta data-mint-head property=\"og:description\" content=\"The agent pays for a remote resource that requires USDC via the x402 protocol. Budget-checked, kill-switch-gated, atomically enforced.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Relayer.fi\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.relayer.fi/api-reference/flows/agent-x402-pay\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://relayerfi.mintlify.site/_mintlify/api/og/v2?division=Runtime+%28HMAC%29\u0026amp;title=Pay+for+an+x402-gated+resource\u0026amp;description=The+agent+pays+for+a+remote+resource+that+requires+USDC+via+the+x402+protocol.+Budget-checked%2C+kill-switch-gated%2C+atomically+enforced.\u0026amp;theme=ac545d78a150f4a69952bd9f\u0026amp;signature=3669c469ae741fe69de34464fbc18e949ef38de6d6d9412ce09a48cfb9cded81\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Pay for an x402-gated resource - Relayer.fi\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"The agent pays for a remote resource that requires USDC via the x402 protocol. Budget-checked, kill-switch-gated, atomically enforced.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://relayerfi.mintlify.site/_mintlify/api/og/v2?division=Runtime+%28HMAC%29\u0026amp;title=Pay+for+an+x402-gated+resource\u0026amp;description=The+agent+pays+for+a+remote+resource+that+requires+USDC+via+the+x402+protocol.+Budget-checked%2C+kill-switch-gated%2C+atomically+enforced.\u0026amp;theme=ac545d78a150f4a69952bd9f\u0026amp;signature=3669c469ae741fe69de34464fbc18e949ef38de6d6d9412ce09a48cfb9cded81\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/relayerfi/FmuHExnVftyvFhdQ/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Relayer.fi\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#015F51\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.relayer.fi/api-reference/flows/agent-x402-pay\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/flows/agent-x402-pay.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.relayer.fi/#organization\",\"name\":\"Relayer.fi\",\"url\":\"https://docs.relayer.fi\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/relayerfi/HPPc29pDPmX_uuYf/images/relayer-isotype-petrol.svg?fit=max\u0026auto=format\u0026n=HPPc29pDPmX_uuYf\u0026q=85\u0026s=4793c846712b8d1c6e643ece66ba100c\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.relayer.fi#website\",\"name\":\"Relayer.fi\",\"url\":\"https://docs.relayer.fi\",\"publisher\":{\"@id\":\"https://docs.relayer.fi/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.relayer.fi/api-reference/flows/agent-x402-pay#webpage\",\"url\":\"https://docs.relayer.fi/api-reference/flows/agent-x402-pay\",\"name\":\"Pay for an x402-gated resource\",\"description\":\"The agent pays for a remote resource that requires USDC via the x402 protocol. Budget-checked, kill-switch-gated, atomically enforced.\",\"dateModified\":\"2026-05-16T22:24:33.390Z\",\"isPartOf\":{\"@id\":\"https://docs.relayer.fi#website\"},\"breadcrumb\":{\"@id\":\"https://docs.relayer.fi/api-reference/flows/agent-x402-pay#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.relayer.fi/api-reference/flows/agent-x402-pay#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Agents\",\"item\":\"https://docs.relayer.fi/api-reference/agents/list-all-agents-for-the-integrator\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Runtime (HMAC)\",\"item\":\"https://docs.relayer.fi/api-reference/agents/get-agent-status-and-kill-switch-state-hmac-or-api-key\"},{\"@type\":\"ListItem\",\"position\":3,\"name\":\"Pay for an x402-gated resource\",\"item\":\"https://docs.relayer.fi/api-reference/flows/agent-x402-pay\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.relayer.fi/api-reference/flows/agent-x402-pay#apireference\",\"headline\":\"Pay for an x402-gated resource\",\"name\":\"Pay for an x402-gated resource\",\"description\":\"The agent pays for a remote resource that requires USDC via the x402 protocol. Budget-checked, kill-switch-gated, atomically enforced.\",\"url\":\"https://docs.relayer.fi/api-reference/flows/agent-x402-pay\",\"mainEntityOfPage\":{\"@id\":\"https://docs.relayer.fi/api-reference/flows/agent-x402-pay#webpage\"},\"dateModified\":\"2026-05-16T22:24:33.390Z\",\"publisher\":{\"@id\":\"https://docs.relayer.fi/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.relayer.fi#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Relayer.fi\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Relayer.fi\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/api-reference/flows/agent-x402-pay.md","siteName":"Relayer.fi","nav":{"global":{"anchors":[{"anchor":"Website","icon":"globe","href":"https://relayer.fi"},{"anchor":"GitHub","icon":"github","href":"https://github.com/relayerfi"}]},"tabs":[{"tab":"Get Started","pages":[{"title":"Get Started","href":"/get-started/overview"}]},{"tab":"Signing Kit","pages":[{"title":"Signing Kit","href":"/signing/overview"}]},{"tab":"Payout Kit","pages":[{"title":"Payout Kit","href":"/payout/overview"}]},{"tab":"Agent Kit","pages":[{"title":"Agent Kit","href":"/agent/overview"}]},{"tab":"Widget Kit","pages":[{"title":"Widget Kit","href":"/widget/overview"}]},{"tab":"API Reference","groups":[{"group":"Introduction","pages":[{"title":"API Reference","sidebarTitle":"Introduction","href":"/api-reference/introduction"}]},{"group":"Wallets","pages":[]},{"group":"Addresses","pages":[]},{"group":"Transactions","pages":[{"title":"List transactions awaiting passkey signature","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /transactions/pending-signature","href":"/api-reference/transactions/list-transactions-awaiting-passkey-signature"},{"title":"List signed transactions","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /transactions/sign","href":"/api-reference/transactions/list-signed-transactions"},{"title":"Get signed transaction details","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /transactions/sign/{transactionId}","href":"/api-reference/transactions/get-signed-transaction-details"},{"title":"Cancel a pending transaction","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /transactions/sign/{transactionId}","href":"/api-reference/transactions/cancel-a-pending-transaction"},{"title":"Broadcast a signed transaction","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /transactions/broadcast/{transactionId}","href":"/api-reference/transactions/broadcast-a-signed-transaction"},{"title":"Broadcast a raw signed transaction","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /transactions/broadcast/raw","href":"/api-reference/transactions/broadcast-a-raw-signed-transaction"},{"title":"Get broadcast status","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /transactions/broadcast/{transactionId}","href":"/api-reference/transactions/get-broadcast-status"},{"title":"Retry broadcasting a failed transaction","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /transactions/broadcast/{transactionId}/retry","href":"/api-reference/transactions/retry-broadcasting-a-failed-transaction"}]},{"group":"Widget Actions","pages":[{"title":"Widget Actions — overview","sidebarTitle":"Overview","href":"/api-reference/flows/actions-intro"},{"title":"Generate metadata for Swap application","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /action/builders/swap","href":"/api-reference/action:-builders/generate-metadata-for-swap-application"},{"title":"Generate metadata for Native Token Transfer application","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /action/builders/transfer-native","href":"/api-reference/action:-builders/generate-metadata-for-native-token-transfer-application"},{"title":"Generate metadata for Crosschain Transfer application","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /action/builders/crosschain-transfer","href":"/api-reference/action:-builders/generate-metadata-for-crosschain-transfer-application"},{"title":"Generate metadata for Crosschain Bridge application","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /action/builders/crosschain-bridge","href":"/api-reference/action:-builders/generate-metadata-for-crosschain-bridge-application"},{"title":"Get the Directory data","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /action/directory","href":"/api-reference/action:-directory/get-the-directory-data"},{"title":"Retrieve protocol token list for a chain","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /action/tokens/{chain}/{protocol}","href":"/api-reference/action:-tokens/retrieve-protocol-token-list-for-a-chain"}]},{"group":"Agents","pages":[{"group":"Operator (api-key)","pages":[{"title":"List all agents for the integrator","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /agents","href":"/api-reference/agents/list-all-agents-for-the-integrator"},{"title":"Get agent details","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /agents/{id}","href":"/api-reference/agents/get-agent-details"},{"title":"Pause an agent (reversible)","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /agents/{id}/pause","href":"/api-reference/agents/pause-an-agent-reversible"},{"title":"Resume a paused agent","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /agents/{id}/resume","href":"/api-reference/agents/resume-a-paused-agent"}]},{"group":"Runtime (HMAC)","pages":[{"title":"Get agent status and kill-switch state (HMAC or API key)","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /agents/{id}/status","href":"/api-reference/agents/get-agent-status-and-kill-switch-state-hmac-or-api-key"},{"title":"Get agent wallet balance with budget context (HMAC or API key)","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /agents/{id}/balance","href":"/api-reference/agents/get-agent-wallet-balance-with-budget-context-hmac-or-api-key"},{"title":"Get agent budget state (HMAC or API key)","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /agents/{id}/budget","href":"/api-reference/agents/get-agent-budget-state-hmac-or-api-key"},{"title":"Sign a Solana transaction for an agent","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /agents/{id}/sign-transaction","href":"/api-reference/agents/sign-a-solana-transaction-for-an-agent"},{"title":"Batch ingest agent events (up to 100)","description":"\u003c!-- relayer:auth-badge:start -->\n> **Auth: agent HMAC.** Called by the agent SDK at runtime with `x-agent-id`, `x-agent-auth`, `x-request-timestamp` headers. **Not callable from backend ApiKey.** See [Authentication → Agent HMAC](/get-started/authentication).\n\u003c!-- relayer:auth-badge:end -->","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /agents/events/batch","href":"/api-reference/agents/batch-ingest-agent-events-up-to-100"},{"title":"Pay for an x402-gated resource","sidebarTitle":"x402-pay","api":"POST /v1/agents/{id}/x402-pay","href":"/api-reference/flows/agent-x402-pay"}]}]},{"group":"Beneficiaries","pages":[]},{"group":"Global Payout","pages":[{"title":"Set up a payout account — Step 1","description":"Step 1 of the 2-step payout account setup. Creates a crypto withdrawal address linked to a recipient's bank account.","sidebarTitle":"Setup withdrawal address","api":"POST /v1/payout/accounts/setup/liquidation-address","href":"/api-reference/flows/payout-setup"},{"title":"Set up a payout account — Step 2","sidebarTitle":"Setup virtual account","api":"POST /v1/payout/accounts/setup/virtual-account","href":"/api-reference/flows/payout-virtual-account"},{"title":"Get a payment quote (MXN → USD)","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /payout/accounts/quote","href":"/api-reference/payout:-accounts/get-a-payment-quote-mxn-→-usd"},{"title":"Execute a fiat payment","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /payout/accounts/execute","href":"/api-reference/payout:-accounts/execute-a-fiat-payment"},{"title":"List all payments for the authenticated integrator","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /payout/accounts","href":"/api-reference/payout:-accounts/list-all-payments-for-the-authenticated-integrator"},{"title":"Get payment status by reference","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /payout/accounts/{reference}/status","href":"/api-reference/payout:-accounts/get-payment-status-by-reference"}]},{"group":"On-ramp","pages":[{"title":"Get an on-ramp quote (fiat → stablecoin)","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /payout/onramp/quote","href":"/api-reference/payout:-on-ramp/get-an-on-ramp-quote-fiat-→-stablecoin"},{"title":"Create or get a deposit account (idempotent)","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /payout/onramp/deposit-accounts","href":"/api-reference/payout:-on-ramp/create-or-get-a-deposit-account-idempotent"},{"title":"List my deposit accounts","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /payout/onramp/deposit-accounts","href":"/api-reference/payout:-on-ramp/list-my-deposit-accounts"},{"title":"Get a single deposit account by id","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /payout/onramp/deposit-accounts/{id}","href":"/api-reference/payout:-on-ramp/get-a-single-deposit-account-by-id"},{"title":"List lifecycle events for a deposit account","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /payout/onramp/deposit-accounts/{id}/events","href":"/api-reference/payout:-on-ramp/list-lifecycle-events-for-a-deposit-account"}]}]}]},"basePath":"","title":"Pay for an x402-gated resource - Relayer.fi","deploymentId":"dpl_2pTxFtyBudBMYZiCw1MyvoA1wxpd","buildId":"dpl_2pTxFtyBudBMYZiCw1MyvoA1wxpd","dynamics":["c2aa737661","2b790eda92","b0f84f53ff"],"chunks":["OpenApiReferenceProvider-BtG4DSkw.js","snippetPresets-C1k1xDhp.js","utils-PMJoEt4Y.js","style-to-object-BY3JEAdk.js","utils-DW3Pr7Jq.js","v4-DIgz8zy6.js","addUniqueKeysToSchema-DIISLO2w.js","conditional-requirements-CFM0id0Q.js","cloneDeep-BErNCZCm.js","_Uint8Array-f0PCu9f_.js","isObject-FP1Yky1u.js","ApiExamples-OjY-8mqu.js","usePlaygroundInputsStore-B2HS2hUb.js","shallow-DVFuuIDQ.js","isEqual-DG0UKiQC.js","CodeSnippets-Cy6FBgwN.js","CodeSnippet-D1PtG8ed.js","getApiPlaygroundDisplay-Dkx2eNtL.js","Page-C8Cg25if.js","DynamicMarkdown-BvJIe00T.js","SectionHeading-B0rKYV8d.js","icon-yclzBff4.js","MethodPill-DxA11cCF.js","getPastedJson-CpkIDpMk.js","DuplicateIcon-CFCQNJ-D.js","axios-CsQoIw0U.js"]}