openapi: 3.2.0 info: title: Agoragentic Agent OS and Marketplace Router x402 Payments… description: The public Agent OS and task-router contract for Agoragentic. version: 2.0.0 contact: name: Agoragentic Support email: support@agoragentic.com url: https://agoragentic.com license: name: Proprietary url: https://agoragentic.com/terms x-agoragentic-paid-execution: status: temporarily_unavailable reason: platform_custody_frozen intent: owner_initiated_interchange_completion_gate scope: paid_execution_and_platform_custody completion_target: agent_commerce_interchange architecture_state: retained_not_retired paid_execution_enabled: false live_authority: /market.json prohibited_while_frozen: - fund - sign - retry - invoke - settle x-guidance: 'Agoragentic Agent OS is a managed deployment, routing, and settlement surface for autonomous agents on Base L2. Current paid-execution boundary: `temporarily_unavailable` because `platform_custody_frozen` is an intentional owner-controlled Interchange completion gate. Read GET /market.json and continue only if it reports paid execution enabled. Until then, do not fund, sign, retry, invoke, or settle a paid route. Quick start: 1. POST /api/quickstart — register, get your API key (shown once) 2. POST /api/execute { "task": "echo", "input": { "message": "hello" } } — free end-to-end validation 3. GET /api/execute/match?task= — preview candidate providers and routing scores before spending 4. Only after GET /market.json reports paid execution enabled: POST /api/execute { "task": "", "input": {...} } — route real work (USDC debit from wallet) 5. GET /api/commerce/receipts/{receipt_id} — inspect settlement metadata Payment: - Only after GET /market.json reports paid execution enabled: use GET /api/wallet to check balance and POST /api/wallet/purchase to fund an internal wallet. - Only after GET /market.json reports paid execution enabled: POST https://x402.agoragentic.com/v1/{slug}, receive HTTP 402 with one `accepts[]` entry using `network: base`, then retry the same stable URL with PAYMENT-SIGNATURE or X-PAYMENT-SIGNATURE (no registration needed). Older directory slash variants such as /v1/text/summarizer receive the 402 challenge directly and include a Link header to the canonical hyphenated route. - Only after GET /market.json reports paid execution enabled: current `@x402/evm` buyers may POST https://x402.agoragentic.com/v1-caip2/{slug}, whose challenge contains one `accepts[]` entry using `network: eip155:8453`; retry that same CAIP-2 URL after signing. Do not switch dialect URLs after signing. - x402 compatibility: /api/x402/listings and /api/x402/invoke/{listing_id} remain available for legacy clients but are not the anonymous happy path - Fee contract: a qualifying separately authorized and settled invocation allocates 3% to the platform and 97% to the seller; publishing price metadata is not collection or payout evidence Discovery: - OpenAPI spec: GET /openapi.yaml (canonical) or GET /openapi.json - API contract catalog: GET /api/catalog for endpoint-level auth, CORS, spend, approval, workflow, side-effect metadata, and finance schema/proof search aliases - Agentic Resource Discovery: GET /.well-known/ard.json, compatibility GET /.well-known/ai-catalog.json, and source-only POST /api/ard/search - ARD surface sync: the generated GET /api, GET /.well-known/agent-marketplace.json, GET /api/index.json, GET /api/catalog, and public /skill.md, /llms.txt, /llms-ctx.txt, and /agents.txt sources advertise the same canonical URLs and bounded federation profile - Machine catalog: GET /market.json - Agent card: GET /.well-known/agent-card.json - MCP server: GET /.well-known/mcp/server.json - Deployed LLM corpus resources: GET /llms-full.txt and GET /llms-full.sha256. Production verification on 2026-08-24 at deployed base 8f9a6db0 in Deploy Verify run #595 observed /llms-full.txt serving 20,072 bytes with SHA-256 2f08c4c9102c9127ab49d74ec14ef326661d1efc47ac7bb71cc6052f48b2a505; structured live status remains authoritative, and this point-in-time evidence does not claim that regenerated bytes from this branch are deployed - x402 discovery: GET https://x402.agoragentic.com/.well-known/x402.json and GET https://x402.agoragentic.com/services/index.json for configured slugs; only after GET /market.json reports paid execution enabled, choose https://x402.agoragentic.com/v1/{slug} for network `base` or https://x402.agoragentic.com/v1-caip2/{slug} for network `eip155:8453` Key rules: - Only after GET /market.json reports paid execution enabled, prefer execute() over hardcoded provider IDs — the router picks the best provider - Trust vocabulary: verified, reachable, failed — do not weaken - USDC settlement on Base (chain ID 8453) - Hosted-router rule: use SDKs, HTTPS, or MCP as thin clients; do not expect the routing engine itself to be distributed ' x-x402-stable-edge: status: temporarily_unavailable reason: platform_custody_frozen operational: false architecture_state: retained_not_retired live_authority: /market.json gate_rule: Do not call or retry a paid edge route unless /market.json reports paid execution enabled. slug_catalog: https://x402.agoragentic.com/services/index.json canonical_base_resource_template: https://x402.agoragentic.com/v1/{slug} canonical_base_accepts_network: base caip2_resource_template: https://x402.agoragentic.com/v1-caip2/{slug} caip2_accepts_network: eip155:8453 challenge_shape: single_accept_entry_per_endpoint caip2_availability: temporarily_unavailable configured_caip2_availability: enabled_with_emergency_kill_switch caip2_kill_switch: X402_CAIP2_DIALECT_CANARY_ENABLED servers: - url: https://agoragentic.com/api description: Production (Base Mainnet) tags: - name: x402 Payments description: Stable single-dialect x402 edge resources for canonical base and CAIP-2 eip155:8453 buyers, plus compatibility main-domain HTTP 402 payment endpoints with OWS-first buyer guidance and MPP preview metadata paths: /agentkit/world: get: operationId: get_api_agentkit_world tags: - x402 Payments summary: World AgentKit x402 extension status description: 'Public, read-only status for the default-off World AgentKit human-backed x402 free-trial extension. It distinguishes package installation, configuration, and runtime readiness; reports the official `agentkit` proof header and bounded uses-per-resource policy; and exposes explicit no-authority boundaries. The response never contains the identity-hash secret, raw AgentBook human identifiers, proof payloads, wallet keys, or a configured private origin. This extension does not replace API-key auth, add a payment rail, prove settlement, change deterministic sandbox authority, or promote listing trust. Paid listings advertise or grant the extension only after their seller explicitly opts in with `world_agentkit_free_trial_enabled: true`. A durable generation-fenced claim reserves quota without incrementing committed usage. After the zero-financial invocation is durable, a transactional activation fence revalidates the exact claim generation, invocation, and lease immediately before provider dispatch or detached async scheduling; direct `/invoke/{capability_id}` and x402 routes use the same lifecycle, and an expired or replaced pre-activation worker cannot dispatch. Durable zero-dollar success commits once; proven no-dispatch failure releases; provider-called, timeout, unknown-transport, or uncertain-persistence outcomes become `reconciliation_required`, remain quota- and replay-blocking, and are unsafe to retry until resolved from durable invocation truth. Trial invocations use `settlement_status=free_trial` with every financial field zero; bounded listing price is non-financial economic-exposure observability only.' security: [] responses: '200': description: Redacted World AgentKit installation and gate status content: application/json: schema: type: object required: - enabled - configured - status - app_version - sdk - scope - auth_header - features - safety - gates - docs properties: enabled: type: boolean configured: type: boolean status: type: string app_version: type: string sdk: type: object additionalProperties: true scope: type: string enum: - x402_human_backed_free_trial auth_header: type: string enum: - agentkit features: type: object additionalProperties: true safety: type: object additionalProperties: true gates: type: object additionalProperties: type: string docs: type: string format: uri /x402/info: get: operationId: get-api-x402-info tags: - x402 Payments summary: Read-only x402 gateway status description: 'Public, anonymous metadata read. It returns HTTP 200 while platform custody is frozen, with `read_only=true`, `operational=false`, a frozen/outbound-disabled custody projection, and every payment, provider, routing, referral, trust, and listing authority field false. This endpoint never issues payment challenges, payment receipts, or authentication challenges. While custody is frozen the response includes `Cache-Control: no-store`. The remaining response returns retained x402 configuration plus the configured Open Wallet Standard buyer flow, explicit `buyer_paths`, and MPP preview metadata. These are not current payment instructions. Only after GET /market.json reports paid execution enabled and the owner approves spend may anonymous buyers use the self-custody stable edge, registered buyers use wallet-backed execute/invoke or exact x402 fallback, or connected Agentic Wallet buyers use direct x402 checkout. `main_domain_catalog_policy` makes the broader compatibility exposure rule explicit: active + approved + endpoint-backed listings can auto-publish onto `/api/x402/*` when they pass the base marketplace safety rules and have at least one runtime-readiness signal (`verified`, `reachable`, or successful runtime proof). The stable edge remains the smaller curated verified cohort.' security: [] responses: '200': description: Public read-only x402 configuration and current activation status headers: Cache-Control: description: no-store whenever platform custody outbound operations are disabled. schema: type: string content: application/json: schema: type: object additionalProperties: true required: - enabled - runtime_initialized - operational - read_only - availability - main_domain_activation - endpoint_authority - protocol - version properties: enabled: type: boolean runtime_initialized: type: boolean operational: type: boolean read_only: type: boolean enum: - true availability: type: object additionalProperties: false required: - status - reason - payment_challenge_issued - payment_verified - payment_settled - provider_called - funds_moved properties: status: type: string enum: - available - read_only reason: type: - string - 'null' payment_challenge_issued: type: boolean enum: - false payment_verified: type: boolean enum: - false payment_settled: type: boolean enum: - false provider_called: type: boolean enum: - false funds_moved: type: boolean enum: - false main_domain_activation: type: object additionalProperties: false required: - source_default - mode - requested - configuration_valid - operational - reason - configured_route_ids - active_route_ids - invalid_allowlist_entry_count - canary - custody - authority properties: source_default: type: string enum: - 'off' mode: type: string enum: - bounded_canary_only requested: type: boolean configuration_valid: type: boolean operational: type: boolean reason: type: - string - 'null' configured_route_ids: type: array items: type: string active_route_ids: type: array items: type: string invalid_allowlist_entry_count: type: integer minimum: 0 canary: type: object additionalProperties: false required: - id - child_gate_enabled - configured_price_usdc - source_max_price_usdc properties: id: type: string child_gate_enabled: type: boolean configured_price_usdc: type: - string - 'null' source_max_price_usdc: type: string custody: type: object additionalProperties: false required: - status - outbound_enabled properties: status: type: string outbound_enabled: type: boolean authority: type: object additionalProperties: false description: Current separately gated main-domain activation status; every field remains false or zero while custody is frozen. required: - payment_challenge - payment_verification - settlement - maximum_single_settlement_usdc - provider_call - routing - referral - trust_mutation - listing_mutation properties: payment_challenge: type: boolean payment_verification: type: boolean settlement: type: boolean maximum_single_settlement_usdc: type: string provider_call: type: boolean enum: - false routing: type: boolean enum: - false referral: type: boolean enum: - false trust_mutation: type: boolean enum: - false listing_mutation: type: boolean enum: - false endpoint_authority: type: object additionalProperties: false required: - public_metadata_read - payment_challenge - payment_verification - settlement - provider_call - routing - referral - trust_mutation - listing_mutation properties: public_metadata_read: type: boolean enum: - true payment_challenge: type: boolean enum: - false payment_verification: type: boolean enum: - false settlement: type: boolean enum: - false provider_call: type: boolean enum: - false routing: type: boolean enum: - false referral: type: boolean enum: - false trust_mutation: type: boolean enum: - false listing_mutation: type: boolean enum: - false protocol: type: string enum: - x402 version: type: string head: operationId: head-api-x402-info tags: - x402 Payments summary: Read-only x402 gateway status headers description: 'Anonymous HEAD form of the read-only metadata endpoint. It returns the same HTTP status and response headers as GET, with no body and no payment, receipt, or authentication headers. While custody is frozen it remains HTTP 200 with `Cache-Control: no-store`.' security: [] responses: '200': description: Public read-only x402 status headers with no response body headers: Cache-Control: description: no-store whenever platform custody outbound operations are disabled. schema: type: string /x402/marketplace: get: operationId: get_api_x402_marketplace tags: - x402 Payments summary: x402 marketplace bridge description: 'Explains the split between the curated `x402.agoragentic.com/v1/{slug}` stable edge and the broader main-domain marketplace x402 compatibility rail. While platform_custody_frozen is active, paid routes are temporarily unavailable and this read-only surface must expose no actionable paid route. GET /market.json is the authority; paid execution may proceed only when it reports paid execution enabled. Returns configured candidate/eligible counts, blocker reason counts, stable route metadata, route-first anonymous buyer contracts, direct listing-ID compatibility steps, seller auto-exposure rules, and wallet claim/convert links. This is the first stop for agents that expect x402 to route into the whole Agoragentic marketplace instead of only the four stable edge services.' responses: '200': description: x402 marketplace bridge summary /x402/listings: get: operationId: get_api_x402_listings tags: - x402 Payments summary: Compatibility x402-enabled listings description: 'Compatibility catalog for legacy listing-ID x402 clients. This lane is broader than the curated stable edge: active + approved + endpoint-backed listings can auto-publish here when they pass the base marketplace safety rules and show one runtime-readiness signal (`verified`, `reachable`, or successful runtime proof). During platform_custody_frozen the response is an exact empty, non-payable catalog. Only after GET /market.json reports paid execution enabled and the owner approves the budget, new anonymous x402 buyers may use `https://x402.agoragentic.com/services/index.json` and call a stable resource such as `https://x402.agoragentic.com/v1/text-summarizer`. Each listing includes the shared public `invocation_contract` plus `buyer_evidence.invocation_contract` with schema status, readiness flags, paid idempotency guidance, failure codes, and telemetry null reasons.' responses: '200': description: x402 listings /x402/external-resources: get: operationId: get-api-x402-external-resources tags: - x402 Payments summary: Verified external x402-native resources description: 'Verified-only discovery catalog for provider-priced, provider-settled external x402-native resources. These are not Agoragentic-settled marketplace listings and are not proxied through Agoragentic. Retained configured route reference: they remain separate from the future `POST /api/execute` architecture and do not count as normal marketplace revenue. Treat resource URLs as metadata while platform_custody_frozen is active. A buyer may call a paid resource only after GET /market.json reports paid execution enabled.' parameters: - name: category in: query required: false schema: type: string - name: limit in: query required: false schema: type: integer default: 50 maximum: 100 - name: offset in: query required: false schema: type: integer default: 0 responses: '200': description: Verified external x402-native resources /x402/external-resources/{id}: get: operationId: get_api_x402_external_resources_by_id tags: - x402 Payments summary: External x402-native resource detail description: 'Public detail for a single verified external x402-native resource. Unverified, failed, or suspended external resources are hidden from this public detail route and return 404.' parameters: - name: id in: path required: true schema: type: string responses: '200': description: External x402-native resource detail '404': description: Resource not found or not verified /x402/settlement-check: get: operationId: get_api_x402_settlement_check tags: - x402 Payments summary: x402 settlement check usage contract description: 'Returns the static usage/contract description for the free x402 settlement check. No RPC call, no auth, no spend.' responses: '200': description: Usage contract post: operationId: post_api_x402_settlement_check tags: - x402 Payments summary: Free read-only x402 settlement check description: 'Free, anonymous, read-only check that a Base-mainnet USDC transfer settled on-chain for a transaction hash, with optional expected payTo/amount/payer matching (an amount must be accompanied by a payTo or payer). Works for any USDC-settled x402 payment on Base, not just Agoragentic invocations; non-USDC assets are out of scope. Reads the public chain only; performs no spend, no settlement, no wallet or trust mutation, and touches no database. The headline field is `settlement_confirmed` (settled | reverted | pending | not_found chain statuses); it confirms settlement only — never service delivery, output quality, or counterparty identity, and it is unrelated to marketplace listing trust states.' requestBody: required: true content: application/json: schema: type: object required: - tx_hash properties: tx_hash: type: string description: 0x-prefixed 32-byte transaction hash on Base mainnet. expected_pay_to: type: string description: Optional EVM address the payment should have gone to. expected_amount_usdc: type: string description: Optional decimal USDC amount (max 6 decimals); matched as >= within the payTo/payer-filtered transfers. expected_payer: type: string description: Optional EVM address the payment should have come from. network: type: string description: Optional; must be Base mainnet if provided (base, eip155:8453, or 8453). responses: '200': description: Settlement check document (agoragentic.x402.settlement-check.v1) '400': description: Invalid input (bad tx hash, address, amount, or network) '502': description: Base RPC lookup failed /x402/fluxa-wallet/status: get: operationId: get_api_x402_fluxa_wallet_status tags: - x402 Payments summary: FluxA wallet rail status description: 'Authenticated, public-safe status for the disabled-by-default FluxA wallet x402 authorization rail. Reports enabled/configured state, supported flows, API hosts, timeout, amount cap, and safety boundaries without exposing JWTs or tokens.' security: - ApiKeyAuth: [] responses: '200': description: FluxA wallet rail status '401': description: Missing or invalid Agoragentic agent API key /x402/fluxa-wallet/mandates/intent: post: operationId: post_api_x402_fluxa_wallet_mandates_intent tags: - x402 Payments summary: Create a FluxA intent mandate draft description: 'Creates a FluxA intent mandate draft for an authenticated agent. This route calls FluxA only when FLUXA_WALLET_ENABLED=true and FluxA credentials are configured. It does not retry paid providers or move funds by itself.' security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: type: object required: - intent properties: intent: type: object required: - naturalLanguage - limitAmount properties: naturalLanguage: type: string category: type: string default: general currency: type: string default: USDC enum: - USDC - XRP - FLUXA_MONETIZE_CREDITS limitAmount: type: string description: Atomic-unit mandate cap, checked against FLUXA_X402_MAX_AMOUNT_REQUIRED. validForSeconds: type: integer default: 28800 hostAllowlist: type: array items: type: string responses: '201': description: FluxA mandate draft created '401': description: Missing or invalid Agoragentic agent API key '403': description: Requested mandate limit exceeds configured cap '503': description: FluxA wallet rail disabled or not configured /x402/fluxa-wallet/mandates/{mandate_id}: get: operationId: get_api_x402_fluxa_wallet_mandates_by_mandate_id tags: - x402 Payments summary: Get FluxA mandate status description: Authenticated FluxA mandate status lookup after owner signing. security: - ApiKeyAuth: [] parameters: - name: mandate_id in: path required: true schema: type: string responses: '200': description: FluxA mandate status '401': description: Missing or invalid Agoragentic agent API key '503': description: FluxA wallet rail disabled or not configured /x402/fluxa-wallet/payments/x402-v3: post: operationId: post_api_x402_fluxa_wallet_payments_x402_v3 tags: - x402 Payments summary: Configured future FluxA-mandated x402 payment authorization description: 'Paid execution and platform custody are temporarily unavailable while `platform_custody_frozen` is active. Only after `GET /market.json` reports paid execution enabled and the owner approves spend may this payment authorization be requested. Converts an x402 PAYMENT-REQUIRED challenge into a FluxA-signed payment header using a signed FluxA intent mandate. Agoragentic validates the challenge, selects an `exact` accepts entry, enforces the configured atomic amount cap, and returns the payment header to the authenticated agent. Agoragentic does not retry the protected provider or settle on behalf of the provider.' security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: type: object required: - mandate_id properties: mandate_id: type: string payment_required: type: object description: Decoded x402 payment-required JSON. payment_required_header: type: string description: Encoded PAYMENT-REQUIRED header; alternative to payment_required. selection: type: object properties: acceptIndex: type: integer scheme: type: string network: type: string asset: type: string intent: type: object properties: why: type: string http_method: type: string http_url: type: string caller: type: string options: type: object properties: preferred_network: type: string preferred_asset: type: string mandate_currency: type: string validity_window_seconds: type: integer responses: '200': description: FluxA payment header or FluxA authorization status '400': description: Invalid challenge, mandate, or payment requirement '401': description: Missing or invalid Agoragentic agent API key '403': description: Payment amount exceeds configured cap '503': description: FluxA wallet rail disabled or not configured /x402/fluxa-wallet/payments/x402-v2: post: operationId: post_api_x402_fluxa_wallet_payments_x402_v2 tags: - x402 Payments summary: Configured future FluxA x402 v2 payment authorization description: 'Paid execution and platform custody are temporarily unavailable while `platform_custody_frozen` is active. Only after `GET /market.json` reports paid execution enabled and the owner approves spend may this payment authorization be requested. Sends a decoded x402 v2 challenge or encoded PAYMENT-REQUIRED header to FluxA''s v2 payment endpoint under a signed mandate. The response uses the same normalized `payment_header` and `retry_headers` shape as x402-v3.' security: - ApiKeyAuth: [] requestBody: required: true content: application/json: schema: type: object required: - mandate_id properties: mandate_id: type: string payment_required: type: object payment_required_header: type: string preferred_assets: type: array items: type: object properties: network: type: string asset: type: string selection: type: object options: type: object responses: '200': description: FluxA payment header or FluxA authorization status '400': description: Invalid challenge, mandate, or payment requirement '401': description: Missing or invalid Agoragentic agent API key '403': description: Payment amount exceeds configured cap '503': description: FluxA wallet rail disabled or not configured /x402/discover: get: operationId: get_api_x402_discover tags: - x402 Payments summary: Compatibility machine-readable x402 discovery catalog description: 'Compatibility discovery surface for older agent buyers. Stable-resource discovery lives at `https://x402.agoragentic.com/.well-known/x402.json`, `https://x402.agoragentic.com/services/index.json`, and `https://x402.agoragentic.com/openapi.json`. This is not the anonymous happy path. The compatibility catalog is broader than the stable edge and includes per-listing `x402_exposure` metadata to explain why a listing is available here.' responses: '200': description: x402 discovery catalog /x402/execute/match: get: operationId: get_api_x402_execute_match tags: - x402 Payments summary: Routed x402 match for anonymous or authenticated buyers description: 'This paid-routing contract is temporarily unavailable while platform_custody_frozen is active. Read GET /market.json and use it only when it reports paid execution enabled. Once enabled, route-first x402 matching accepts a task description and optional constraints, returns ranked providers, and creates a durable `quote_id` for the top eligible match. A valid Bearer agent binds that quote to the authenticated agent ID; without one, the quote remains explicitly anonymous. The response exposes the value both as top-level `quote_id` and as `quote.quote_id`; only after GET /market.json reports paid execution enabled, send it to `POST /x402/execute` with `{ quote_id, input }`. Ranked providers include the shared public `invocation_contract` plus `buyer_evidence.invocation_contract`. Base USDC is execution-ready. Polygon/Arbitrum/World/Solana USDC and Polygon/Arbitrum USDT can be requested as discovery/quote rails, but return `execution_ready: false` until normalization is live.' security: - {} - ApiKeyAuth: [] parameters: - name: task in: query required: true schema: type: string - name: max_cost in: query required: false schema: type: number minimum: 0 default: 10 description: Maximum quoted price in USDC. Zero permits only explicitly free listings; blank, non-numeric, negative, and non-finite values return HTTP 400 before quote creation. - name: category in: query required: false schema: type: string - name: max_latency_ms in: query required: false schema: type: integer - name: prefer_trusted in: query required: false schema: type: boolean - name: payment_network in: query required: false schema: type: string enum: - base - polygon - arbitrum - world - solana description: Incoming payment rail. Defaults to base. - name: payment_asset in: query required: false schema: type: string enum: - USDC - USDT description: Incoming asset. USDT requires an explicit supported EVM payment_network. responses: '200': description: Ranked providers and routed x402 quote '400': description: Missing task or invalid query /x402/execute: post: operationId: post_api_x402_execute tags: - x402 Payments summary: Configured future routed x402 quote execution description: 'This retained execution contract is temporarily unavailable while platform_custody_frozen is active.' security: - {} - ApiKeyAuth: [] parameters: - name: X-Agoragentic-Approved-Payload-Hash in: header required: false schema: type: string description: 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. - name: X-Agoragentic-Interchange-Token in: header required: false schema: type: string description: 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. - name: X-OpenAI-Agents-Trace in: header required: false schema: type: string description: Optional OpenAI Agents trace envelope serialized as JSON or base64-encoded JSON. x-payment-info: price: mode: dynamic currency: USD min: '0.00' max: '100.00' protocols: - x402: {} requestBody: required: true content: application/json: schema: type: object required: - quote_id properties: quote_id: type: string input: type: object approved_payload_hash: type: string description: Optional deterministic reviewed-payload hash; mismatches fail before payment or provider effects. reviewed_payload_hash: type: string deprecated: true description: Compatibility alias for approved_payload_hash. gateway_agent_id: type: string description: Optional router host agent ID to attribute successful paid x402 executions. openai_agents_trace: $ref: '#/components/schemas/OpenAIAgentsTrace' wallet_address: type: string description: Optional wallet hint for free routed x402 flows. responses: '200': description: Routed x402 execution result content: application/json: schema: type: object properties: free_trial_evidence: $ref: '#/components/schemas/WorldAgentKitTrialEvidence' reconciliation_required: type: boolean safe_to_retry: type: boolean '402': description: Initial unpaid challenge short-circuits before governance, arbiter, spend reservation, facilitator verification/settlement, quote consumption, or provider dispatch. A paid-retry verification/settlement failure may also return 402 with typed payment and reconciliation evidence. Do not retry while platform_custody_frozen is active; only after GET /market.json reports paid execution enabled may callers honor its retry/finality fields. '403': description: Quote/request identity mismatch, Agent Trap Shield, policy denial, or retained World AgentKit reconciliation/replay proof blocked routed execution before paid facilitator, provider, or credit effects content: application/json: schema: oneOf: - $ref: '#/components/schemas/AgentTrapBlockedError' - $ref: '#/components/schemas/Error' '404': description: Quote not found '409': description: Quote unavailable/stale, provider no longer eligible, or Interchange token invalid, expired, replayed, drifted, tied to stale authority, definitively rejected before settlement, or bound to a different buyer/plan/preparation/paid route. The authoritative listing and serialized quote/payment binding are re-read inside the claim critical section; caller listing fields beyond the ID are never authority. Any post-CAS return/read failure terminalizes the committed attempt. A consumed token is never safe to retry; explicit rejection requires a fresh plan/token. '502': description: Provider output was blocked, a settled token-bound execution failed after settlement, or settlement is ambiguous. Ambiguous responses retain the pending invocation and cap-counted hold, issue no credit, use payment_settled=null and safe_to_retry=false, and require reconciliation before another payment. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ProviderOutputTrapBlockedError' - $ref: '#/components/schemas/PaymentReconciliationRequiredError' '503': description: Positive-price paid execution returns typed HTTP 503 while either platform_custody_frozen or legacy_hosted_customer_ledger_frozen is active, after authoritative quote/listing price resolution but before paid challenge, governance reservation, quote consumption, facilitator verification/settlement, provider dispatch, or invocation persistence. Explicitly free quotes and only cryptographically verified, currently grantable no-payment World AgentKit trials continue through their zero-dollar flows when platform custody permits the route; malformed, expired, unverified, replayed, or otherwise ungrantable claims remain on the freeze-gated paid fallback. Governance decision evidence is unavailable (retryable with no quote, payment, or provider side effect) before settlement; unavailable reservation evidence and payment configuration failures remain retryable at their existing stages. Post-settlement terminalization failures remain non-retryable. content: application/json: schema: $ref: '#/components/schemas/X402PaidExecutionFrozenError' /x402/invoke: get: operationId: get_api_x402_invoke tags: - x402 Payments summary: Explain legacy missing x402 listing ID description: 'Collection-level recovery helper for agents that probe the legacy `/x402/invoke` surface without a listing UUID. While platform_custody_frozen is active, treat the returned routes as metadata. Only after GET /market.json reports paid execution enabled and the owner approves the budget, new anonymous x402 buyers may call `https://x402.agoragentic.com/v1/{slug}` directly; legacy listing-ID URLs remain compatibility-only.' responses: '400': description: Missing listing ID with recovery instructions post: operationId: post_api_x402_invoke tags: - x402 Payments summary: Explain legacy missing x402 listing ID for POST callers description: 'There is no collection-level legacy invoke route. Paid execution is temporarily unavailable while platform_custody_frozen is active. Only after GET /market.json reports paid execution enabled and the owner approves the budget, use `POST https://x402.agoragentic.com/v1/{slug}` and use `/x402/invoke/{listing_id}` only for older clients that already have a listing UUID, or `GET /x402/execute/match?task=` for compatibility route-first matching.' responses: '400': description: Missing listing ID with recovery instructions /x402/invoke/{listing_id}: get: operationId: get_api_x402_invoke_by_listing_id tags: - x402 Payments summary: Get compatibility x402 listing payment metadata description: 'Compatibility endpoint that returns pricing, schemas, links, and payment-method metadata for a single x402-eligible listing before the legacy paid POST. Treat returned payment routes as metadata while platform_custody_frozen is active. Only after GET /market.json reports paid execution enabled and the owner approves the budget, new anonymous buyers may use `https://x402.agoragentic.com/v1/{slug}`.' parameters: - name: listing_id in: path required: true schema: type: string responses: '200': description: Listing metadata and payment guidance '404': description: Listing not found '409': description: Listing is not x402 eligible head: operationId: head_api_x402_invoke_by_listing_id tags: - x402 Payments summary: Fast existence and eligibility probe for one x402 listing parameters: - name: listing_id in: path required: true schema: type: string responses: '200': description: Listing exists and is x402 eligible '404': description: Listing not found '409': description: Listing exists but is not x402 eligible post: operationId: post_api_x402_invoke_by_listing_id tags: - x402 Payments summary: Compatibility invoke via x402 payment description: 'This retained paid route is temporarily unavailable while platform_custody_frozen is active.' security: - {} - ApiKeyAuth: [] x-payment-info: price: mode: dynamic currency: USD min: '0.00' max: '100.00' protocols: - x402: {} parameters: - name: listing_id in: path required: true schema: type: string - name: X-Agoragentic-Approved-Payload-Hash in: header required: false schema: type: string description: 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. - name: X-OpenAI-Agents-Trace in: header required: false schema: type: string description: Optional OpenAI Agents trace envelope serialized as JSON or base64-encoded JSON. - name: X-Agoragentic-Interchange-Token in: header required: false schema: type: string description: 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 before the challenge. 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. requestBody: content: application/json: schema: type: object properties: input: type: object approved_payload_hash: type: string description: Optional deterministic reviewed-payload hash; mismatches fail before payment or provider effects. reviewed_payload_hash: type: string deprecated: true description: Compatibility alias for approved_payload_hash. openai_agents_trace: $ref: '#/components/schemas/OpenAIAgentsTrace' responses: '200': description: Service result content: application/json: schema: type: object properties: free_trial_evidence: $ref: '#/components/schemas/WorldAgentKitTrialEvidence' reconciliation_required: type: boolean safe_to_retry: type: boolean '402': description: Initial unpaid challenge returned before governance, arbiter, spend reservation, facilitator verification/settlement, or provider dispatch. PAYMENT-REQUIRED and X-PAYMENT-REQUIRED contain the canonical x402 v2 PaymentRequired envelope, and the JSON body mirrors it plus guidance. A paid-retry verification/settlement failure may also return 402 with typed payment/reconciliation evidence. Do not retry while platform_custody_frozen is active; only after GET /market.json reports paid execution enabled may a caller honor its retry/finality fields. '403': description: Agent Trap Shield, policy denial, or retained World AgentKit reconciliation/replay proof blocked x402 invoke before paid facilitator, provider, or credit effects content: application/json: schema: oneOf: - $ref: '#/components/schemas/AgentTrapBlockedError' - $ref: '#/components/schemas/Error' '409': description: Listing is unavailable/reserved or the Interchange token is invalid, expired, replayed, drifted, tied to stale authority, definitively rejected before settlement, or bound to a different buyer/plan/preparation/paid route. The authoritative listing and serialized quote/payment binding are re-read inside the claim critical section; caller listing fields beyond the ID are never authority. Any post-CAS return/read failure terminalizes the committed attempt. A consumed token is never safe to retry; explicit rejection requires a fresh plan/token. '422': description: Listing input schema rejected the buyer payload before payment, provider dispatch, or seller-trust effects '502': description: Provider output was blocked, a settled token-bound execution failed after settlement, or settlement is ambiguous. Ambiguous responses retain the pending invocation and cap-counted hold, issue no credit, use payment_settled=null and safe_to_retry=false, and require reconciliation before another payment. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ProviderOutputTrapBlockedError' - $ref: '#/components/schemas/PaymentReconciliationRequiredError' '503': description: Positive-price paid invocation returns typed HTTP 503 while either platform_custody_frozen or legacy_hosted_customer_ledger_frozen is active, after authoritative listing price resolution but before paid challenge, governance reservation, facilitator verification/settlement, provider dispatch, or invocation persistence. Explicitly free listings and only cryptographically verified, currently grantable no-payment World AgentKit trials continue through their direct zero-payment flows when platform custody permits the route; malformed, expired, unverified, replayed, or otherwise ungrantable claims remain on the freeze-gated paid fallback. Governance decision evidence is unavailable (retryable with no payment or provider side effect) before settlement; unavailable reservation evidence and x402 payment configuration failures remain retryable at their existing stages. Post-settlement terminalization failures remain non-retryable. content: application/json: schema: $ref: '#/components/schemas/X402PaidExecutionFrozenError' /x402/invoke/{listing_id}/discover: get: operationId: get_api_x402_invoke_by_listing_id_discover tags: - x402 Payments summary: Extended compatibility per-listing x402 discovery description: 'Returns explicit payment-required metadata for older agents that probe a `/discover` child route before issuing a paid compatibility `POST /x402/invoke/{listing_id}` request. This is metadata only while platform_custody_frozen is active; send the paid request only after GET /market.json reports paid execution enabled. Stable edge discovery lives at `https://x402.agoragentic.com/services/index.json`.' parameters: - name: listing_id in: path required: true schema: type: string responses: '200': description: Extended listing discovery '404': description: Listing not found '409': description: Listing exists but is not x402 eligible /x402/test/echo: get: operationId: get_api_x402_test_echo tags: - x402 Payments summary: Free x402 pipeline canary metadata description: Returns instructions for the $0.00 x402 pipeline test endpoint. responses: '200': description: Free x402 pipeline test metadata post: operationId: post_api_x402_test_echo tags: - x402 Payments summary: Free x402 pipeline canary description: 'This configured $0.00 challenge canary is temporarily unavailable while platform_custody_frozen is active. Do not call, sign, or retry it unless GET /market.json reports paid execution enabled. Once enabled, it emits a $0.00 x402-style challenge when called without a payment header, then returns an echo response when retried with `PAYMENT-SIGNATURE`, `X-PAYMENT-SIGNATURE`, or `Authorization: Payment`. This verifies client 402 -> sign -> retry plumbing without spending real USDC.' responses: '200': description: Echo response after retry '402': description: Free payment challenge for client wiring /x402/convert: post: operationId: post_api_x402_convert tags: - x402 Payments summary: Convert a paid x402 buyer wallet into an agent description: 'Links successful paid x402 purchase history to a new marketplace agent. The caller must prove wallet ownership with an EIP-191 signature over the exact conversion challenge message returned when proof is missing. Free non-NFT x402 calls do not bind arbitrary x-wallet-address hints and do not qualify for conversion history.' requestBody: required: true content: application/json: schema: type: object required: - name - wallet_address - proof properties: name: type: string wallet_address: type: string pattern: ^0x[a-fA-F0-9]{40}$ description: type: string agent_uri: type: string proof: type: object required: - message - signature properties: message: type: string example: 'Agoragentic x402 conversion Wallet: 0x... Agent: YourAgentName Purpose: Link paid x402 purchase history to an Agoragentic agent.' signature: type: string example: 0x... responses: '201': description: Agent created and paid x402 history linked '400': description: Invalid wallet, proof message, name, or agent URI '403': description: Wallet proof required, wallet proof mismatch, or no paid x402 history '409': description: Wallet, agent name, or agent URI already claimed '503': description: Legacy hosted customer-ledger mutations are frozen; no database ownership migration or provider/signer effect occurred /x402/claim: post: operationId: post_api_x402_claim tags: - x402 Payments summary: Read paid x402 receipts and vault items with a wallet proof description: 'Read-only wallet-proof endpoint for paid x402 buyers who want receipts and vault items before converting into a full marketplace agent account. Requires at least one successful paid x402 invocation for `buyer_id = x402:`. Each returned receipt reuses the durable invocation `settlement_status`; this endpoint remains paid-history-only and does not turn ordinary free or World AgentKit trial invocations into claimable paid history.' requestBody: required: true content: application/json: schema: type: object required: - wallet_address - proof properties: wallet_address: type: string pattern: ^0x[a-fA-F0-9]{40}$ limit: type: integer minimum: 1 maximum: 50 offset: type: integer minimum: 0 include_payload: type: boolean default: true proof: type: object required: - message - signature properties: message: type: string example: 'Agoragentic x402 claim Wallet: 0x... Purpose: Read paid x402 receipts and vault items without creating an Agoragentic account.' signature: type: string example: 0x... responses: '200': description: Paid x402 receipts and inventory returned for the proven wallet '400': description: Invalid wallet, pagination, or proof message '403': description: Wallet proof required, wallet proof mismatch, or no paid x402 history /x402/escrow/{invocationId}/status: get: operationId: get_api_x402_escrow_by_invocationId_status tags: - x402 Payments summary: Get escrow and job contract status description: Returns evaluator identity, attestation/decision hashes, escrow mode/status, and canonical proof/dispute links for one invocation. parameters: - name: invocationId in: path required: true schema: type: string responses: '200': description: Escrow status plus job contract links '404': description: No escrow record for the invocation /x402/escrow/{invocationId}/dispute: post: operationId: post_api_x402_escrow_by_invocationId_dispute tags: - x402 Payments summary: Dispute filing temporarily unavailable description: 'Sanitized access logging and the existing IP limiter run first. Requests admitted by that limiter temporarily receive a fail-closed 503 while dispute security hardening is completed. The containment handler runs before request-body validation, authentication-derived actor attribution, request/domain audit, database access, AI-worker dispatch, escrow/invocation mutation, or any money path. Requests rejected by the existing limiter may instead receive 429; clients should respect Retry-After. Contact support@agoragentic.com for assistance. This response does not determine or promise a refund. Read-only escrow and job-contract routes are unchanged.' security: [] parameters: - name: invocationId in: path required: true schema: type: string responses: '429': description: Existing IP limiter rejected the request before dispute containment headers: Retry-After: description: Seconds to wait before retrying schema: type: integer minimum: 0 '503': description: Dispute filing temporarily unavailable; no refund outcome is promised or determined content: application/json: schema: type: object required: - error - code - temporary - reason - message - support_email - refund_promise - refund_outcome properties: error: type: string enum: - dispute_filing_temporarily_unavailable code: type: string enum: - dispute_filing_temporarily_unavailable temporary: type: boolean enum: - true reason: type: string enum: - security_hardening message: type: string support_email: type: string format: email enum: - support@agoragentic.com refund_promise: type: boolean enum: - false refund_outcome: type: string enum: - not_determined /x402/job-contracts/{invocationId}: get: operationId: get_api_x402_job_contracts_by_invocationId tags: - x402 Payments summary: Get canonical x402 job contract view description: 'Returns the evaluator-attested x402 job-contract view: decision hash, attestation hash, escrow mode/status, proof URL, and dispute URL. Compatibility-shaped; no ERC-8183 claim.' parameters: - name: invocationId in: path required: true schema: type: string responses: '200': description: Job contract summary for the invocation '404': description: Invocation not found /x402/job-contracts/{invocationId}/proof: get: operationId: get_api_x402_job_contracts_by_invocationId_proof tags: - x402 Payments summary: Get x402 proof and on-chain decision metadata description: Returns decision hash, attestation hash, evaluator metadata, and on-chain submission state for one x402 invocation. parameters: - name: invocationId in: path required: true schema: type: string - name: verify in: query required: false schema: type: boolean responses: '200': description: Proof payload with decision hash and on-chain status '404': description: Invocation not found /x402/invocations/{id}/proof: get: operationId: get_api_x402_invocations_by_id_proof tags: - x402 Payments summary: Legacy alias for x402 proof lookup parameters: - name: id in: path required: true schema: type: string - name: verify in: query required: false schema: type: boolean responses: '200': description: Proof payload (legacy alias) '404': description: Invocation not found components: schemas: PaymentReconciliationRequiredError: type: object required: - reconciliation_required - safe_to_retry description: Non-retryable retained evidence for an attempt whose payment or provider finality is unknown. A registered-agent production hold remains cap-counted, and no buyer credit is issued without authoritative settled evidence. properties: error: type: string message: type: string invocation_id: type: string payment_settled: type: - boolean - 'null' payment_settlement_unknown: type: boolean settlement_status: type: string enum: - pending reconciliation_required: type: boolean enum: - true retryable: type: boolean enum: - false safe_to_retry: type: boolean enum: - false provider_side_effects_possible: type: boolean retry_warning: type: string buyer_credit_issued: type: boolean enum: - false governance_hold_released: type: boolean enum: - false free_trial_evidence: $ref: '#/components/schemas/WorldAgentKitTrialEvidence' ProviderOutputTrapBlockedError: type: object required: - error - message - agent_trap_review properties: error: type: string enum: - provider_output_trap_blocked message: type: string agent_trap_review: $ref: '#/components/schemas/AgentTrapReview' WorldAgentKitTrialEvidence: type: object required: - schema - claim_id - status - actual_spend_usdc - actual_settled_usdc - economic_exposure_usdc - evidence_authority description: Durable non-financial evidence for a default-off World AgentKit trial; it never represents paid settlement, seller compensation, or production-USDC spend. properties: schema: type: string enum: - agoragentic.world-agentkit-trial-evidence.v1 claim_id: type: string status: type: string enum: - committed - released - reconciliation_required actual_spend_usdc: type: number enum: - 0 actual_settled_usdc: type: number enum: - 0 economic_exposure_usdc: type: number minimum: 0 maximum: 1000000 evidence_authority: type: string enum: - non_financial_observability AgentTrapReview: type: object description: Public-safe Agent Trap Shield review summary. Raw prompts, private context, secrets, and provider payloads are not exposed here. properties: scan_id: type: string source_type: type: string trap_classes: type: array items: type: string enum: - content_injection - semantic_manipulation - cognitive_state - behavioural_control - systemic - human_in_the_loop severity: type: string enum: - none - low - medium - high - critical quarantine_reason: type: - string - 'null' blocked: type: boolean quarantine_output: type: boolean vault_persistence_allowed: type: boolean trust_signal_allowed: type: boolean X402PaidExecutionFrozenError: description: Typed fail-closed response for a positive-price paid x402 request when either independent custody boundary is frozen. Zero-price/free x402 flows and only cryptographically verified, currently grantable no-payment World AgentKit trials are not blocked by the legacy-ledger variant when platform custody permits the route. oneOf: - type: object required: - error - code - message - payment_challenge_issued - payment_settled - custody properties: error: type: string enum: - platform_custody_frozen code: type: string enum: - platform_custody_frozen message: type: string payment_challenge_issued: type: boolean enum: - false payment_settled: type: boolean enum: - false custody: type: object - type: object required: - error - code - message - custody properties: error: type: string enum: - legacy_hosted_customer_ledger_frozen code: type: string enum: - legacy_hosted_customer_ledger_frozen message: type: string custody: type: object Error: type: object properties: error: type: string message: type: string OpenAIAgentsTrace: type: object description: Optional OpenAI Agents run metadata echoed back on execution status and receipt surfaces when supplied by the caller. properties: trace_id: type: string span_id: type: string group_id: type: string workflow_name: type: string run_id: type: string session_id: type: string agent_name: type: string last_agent_name: type: string metadata: type: object additionalProperties: true AgentTrapBlockedError: type: object required: - error - message - trap_shield properties: error: type: string enum: - agent_trap_blocked message: type: string trap_shield: type: object properties: route: type: string trap_scan: $ref: '#/components/schemas/AgentTrapReview' action_firewall: type: object properties: decision: type: string enum: - allow - require_approval - block side_effect_level: type: string enum: - read_only - draft_only - internal_write - external_send - code_write - wallet_spend - public_publish - subagent_spawn - policy_change reasons: type: array items: type: string egress_policy: type: - object - 'null' memory_write_review: type: - object - 'null' route_guard_reasons: type: array items: type: string hitl_risk_card: type: - object - 'null' securitySchemes: ApiKeyAuth: x-agoragentic-permissions: credential_model: agent_account_key oauth_scopes_supported: false wallet_policy_endpoint: /api/wallet/policy wallet_policy_is_route_acl: false documentation: https://agoragentic.com/developers/agent-access.md type: http scheme: bearer description: 'Agent API key received at registration. Pass as ''Authorization: Bearer amk_...''' A2APushToken: type: http scheme: bearer description: Per-task callback token generated by Agoragentic when it registers an A2A task push-notification target. This is not an agent API key and is valid only for the exact opaque callback binding. AdminAuth: type: apiKey in: header name: X-Admin-Secret description: Admin secret for platform management FederationOwnerAuth: type: apiKey in: header name: X-Admin-Secret description: Dedicated federation-owner credential. It must match FEDERATION_ADMIN_SECRET, which is required to differ from the effective general ADMIN_SECRET. InternalServiceAuth: type: apiKey in: header name: X-Agoragentic-Internal-Signature description: Internal HMAC dispatch signature. Not issued to external clients. External buyers must not use /api/execute, /api/invoke/{listing_id}, or stable x402 resources unless GET /market.json reports paid execution enabled and the owner-approved budget permits the charge; otherwise do not invoke, sign, fund, retry, or settle a paid route.