{"openapi":"3.1.0","info":{"title":"Relay API","version":"0.1.0","summary":"Verified agent commerce infrastructure for Stellar x402 services.","description":"Relay adds discovery, active verification, policy-aware routing, and publicly verifiable receipts on top of standard Stellar x402 payments. Facilitator endpoints are wire-compatible x402 and add no proprietary fields.","license":{"name":"Apache-2.0","identifier":"Apache-2.0"}},"servers":[{"url":"https://api.relayx402.xyz","description":"Relay (stellar:testnet)"}],"tags":[{"name":"Health","description":"Liveness, readiness, and dependency status."},{"name":"Facilitator","description":"Wire-compatible x402 verify/settle proxying."},{"name":"Discovery","description":"Catalog of machine-payable resources."},{"name":"Verification","description":"Probe evidence, metrics, and observations."},{"name":"Routing","description":"Policy-aware provider selection."},{"name":"Receipts","description":"Signed, independently verifiable purchase records."}],"paths":{"/health/live":{"get":{"tags":["Health"],"operationId":"getHealthLive","summary":"Check liveness","responses":{"200":{"description":"The process is alive.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"},"examples":{"ok":{"value":{"status":"ok"}}}}}}}}},"/health/ready":{"get":{"tags":["Health"],"operationId":"getHealthReady","summary":"Check readiness","description":"Reports the configured network and the USDC asset Relay settles in.","responses":{"200":{"description":"Relay is ready to serve traffic.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadyResponse"}}}}}}},"/health/dependencies":{"get":{"tags":["Health"],"operationId":"getHealthDependencies","summary":"Inspect backing services","description":"Shows whether the store is durable and which facilitator backends are currently healthy.","responses":{"200":{"description":"Dependency status.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/x402/supported":{"get":{"tags":["Facilitator"],"operationId":"getSupportedPaymentKinds","summary":"List supported payment kinds","description":"Merged capabilities across every configured facilitator, de-duplicated by network and scheme.","responses":{"200":{"description":"Supported x402 payment kinds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportedResponse"}}}}}}},"/x402/verify":{"post":{"tags":["Facilitator"],"operationId":"verifyPayment","summary":"Verify a payment payload","description":"Verifies without settling. Routed to a facilitator advertising the kind.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Facilitator verification result."},"422":{"description":"No configured facilitator supports the requested network and scheme.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Every eligible facilitator failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/x402/settle":{"post":{"tags":["Facilitator"],"operationId":"settlePayment","summary":"Settle a verified payment","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Settlement result."},"422":{"description":"Unsupported payment kind."},"502":{"description":"Every eligible facilitator failed."}}}},"/x402/facilitators":{"get":{"tags":["Facilitator"],"operationId":"listFacilitators","summary":"Inspect facilitator health","responses":{"200":{"description":"Per-backend health and capability counts."}}}},"/v1/resources":{"get":{"tags":["Discovery"],"operationId":"listResources","summary":"List catalogued resources","responses":{"200":{"description":"Every known resource record.","content":{"application/json":{"schema":{"type":"object","properties":{"resources":{"type":"array","items":{"$ref":"#/components/schemas/ResourceRecord"}}}}}}}}}},"/v1/resources/{id}":{"get":{"tags":["Discovery"],"operationId":"getResource","summary":"Resolve one resource","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"svc_atlas_inspect"}],"responses":{"200":{"description":"The resource record and its current metrics."},"404":{"description":"No such resource."}}}},"/v1/search":{"post":{"tags":["Discovery"],"operationId":"searchResources","summary":"Search resources","description":"Price filters compare against worst-case spend, so an `upto` ceiling cannot slip past a buyer's limit.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResourceSearchRequest"},"examples":{"byCapability":{"value":{"capability":"rwa.asset.inspect","network":"stellar:testnet","asset":"USDC","maxPriceUsd":0.005}}}}}},"responses":{"200":{"description":"Matching resource records."}}}},"/v1/validate":{"post":{"tags":["Verification"],"operationId":"validateEndpoint","summary":"Probe an endpoint","description":"Issues a live probe and records the observation. A healthy result requires a 402 carrying a decodable x402 challenge.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"resourceId":{"type":"string"},"url":{"type":"string","format":"uri"},"method":{"type":"string"}}}}}},"responses":{"200":{"description":"Probe result."}}}},"/v1/resources/{id}/metrics":{"get":{"tags":["Verification"],"operationId":"getResourceMetrics","summary":"Get resource metrics","description":"Every field is computed from recorded observations. A resource with no evidence reports zero confidence rather than a placeholder.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"svc_atlas_inspect"}],"responses":{"200":{"description":"Reliability, confidence, latency, and price consistency.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResourceMetrics"}}}},"404":{"description":"No metrics for this resource."}}}},"/v1/resources/{id}/observations":{"get":{"tags":["Verification"],"operationId":"listObservations","summary":"List raw probe observations","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"svc_atlas_inspect"}],"responses":{"200":{"description":"The evidence behind the metrics."}}}},"/v1/routes":{"post":{"tags":["Routing"],"operationId":"routeResource","summary":"Route by policy","description":"Returns the selected provider, ranked fallbacks, and a reason code for every rejection.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouteRequest"}}}},"responses":{"200":{"description":"Routing decision with explanation."}}}},"/v1/policies/evaluate":{"post":{"tags":["Routing"],"operationId":"evaluatePolicy","summary":"Dry-run a policy against one resource","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"ALLOW, DENY, or INSUFFICIENT_DATA with reasons."},"404":{"description":"No such resource."}}}},"/v1/receipts":{"post":{"tags":["Receipts"],"operationId":"createReceipt","summary":"Create a commerce receipt","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"A signed receipt.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommerceReceipt"}}}},"422":{"description":"No eligible provider for the requested route."}}}},"/v1/receipts/signer":{"get":{"tags":["Receipts"],"operationId":"getReceiptSigner","summary":"Get the receipt signing key","description":"Returns the Ed25519 public key receipts are signed with, so third parties can verify without contacting Relay.","responses":{"200":{"description":"Signer disclosure."}}}},"/v1/receipts/{id}":{"get":{"tags":["Receipts"],"operationId":"getReceipt","summary":"Fetch a receipt","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"rcpt_2d146c5673e517e427204e87"}],"responses":{"200":{"description":"The stored receipt."},"404":{"description":"No such receipt."}}}},"/v1/receipts/{id}/verify":{"get":{"tags":["Receipts"],"operationId":"verifyReceipt","summary":"Verify a receipt signature","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"rcpt_2d146c5673e517e427204e87"}],"responses":{"200":{"description":"Verification outcome.","content":{"application/json":{"schema":{"type":"object","properties":{"receiptId":{"type":"string"},"valid":{"type":"boolean"},"algorithm":{"type":"string","enum":["ed25519","hmac-sha256","unknown"]},"signer":{"type":["string","null"]},"reason":{"type":"string"}}}}}},"404":{"description":"No such receipt."}}}}},"components":{"schemas":{"HealthResponse":{"type":"object","required":["status"],"properties":{"status":{"type":"string","examples":["ok"]}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"ReadyResponse":{"type":"object","properties":{"status":{"type":"string"},"network":{"$ref":"#/components/schemas/StellarNetwork"},"asset":{"$ref":"#/components/schemas/SupportedAsset"}}},"StellarNetwork":{"type":"string","enum":["stellar:testnet","stellar:pubnet"]},"PaymentScheme":{"type":"string","enum":["exact","upto"],"description":"`exact` settles a fixed price. `upto` authorizes a ceiling and settles actual usage."},"SupportedAsset":{"type":"object","properties":{"network":{"$ref":"#/components/schemas/StellarNetwork"},"assetContract":{"type":"string"},"symbol":{"type":"string"},"decimals":{"type":"integer","description":"Stellar classic assets wrapped as a SAC keep 7-decimal precision, not the 6 used on EVM chains.","examples":[7]},"minimumAmount":{"type":"string"},"maximumAmount":{"type":"string"}}},"SupportedResponse":{"type":"object","properties":{"kinds":{"type":"array","items":{"type":"object","properties":{"x402Version":{"type":"integer"},"scheme":{"$ref":"#/components/schemas/PaymentScheme"},"network":{"$ref":"#/components/schemas/StellarNetwork"},"extra":{"type":"object"}}}},"extensions":{"type":"array","items":{"type":"string"}},"signers":{"type":"object"}}},"ResourcePaymentOption":{"type":"object","properties":{"network":{"$ref":"#/components/schemas/StellarNetwork"},"scheme":{"$ref":"#/components/schemas/PaymentScheme"},"asset":{"type":"string"},"amount":{"type":"string"},"amountUsd":{"type":"number"},"maxAmount":{"type":"string","description":"For `upto`, the ceiling the buyer authorizes."},"maxAmountUsd":{"type":"number"},"payTo":{"type":"string"}}},"ResourceRecord":{"type":"object","properties":{"resource":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["http","mcp"]},"name":{"type":"string"},"description":{"type":"string"},"url":{"type":"string","format":"uri"},"capabilities":{"type":"array","items":{"type":"string"}},"status":{"$ref":"#/components/schemas/ServiceStatus"},"verificationLevel":{"type":"integer","minimum":0,"maximum":4}}},"provider":{"type":"object"},"paymentOptions":{"type":"array","items":{"$ref":"#/components/schemas/ResourcePaymentOption"}}}},"ServiceStatus":{"type":"string","enum":["DISCOVERED","VALIDATING","LIVE","PAYMENT_VERIFIED","TRANSACTION_VERIFIED","CONTINUOUSLY_VERIFIED","DEGRADED","OFFLINE","QUARANTINED"]},"ResourceSearchRequest":{"type":"object","properties":{"query":{"type":"string"},"capability":{"type":"string"},"scheme":{"$ref":"#/components/schemas/PaymentScheme"},"network":{"$ref":"#/components/schemas/StellarNetwork"},"asset":{"type":"string"},"maxPriceUsd":{"type":"number"},"minimumReliability":{"type":"number"},"maximumP95LatencyMs":{"type":"number"}}},"ResourceMetrics":{"type":"object","properties":{"resourceId":{"type":"string"},"availability24h":{"type":"number"},"paymentInterfaceSuccessRate":{"type":"number"},"p50LatencyMs":{"type":["integer","null"]},"p95LatencyMs":{"type":["integer","null"]},"observedPriceUsd":{"type":["number","null"]},"priceConsistency":{"type":"number"},"reliability":{"type":"number"},"confidence":{"type":"number","description":"Scales with sample size and freshness. Zero means Relay has no current evidence."},"observationCount":{"type":"integer"},"lastVerified":{"type":["string","null"],"format":"date-time"}}},"AgentPolicy":{"type":"object","properties":{"networks":{"type":"array","items":{"$ref":"#/components/schemas/StellarNetwork"}},"assets":{"type":"array","items":{"type":"string"}},"schemes":{"type":"array","items":{"$ref":"#/components/schemas/PaymentScheme"}},"maxPricePerRequestUsd":{"type":"number","description":"Compared against worst-case spend, including any `upto` ceiling."},"minProviderReliability":{"type":"number"},"minConfidence":{"type":"number"},"requireTransactionVerified":{"type":"boolean"},"denyProviders":{"type":"array","items":{"type":"string"}}}},"RouteRequest":{"type":"object","required":["capability"],"properties":{"capability":{"type":"string"},"constraints":{"$ref":"#/components/schemas/AgentPolicy"},"optimizeFor":{"type":"string","enum":["balanced","cheapest","fastest","reliable"]}}},"CommerceReceipt":{"type":"object","properties":{"receiptId":{"type":"string"},"request":{"type":"object"},"routing":{"type":"object"},"service":{"type":"object"},"payment":{"type":"object","properties":{"protocol":{"type":"string","enum":["x402"]},"network":{"$ref":"#/components/schemas/StellarNetwork"},"scheme":{"$ref":"#/components/schemas/PaymentScheme"},"asset":{"type":"string"},"amount":{"type":"string"},"maxAmount":{"type":"string"},"transactionHash":{"type":["string","null"]}}},"response":{"type":"object"},"timestamp":{"type":"string","format":"date-time"},"relaySignature":{"type":"string"},"relaySigner":{"type":"string","description":"Stellar public key that signed this receipt."},"signatureAlgorithm":{"type":"string","enum":["ed25519","hmac-sha256"]}}}}}}