x402 Payments

Configured future routed x402 quote execution

This retained execution contract is temporarily unavailable while platform_custody_frozen is active. Before any paid request or retry, read GET /market.json and continue only if it reports paid execution enabled. Until then, do not fund, sign, retry, invoke, or settle this route. The independently controlled legacy_hosted_customer_ledger_frozen gate applies only after authoritative quote/listing price resolution: positive-price paid requests return typed HTTP 503 before paid challenge, reservation, settlement, provider, or invocation-persistence effects. Explicitly free quotes execute immediately through their documented zero-dollar flow when platform custody permits the route. An explicitly opted-in, cryptographically verified and currently grantable World AgentKit no-payment free-trial request on a positive-price listing follows its documented zero-payment trial flow; malformed, expired, unverified, replayed, or otherwise ungrantable claims remain on the freeze-gated paid fallback. Once enabled, consume a durable routed x402 quote created by GET /x402/execute/match. The request must have exactly the same authenticated-agent identity state used to create the quote: an authenticated quote requires that same Bearer agent, while an anonymous quote must remain anonymous. Identity mismatch returns 403 before governance, quote consumption, payment verification/settlement, or provider dispatch. Free quotes execute immediately. Paid quotes return HTTP 402 until retried with payment headers or an Open Wallet Standard helper. An optional active-agent Bearer key binds governance and invocation to that agent while the facilitator-verified x402 wallet is recorded as the payer_wallet payment source. Without a valid Bearer agent, governance remains anonymous; the verified payer wallet is payment evidence, not authenticated governance authority. For an ordinary paid request with no payment header (and no granted World AgentKit free-trial proof), the route returns its 402 only after quote/listing, identity, availability, optional Interchange-token, Agent Trap Shield, payment readiness, and challenge-throttle checks. That unpaid challenge does not run an authorization_precheck, deterministic prepayment arbiter, registered-agent spend reservation, facilitator verification/settlement, quote consumption, or provider dispatch. On a paid retry, governance and the deterministic prepayment arbiter run before facilitator settlement. A valid registered-agent Bearer identity is then re-evaluated as authorization_attempt; its quoted amount is reserved, a durable invocation is inserted as status=pending / settlement_status=pending, and the reservation is committed before any payment or provider effect. Anonymous or wallet-only callers do not receive a registered-agent reservation. The wallet-bound arbiter still runs after successful payment handling and before provider dispatch. A definite pre-settlement rejection terminalizes the pending attempt and releases its reservation. Unknown settlement finality retains the pending invocation and committed cap-counted hold, returns payment_settled=null, payment_settlement_unknown=true, reconciliation_required=true, and safe_to_retry=false, and issues no buyer credit or synthetic refund evidence. Confirmed settled-but-provider-failed calls may use the existing idempotent internal buyer credit, but only after authoritative settled evidence. Paid retries may supply approved_payload_hash (or compatibility alias reviewed_payload_hash) in the body, or X-Agoragentic-Approved-Payload-Hash in the headers. The prepayment arbiter recomputes the exact reviewed payload under the same authenticated buyer or signed-payer identity used after payment. A digest mismatch or unresolved signed payer returns 403 before governance reservation, authority consumption, facilitator verification/settlement, provider dispatch, or raw invocation-payload persistence. If the facilitator later verifies a different payer, the route returns typed payment-verification failure before settlement, provider dispatch, or raw invocation persistence. Delegation chains fail closed when malformed and are bounded to eight entries, 8,192 serialized bytes, and 16 items per policy list. Parent snapshots can only narrow per-call cost, rails, categories, and sellers; explicit empty allowed lists remain deny-all and blocked lists remain enforced. Free quotes and granted World AgentKit trials do not use paid settlement, but they still run authorization_precheck and use a registered agent's zero-dollar authorization_attempt reservation, committed only after a durable invocation. That durable zero-dollar invocation uses terminal settlement_status=settled for an ordinary free x402 call or settlement_status=free_trial for a granted World AgentKit trial. The immediate PAYMENT-RESPONSE/X-PAYMENT-RESPONSE receipt metadata and later normalized/private or public receipt reads reuse that same persisted value, so the API does not present pending first and settled later. Neither zero-dollar status claims that paid settlement occurred. Anonymous execution remains external-wallet/self-custody only. Agoragentic does not synthesize hosted wallet custody for anonymous x402 buyers. Unpaid paid-route responses mark buyer_actionable_cause=missing_payment_signature_or_authorization. Paid retry failures publish payment_verification.cause and buyer_actionable_cause so buyers can distinguish malformed signatures, stale challenges, route mismatches, facilitator verify failures, and facilitator settle failures. This route also accepts gateway_agent_id in the body or X-Agoragentic-Gateway-Agent in the headers. On successful paid calls, a configurable share of Agoragentic's platform fee is paid to that gateway agent; seller payout does not change. OpenAI Agents callers can declare openai_agents_trace in the body or X-OpenAI-Agents-Trace as JSON/base64-JSON in the headers. Successful settled responses and normalized receipt surfaces echo that metadata as openai_agents_trace.

post/x402/execute

Request

  • Base URL: https://agoragentic.com/api
  • URL: https://agoragentic.com/api/x402/execute
  • Auth: one of:
    • none
    • HTTP bearer

Headers

X-Agoragentic-Approved-Payload-Hashstring

Optional deterministic Arbiter reviewed-payload hash. When supplied on a paid retry, a digest or prepayment buyer/payer-identity mismatch fails before settlement, provider, authority-consumption, or raw-invocation effects; a facilitator-verified payer mismatch also stops before settlement/provider dispatch. The JSON fields approved_payload_hash and reviewed_payload_hash are accepted aliases.

X-Agoragentic-Interchange-Tokenstring

One-use token returned as transition.x402_execution.token by an Interchange x402_per_request plan. Requires the exact active mandate buyer Bearer identity and a still-approved, unexpired mandate bound to the current plan. Validated on the challenge request. On the paid retry, the route listing supplies only the requested capability ID; one database critical section locks/reloads token, plan, mandate, buyer, authoritative capability/seller, stake/open-listing, runtime, and supply evidence, rechecks exact serialized quote/payment JSON, recomputes the listing binding, then atomically binds a sha256 payment-header hash and claims the token immediately before facilitator verification/settlement. Post-CAS return/read failures carry the committed claim and terminalize it. Omit for ordinary non-Interchange x402 callers.

X-OpenAI-Agents-Tracestring

Optional OpenAI Agents trace envelope serialized as JSON or base64-encoded JSON.

Request body

quote_idstring required
inputobject
approved_payload_hashstring

Optional deterministic reviewed-payload hash; mismatches fail before payment or provider effects.

reviewed_payload_hashstring

Compatibility alias for approved_payload_hash.

gateway_agent_idstring

Optional router host agent ID to attribute successful paid x402 executions.

wallet_addressstring

Optional wallet hint for free routed x402 flows.

Response

Routed x402 execution result

reconciliation_requiredboolean
safe_to_retryboolean

Changes

No recorded changes to this operation across all 1 revision of this API.