{"openapi":"3.1.0","info":{"title":"XGuard Mainnet API","version":"0.5.1","description":"Guarded x402 v2 verification and settlement API for Base mainnet USDC."},"servers":[{"url":"https://www.xguardgate.com"}],"tags":[{"name":"Discovery"},{"name":"Merchant"},{"name":"Payments"}],"paths":{"/":{"get":{"tags":["Discovery"],"summary":"Describe XGuard","responses":{"200":{"description":"XGuard service metadata"}}}},"/.well-known/x402/facilitator.json":{"get":{"tags":["Discovery"],"summary":"Read the XGuard facilitator provider manifest","description":"XGuard-specific machine-readable provider metadata. This supplements, but does not replace, the standard x402 /supported response.","responses":{"200":{"description":"Provider manifest"}}}},"/provider.json":{"get":{"tags":["Discovery"],"summary":"Read the XGuard facilitator provider manifest alias","responses":{"200":{"description":"Provider manifest"}}}},"/healthz":{"get":{"tags":["Discovery"],"summary":"Liveness check","responses":{"200":{"description":"Worker is alive"}}}},"/readyz":{"get":{"tags":["Discovery"],"summary":"Readiness check","responses":{"200":{"description":"Mainnet route is ready"},"503":{"description":"Mainnet route is degraded or unavailable"}}}},"/supported":{"get":{"tags":["Discovery"],"summary":"List supported x402 kinds","responses":{"200":{"description":"Supported x402 capabilities"}}}},"/status":{"get":{"tags":["Discovery"],"summary":"Read operational status","responses":{"200":{"description":"Operational status and settlement counters"}}}},"/v1/register":{"post":{"tags":["Merchant"],"summary":"Register a merchant","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}}}}}},"responses":{"201":{"description":"Merchant registered and API key issued"}}}},"/v1/balance":{"get":{"tags":["Merchant"],"summary":"Read merchant service balance","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Merchant balance"},"401":{"description":"Missing or invalid merchant API key"}}}},"/v1/topups/intents":{"post":{"tags":["Merchant"],"summary":"Create a service-balance top-up intent","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amountUsd"],"properties":{"amountUsd":{"oneOf":[{"type":"string"},{"type":"number"}]}}}}}},"responses":{"201":{"description":"Top-up intent created"},"401":{"description":"Missing or invalid merchant API key"}}}},"/v1/topups/claim":{"post":{"tags":["Merchant"],"summary":"Claim a finalized Base USDC top-up","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["claimToken","transactionHash"],"properties":{"claimToken":{"type":"string"},"transactionHash":{"type":"string"}}}}}},"responses":{"200":{"description":"Top-up credited"},"401":{"description":"Missing or invalid merchant API key"}}}},"/verify":{"post":{"tags":["Payments"],"summary":"Verify an x402 v2 payment authorization","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"x402 v2 facilitator request containing paymentPayload and paymentRequirements as defined by the x402 specification.","additionalProperties":true}}}},"responses":{"200":{"description":"x402 verification result"},"400":{"description":"Malformed or unsupported payment request"},"401":{"description":"Missing or invalid merchant API key"},"503":{"description":"No healthy facilitator route is available"}}}},"/settle":{"post":{"tags":["Payments"],"summary":"Settle an x402 v2 payment","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"x402 v2 facilitator request containing paymentPayload and paymentRequirements as defined by the x402 specification.","additionalProperties":true}}}},"responses":{"200":{"description":"x402 settlement result"},"400":{"description":"Malformed or unsupported payment request"},"401":{"description":"Missing or invalid merchant API key"},"402":{"description":"Merchant service balance is insufficient"},"409":{"description":"Duplicate, conflicting, or in-progress settlement"},"503":{"description":"Settlement outcome is ambiguous or route unavailable"}}}},"/discovery/resources":{"get":{"summary":"List x402 Bazaar resources cataloged by XGuard","responses":{"200":{"description":"Discovery catalog"}}}},"/discovery/search":{"get":{"summary":"Search XGuard's x402 Bazaar catalog","parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Matching resources"}}}},"/.well-known/xguard/migrate":{"get":{"summary":"Generate a side-effect-free XGuard facilitator switch kit","description":"Returns merchant-controlled migration instructions only. It does not register, fund, mutate third-party configuration, create synthetic payments, or execute verify/settle calls.","parameters":[{"name":"from","in":"query","schema":{"type":"string"}},{"name":"name","in":"query","schema":{"type":"string"}},{"name":"resource","in":"query","schema":{"type":"string","format":"uri"}}],"responses":{"200":{"description":"Safe migration kit"}}}},"/v1/settlements/{logicalPaymentKey}/truth":{"get":{"summary":"Read XGuard's independent settlement truth","description":"Merchant-authenticated lookup of finalized Base settlement and EIP-3009 recovery evidence. FINALIZED is the only release-safe state.","security":[{"bearerAuth":[]}],"parameters":[{"name":"logicalPaymentKey","in":"path","required":true,"description":"Immutable XGuard logical payment identity","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Terminal settlement truth or fail-closed conflicting evidence"},"202":{"description":"Independent evidence remains pending"},"401":{"description":"Merchant authentication required"},"404":{"description":"Settlement truth record not found"}}}},"/v1/settlements/{logicalPaymentKey}/resolve":{"post":{"summary":"Resolve an ambiguous x402 settlement now","description":"Triggers immediate finalized Base and EIP-3009 recovery checks without blindly resubmitting the payment authorization.","security":[{"bearerAuth":[]}],"parameters":[{"name":"logicalPaymentKey","in":"path","required":true,"description":"Immutable XGuard logical payment identity","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Resolution reached a terminal truth state"},"202":{"description":"Sufficient final evidence is not yet available"},"401":{"description":"Merchant authentication required"},"404":{"description":"Settlement truth record not found"}}}},"/mcp":{"post":{"summary":"XGuard Streamable HTTP MCP endpoint","description":"Supports MCP 2026-07-28 stateless requests and backward-compatible 2025-era requests.","responses":{"200":{"description":"MCP JSON-RPC response"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Merchant API key returned once by POST /v1/register."}}}}