{"openapi":"3.1.0","info":{"title":"x402Rail API","version":"0.2.0","description":"Correctness-critical services for autonomous AI agents, billed per-request\nover the x402 machine-payment protocol (USDC on Base).\n\n## Paying for a call (x402)\nPaid endpoints are gated by HTTP 402. The flow is:\n1. Call the endpoint with no payment. The server replies `402 Payment\n   Required` with a machine-readable `accepts` array of PaymentRequirements.\n2. Construct and sign an x402 payment for one of the offered requirements.\n3. Retry the same request with the signed payload in the `X-PAYMENT` header.\n4. On success you receive `200` with the result and an `X-PAYMENT-RESPONSE`\n   header containing the settlement receipt.\n\n## Discovery (deterministic, no pre-flight crawl)\nDiscovery never depends on parsing one versioned sub-resource. The policy,\nmanifest, catalog, and spec are advertised in three standard places:\n\n1. **Root manifest** — `GET /.well-known/x402` is the single,\n   unauthenticated entry point. A first-contact agent reads the whole\n   platform schema (network, chain, asset, payee, facilitator) and the\n   discovery endpoints here before sending any traffic.\n2. **Inline in the 402 envelope** — every `402 Payment Required` body\n   carries `policyUrl` and a `discovery` block, so an agent learns the\n   terms at the exact moment it hits the paywall (the \"hot path\").\n3. **Response headers** — every response carries `Link`\n   (`rel=\"payment-policy\"`, `rel=\"x402-manifest\"`, `rel=\"x402-catalog\"`,\n   `rel=\"service-desc\"`) and `X-X402-Policy`, so an agent can sniff terms\n   with a lightweight `HEAD /` without parsing any JSON.\n\nFree endpoints (`/.well-known/x402`, `/v1/health`, `/v1/catalog`,\n`/v1/policy`, `/openapi.json`) require no payment and are intended for\ndiscovery and uptime probing.\n","contact":{"name":"x402Rail","email":"brian-x402@outlook.com"},"license":{"name":"Proprietary"},"x-guidance":"Start at GET /.well-known/x402 for platform schema and discovery URLs. Paid routes\nreturn HTTP 402 with x402 v2 Payment-Required metadata and Bazaar input/output\nschemas. State Hub ops are prepaid-credit (deposit once via POST /v1/state/deposit);\nthey are identity-gated bearer routes, not per-request x402.\n"},"servers":[{"url":"https://x402rail.net","description":"Production"},{"url":"https://dev.x402rail.net","description":"Dev staging"},{"url":"http://localhost:3000","description":"Local development"}],"tags":[{"name":"discovery","description":"Free endpoints for catalog, health, and spec discovery."},{"name":"reputation","description":"Paid reputation/verification scores for other x402 services."},{"name":"transform","description":"Paid Claude-backed text computation."},{"name":"data","description":"Paid niche data feeds."},{"name":"state","description":"Prepaid Agent State Hub (deposit once, spend in-DB)."}],"paths":{"/.well-known/x402":{"get":{"tags":["discovery"],"summary":"Root platform manifest (x402 well-known)","description":"Free, unauthenticated root manifest at the standardized `/.well-known/`\npath. A first-contact agent fetches this once to ingest the entire\nplatform schema — x402 version, network/chain, USDC asset, receive-only\n`payTo`, facilitator — and the absolute discovery endpoints (policy,\ncatalog, OpenAPI, health) before initiating any traffic.\n","operationId":"getWellKnownX402","security":[],"responses":{"200":{"description":"Platform manifest.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"Link":{"$ref":"#/components/headers/DiscoveryLink"},"X-X402-Policy":{"$ref":"#/components/headers/XX402Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WellKnownManifest"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/openapi.json":{"get":{"tags":["discovery"],"summary":"OpenAPI specification (JSON)","operationId":"getOpenApi","security":[],"responses":{"200":{"description":"The OpenAPI document for this API.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v2/x402/discovery/mcp":{"get":{"tags":["discovery"],"summary":"MCP discovery server descriptor","description":"Native Model Context Protocol (MCP) endpoint. A plain `GET` returns a\ndescriptor (transport, protocol version, available tools). Agents on\nMCP-native frameworks `POST` JSON-RPC 2.0 messages here.\n","operationId":"getMcpDescriptor","security":[],"responses":{"200":{"description":"MCP server descriptor.","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["discovery"],"summary":"MCP JSON-RPC endpoint (Streamable HTTP)","description":"Handles MCP JSON-RPC 2.0 messages: `initialize`, `tools/list`, and\n`tools/call`. Two tools are exposed:\n\n  - **search_resources** — rank the x402 catalog by intent; returns\n    price, input schema, output example, and absolute resource URL.\n  - **proxy_tool_call** — invoke a resource. Relays the agent's\n    `X-PAYMENT` header when present; otherwise returns the `402`\n    envelope so payment can be negotiated. This server holds no signing\n    key and never pays on the agent's behalf.\n","operationId":"postMcp","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"A JSON-RPC 2.0 request object (or a batch array)."}}}},"responses":{"200":{"description":"JSON-RPC 2.0 response (or batch).","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"description":"Accepted (notification with no response body)."},"400":{"description":"Parse error (malformed JSON).","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/health":{"get":{"tags":["discovery"],"summary":"Full health report (JSON)","description":"Returns configuration checks, dependency probes (Postgres, x402\nfacilitator), and runtime metrics. Responds with `503` when status is\n`unhealthy`. Send `Accept: text/html` for the operator dashboard, or\nuse `/v1/health/ui` directly.\n","operationId":"getHealth","security":[],"responses":{"200":{"description":"Service is healthy or degraded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthReport"}},"text/html":{"schema":{"type":"string"}}}},"503":{"description":"One or more critical checks failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthReport"}}}}}}},"/v1/health/ui":{"get":{"tags":["discovery"],"summary":"Operator health dashboard (HTML)","operationId":"getHealthUi","security":[],"responses":{"200":{"description":"Auto-refreshing HTML diagnostics page.","content":{"text/html":{"schema":{"type":"string"}}}},"503":{"description":"One or more critical checks failed."}}}},"/v1/health/simple":{"get":{"tags":["discovery"],"summary":"Minimal liveness probe","description":"Lightweight ping for uptime probers and load balancers. Always returns\n`200` when the process is running; does not probe dependencies.\n","operationId":"getHealthSimple","security":[],"responses":{"200":{"description":"Process is alive.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthSimple"}}}}}}},"/v1/catalog":{"get":{"tags":["discovery"],"summary":"Machine-readable product + price list","description":"Lists every billable endpoint with its current price, so agents and\nmarketplace crawlers can discover offerings without paying.\n","operationId":"getCatalog","security":[],"responses":{"200":{"description":"Current catalog.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CatalogItem"}},"policyUrl":{"type":"string","description":"Absolute URL of the free data acceptance policy (GET /v1/policy).","example":"https://x402rail.net/v1/policy"},"discovery":{"$ref":"#/components/schemas/DiscoveryLinks"}},"required":["items"]}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/policy":{"get":{"tags":["discovery"],"summary":"Data acceptance policy (what we accept vs. reject)","description":"Free, machine-readable description of what content the service accepts\nand what it rejects, plus size/TTL/quota limits and the error codes a\nrejection returns. Fetch this **before** a billed `POST /v1/state/save`\nor `POST /v1/extract` to pre-screen a payload locally and avoid paying\nfor a call that would be rejected.\n\nScreening classes:\n  - **opaque** (embedded media, high-entropy blobs) — always rejected;\n    store a URL or hash instead.\n  - **secret_or_pii** (private keys, JWTs, AWS keys, card numbers, SSNs)\n    — rejected by default, or masked when the deployment runs the\n    `redact` policy.\n  - **soft_identifier** (email, phone) — allowed (recorded only) by\n    default, or masked under the `redact` policy.\n","operationId":"getDataPolicy","security":[],"responses":{"200":{"description":"Current data acceptance policy.","headers":{"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataPolicy"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/score/{serviceId}":{"get":{"tags":["reputation"],"summary":"Current reliability score for an x402 service","operationId":"getServiceScore","security":[],"x-payment-info":{"protocols":[{"x402":{}}],"price":{"mode":"fixed","currency":"USD","amount":"0.01"}},"parameters":[{"$ref":"#/components/parameters/ServiceId"}],"responses":{"200":{"description":"The latest score plus component breakdown and evidence.","headers":{"X-PAYMENT-RESPONSE":{"$ref":"#/components/headers/XPaymentResponse"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceScore"}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/DuplicatePayment"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/score/{serviceId}/history":{"get":{"tags":["reputation"],"summary":"Historical score time series","operationId":"getServiceScoreHistory","security":[],"x-payment-info":{"protocols":[{"x402":{}}],"price":{"mode":"fixed","currency":"USD","amount":"0.02"}},"parameters":[{"$ref":"#/components/parameters/ServiceId"},{"name":"limit","in":"query","description":"Maximum number of history points to return, newest first.","schema":{"type":"integer","minimum":1,"maximum":1000,"default":100},"example":100}],"responses":{"200":{"description":"Score history (most recent first).","headers":{"X-PAYMENT-RESPONSE":{"$ref":"#/components/headers/XPaymentResponse"}},"content":{"application/json":{"schema":{"type":"object","properties":{"serviceId":{"type":"string"},"points":{"type":"array","items":{"$ref":"#/components/schemas/ScorePoint"}}},"required":["serviceId","points"]}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/DuplicatePayment"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/extract":{"post":{"tags":["transform"],"summary":"Schema-guided extraction from an arbitrary payload (Claude-backed)","description":"Returns structured data extracted from `content` according to the\nrequested `schema`. A per-call cost guard guarantees the price exceeds\nthe model token cost; if a request would breach the margin floor it is\nrejected with `422 cost_guard_exceeded` rather than run at a loss.\n\n**Accepted input:** `content` is text/markdown/HTML up to the published\ncharacter cap (see `GET /v1/policy` → `limits.extract.maxContentChars`).\nOversized input is rejected with `413` **before** settlement, so an\ninvalid call is never billed.\n\n**No plaintext PII/secrets:** `content` and `instructions` are sent to a\nthird-party model, so they are screened first. Any detected PII or secret\n— private keys, JWTs, AWS keys, card numbers, SSNs, emails, phone numbers,\nor opaque/high-entropy blobs — is rejected with `422 screening_rejected`\n**before** settlement and is never transmitted off-platform. Redact or\nremove sensitive data before calling.\n","operationId":"postExtract","security":[],"x-payment-info":{"protocols":[{"x402":{}}],"price":{"mode":"fixed","currency":"USD","amount":"0.05"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractRequest"}}}},"responses":{"200":{"description":"Extraction result.","headers":{"X-PAYMENT-RESPONSE":{"$ref":"#/components/headers/XPaymentResponse"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractResult"}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"409":{"$ref":"#/components/responses/DuplicatePayment"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"description":"Validation error, cost guard exceeded, or `screening_rejected` when\n`content`/`instructions` contain plaintext PII or secrets.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/data/{feed}":{"get":{"tags":["data"],"summary":"Fetch a niche data feed","operationId":"getDataFeed","security":[],"x-payment-info":{"protocols":[{"x402":{}}],"price":{"mode":"fixed","currency":"USD","amount":"0.005"}},"parameters":[{"name":"feed","in":"path","required":true,"schema":{"type":"string","enum":["x402-directory"]},"example":"x402-directory","description":"Feed identifier. Supported: `x402-directory` — an owned, continuously\nprobed directory of known x402 services with live reliability scores.\nSee /v1/catalog for the current feed list.\n"}],"responses":{"200":{"description":"Feed payload.","headers":{"X-PAYMENT-RESPONSE":{"$ref":"#/components/headers/XPaymentResponse"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataFeedResponse"}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/DuplicatePayment"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/redact":{"post":{"tags":["services"],"summary":"Redact PII/secrets with a signed attestation","description":"Redacts PII and secrets from caller content and returns the redacted\noutput plus an off-chain Ed25519-signed attestation that binds input to\noutput (verifiable at `/v1/attest/{id}`). Choose `redactionMode`:\n`remove` (default `[REDACTED]`), `mask` (format-preserving partial\nmasking), or `pseudonymize` (stable keyed HMAC tokens). No content is\nforwarded to any model; redaction is local. Input is screened/size-capped\nbefore settle.\n","operationId":"postRedact","security":[],"x-payment-info":{"protocols":[{"x402":{}}],"price":{"mode":"fixed","currency":"USD","amount":"0.02"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","description":"Text to redact.","example":"Contact a@b.com or call 415-555-0100."},"redactionMode":{"type":"string","enum":["remove","mask","pseudonymize"],"default":"remove","description":"How to replace detected spans: `remove` → `[REDACTED]`;\n`mask` → format-preserving partial masking;\n`pseudonymize` → stable keyed tokens (`pii_<16 hex>`).\n"}},"required":["content"]}}}},"responses":{"200":{"description":"Redacted content plus a signed attestation.","headers":{"X-PAYMENT-RESPONSE":{"$ref":"#/components/headers/XPaymentResponse"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedactResult"}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"409":{"$ref":"#/components/responses/DuplicatePayment"},"413":{"description":"Content exceeds the published size cap."},"422":{"description":"Validation error (content must be a string)."},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/attest/{id}":{"get":{"tags":["services"],"summary":"Fetch + verify a redaction attestation","description":"Returns a previously issued redaction attestation (public key, signature,\ncontent hash, detector version) plus a server-side `verified` flag, so any\nparty can independently verify a `/v1/redact` result. Free.\n","operationId":"getAttestation","security":[],"parameters":[{"name":"id","in":"path","required":true,"description":"Attestation id returned by POST /v1/redact.","schema":{"type":"string"},"example":"8f14e45f-ceea-4e2a-9b1a-3c2e6f0a1b2c"}],"responses":{"200":{"description":"The signed attestation and verification result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttestationResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/attest/pubkey":{"get":{"tags":["services"],"summary":"Fetch the attestation signing public key","description":"Returns the current Ed25519 public key (SPKI PEM) used to sign\n`/v1/redact` attestations, so anyone can verify a redaction proof offline\nwithout first holding an attestation id. Free.\n","operationId":"getAttestPubkey","security":[],"responses":{"200":{"description":"The current attestation signing public key.","content":{"application/json":{"schema":{"type":"object","properties":{"algorithm":{"type":"string","enum":["ed25519"]},"publicKey":{"type":"string","description":"SPKI PEM public key."},"detectorVersion":{"type":"string","example":"redact-v1"}},"required":["algorithm","publicKey"]}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/preflight":{"get":{"tags":["services"],"summary":"Vet an external x402 service before paying it","description":"Rolls three checks into one paid call: the target's `/.well-known/x402`\nmanifest, a live health probe (reachability + latency), and our own\nappend-only reliability score for that host (if probed). Owned,\naggregated judgement — not a thin proxy. The `url` is SSRF-checked and\nprivate/loopback addresses are rejected before settlement.\n","operationId":"getPreflight","security":[],"x-payment-info":{"protocols":[{"x402":{}}],"price":{"mode":"fixed","currency":"USD","amount":"0.01"}},"parameters":[{"name":"url","in":"query","required":true,"description":"Absolute http(s) URL of the x402 service (or endpoint) to vet.","schema":{"type":"string","format":"uri"},"example":"https://api.example.com/v1/quote"}],"responses":{"200":{"description":"The aggregated preflight assessment.","headers":{"X-PAYMENT-RESPONSE":{"$ref":"#/components/headers/XPaymentResponse"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreflightResult"}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"409":{"$ref":"#/components/responses/DuplicatePayment"},"422":{"description":"Missing/invalid `url`, or a private/loopback address."},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/validate":{"post":{"tags":["services"],"summary":"Validate JSON against a JSON Schema","description":"Returns a definitive valid/invalid verdict for a JSON `value` against a\ncaller-supplied JSON `schema`, with precise, JSON-Pointer-addressed\nerrors. Pure CPU; no model. Invalid schemas and oversized inputs are\nrejected before settlement.\n","operationId":"postValidate","security":[],"x-payment-info":{"protocols":[{"x402":{}}],"price":{"mode":"fixed","currency":"USD","amount":"0.005"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"schema":{"type":"object","description":"The JSON Schema to validate against (draft 2020-12 / draft-07 compatible).","additionalProperties":true},"value":{"description":"The JSON value to validate (any JSON type)."}},"required":["schema","value"]}}}},"responses":{"200":{"description":"The validation verdict.","headers":{"X-PAYMENT-RESPONSE":{"$ref":"#/components/headers/XPaymentResponse"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"409":{"$ref":"#/components/responses/DuplicatePayment"},"413":{"description":"Schema or value exceeds the published size cap."},"422":{"description":"Body invalid, or the JSON Schema failed to compile."},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/state/deposit":{"post":{"tags":["state"],"summary":"Fund prepaid State Hub credit","description":"One x402 settlement credits the payer wallet and returns a tenant bearer\nkey for subsequent State Hub ops.\n","operationId":"postStateDeposit","security":[],"x-payment-info":{"protocols":[{"x402":{}}],"price":{"mode":"fixed","currency":"USD","amount":"0.20"}},"requestBody":{"required":false,"description":"No request body required. Pay the x402 charge; the settling wallet is\ncredited and a tenant bearer key is returned once.\n","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{}}}}},"responses":{"200":{"description":"Deposit settled; tenant key issued once.","headers":{"X-PAYMENT-RESPONSE":{"$ref":"#/components/headers/XPaymentResponse"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StateDepositResponse"}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"409":{"$ref":"#/components/responses/DuplicatePayment"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/state/balance":{"get":{"tags":["state"],"summary":"Prepaid credit balance","description":"Identity-gated State Hub endpoint (not per-request x402). Requires\n`Authorization: Bearer <tenantKey>` minted by POST /v1/state/deposit.\n","operationId":"getStateBalance","security":[],"responses":{"200":{"description":"Current prepaid credit balance (USD).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StateBalanceResponse"}}}},"401":{"description":"Missing or invalid tenant key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/state/save":{"post":{"tags":["state"],"summary":"Save ephemeral wallet-scoped JSON state","description":"Stores a JSON `doc` under `key`, scoped to the paying wallet, with a\nTTL. Every doc is screened at write time against the published data\npolicy (`GET /v1/policy`):\n\n  - **Accepted:** JSON values (objects, arrays, strings, numbers,\n    booleans, null) and human-readable text within the per-doc byte cap\n    and per-wallet quotas.\n  - **Rejected (`422 screening_rejected`):** opaque blobs (embedded\n    base64 media, high-entropy strings) and — under the default policy —\n    hard secrets/PII (private keys, JWTs, AWS keys, card numbers, SSNs).\n    Under a `redact` deployment those are masked instead and the row is\n    returned `flagged`.\n  - **Allowed but recorded:** low-risk identifiers (email, phone).\n\n`key` must match `^[a-zA-Z0-9._:-]+$` (max 256 chars). Pre-screen with\n`GET /v1/policy` to avoid a rejected paid call.\n\nIdentity-gated (not per-request x402): requires bearer tenant key from\nPOST /v1/state/deposit.\n","operationId":"postStateSave","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StateSaveRequest"}}}},"responses":{"200":{"description":"State saved (Tier 0 screen; may be pending async review).","headers":{"x-latency-ms":{"schema":{"type":"string"}},"x-scan-status":{"schema":{"type":"string","enum":["clean","pending","flagged"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StateSaveResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"Prepaid credit exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Doc too large or quota exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Screening rejected the document.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/state/query":{"get":{"tags":["state"],"summary":"Query state by key or prefix","description":"Identity-gated State Hub endpoint (not per-request x402). Requires\n`Authorization: Bearer <tenantKey>`. Supply `key` or `prefix` (or both).\n","operationId":"getStateQuery","security":[],"parameters":[{"name":"key","in":"query","schema":{"type":"string"},"example":"session"},{"name":"prefix","in":"query","schema":{"type":"string"},"example":"user."}],"responses":{"200":{"description":"Matching non-expired state rows.","headers":{"x-latency-ms":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StateQueryResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"Prepaid credit exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"451":{"description":"Document quarantined.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/cache/{key}":{"get":{"tags":["state"],"summary":"Read a Redis hot-cache value","description":"Wallet-scoped cache read. Returns 404 when the key is missing or expired.\nReturns 503 when Redis is unavailable (Postgres state endpoints still work).\n\nIdentity-gated (not per-request x402): requires bearer tenant key from\nPOST /v1/state/deposit.\n","operationId":"getCacheKey","security":[],"parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-zA-Z0-9._:-]+$","maxLength":256},"example":"probe"}],"responses":{"200":{"description":"Cache hit.","headers":{"x-latency-ms":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CacheValueResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"description":"Redis unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["state"],"summary":"Set a Redis hot-cache value with TTL","description":"Identity-gated (not per-request x402): requires bearer tenant key from\nPOST /v1/state/deposit.\n","operationId":"putCacheKey","security":[],"parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-zA-Z0-9._:-]+$","maxLength":256},"example":"probe"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CacheSetRequest"}}}},"responses":{"200":{"description":"Value cached.","headers":{"x-latency-ms":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CacheSetResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"Prepaid credit exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid key or body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"description":"Redis unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["state"],"summary":"Delete a Redis hot-cache key","description":"Identity-gated (not per-request x402): requires bearer tenant key from\nPOST /v1/state/deposit.\n","operationId":"deleteCacheKey","security":[],"parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-zA-Z0-9._:-]+$","maxLength":256},"example":"probe"}],"responses":{"200":{"description":"Key deleted (or was absent).","headers":{"x-latency-ms":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"key":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"description":"Redis unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/state/search":{"post":{"tags":["state"],"summary":"Semantic nearest-neighbor search over wallet vectors","description":"pgvector KNN over embeddings created when saving state with `embed: true`.\nPremium prepaid-credit tier; wallet-isolated via RLS.\n\nIdentity-gated (not per-request x402): requires bearer tenant key from\nPOST /v1/state/deposit.\n","operationId":"postStateSearch","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StateSearchRequest"}}}},"responses":{"200":{"description":"Ranked vector hits.","headers":{"x-latency-ms":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StateSearchResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"Prepaid credit exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid query body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/state/{key}":{"delete":{"tags":["state"],"summary":"Delete one state key","description":"Identity-gated State Hub endpoint (not per-request x402). Requires\n`Authorization: Bearer <tenantKey>`.\n","operationId":"deleteStateKey","security":[],"parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-zA-Z0-9._:-]+$","maxLength":256},"example":"session"}],"responses":{"200":{"description":"Key deleted.","headers":{"x-latency-ms":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"key":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"securitySchemes":{"x402Payment":{"type":"apiKey","in":"header","name":"X-PAYMENT","description":"Signed x402 payment payload. Obtain the required parameters from the\n`402` response's `accepts` array, sign a USDC payment on the indicated\nnetwork, then resend the request with the base64 payload here.\nInformational only — payment is signaled by `x-payment-info` and the\n`402` response, not by an OpenAPI `security` requirement.\n"},"tenantBearer":{"type":"http","scheme":"bearer","description":"Tenant key minted by POST /v1/state/deposit (shown once)."}},"parameters":{"ServiceId":{"name":"serviceId","in":"path","required":true,"description":"Identifier of the x402 service to score: its registry slug or the\nhostname-derived id (dots replaced by dashes, e.g. `api-example-com`).\nDiscover known ids via GET /v1/data/x402-directory.\n","schema":{"type":"string"},"example":"demo-service"}},"headers":{"XPaymentResponse":{"description":"Base64-encoded settlement receipt for the paid request.","schema":{"type":"string"}},"DiscoveryLink":{"description":"RFC 8288 Link header advertising the discovery surfaces:\n`rel=\"payment-policy\"`, `rel=\"x402-manifest\"`, `rel=\"x402-catalog\"`,\nand `rel=\"service-desc\"`. Present on every response.\n","schema":{"type":"string","example":"<https://x402rail.net/v1/policy>; rel=\"payment-policy\"; type=\"application/json\""}},"XX402Policy":{"description":"Absolute URL of the data acceptance policy; sniffable via HEAD.","schema":{"type":"string","example":"https://x402rail.net/v1/policy"}},"CacheControl":{"description":"Caching directive. Static discovery docs (catalog, policy, OpenAPI) are\nedge-cacheable (`public, s-maxage=300, stale-while-revalidate=600`), so\nrepeated pre-flight polls are served from the CDN.\n","schema":{"type":"string","example":"public, s-maxage=300, stale-while-revalidate=600"}}},"responses":{"PaymentRequired":{"description":"Payment is required to access this resource.","headers":{"Accept-Payment":{"description":"Hint that x402 payment is accepted.","schema":{"type":"string"}},"Link":{"$ref":"#/components/headers/DiscoveryLink"},"X-X402-Policy":{"$ref":"#/components/headers/XX402Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequiredBody"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DuplicatePayment":{"description":"This X-PAYMENT was already settled for a prior request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ServiceUnavailable":{"description":"Idempotency store unavailable; payment was **not** settled. Safe to\nretry with the same or a new X-PAYMENT header.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"PayloadTooLarge":{"description":"Request body exceeds the maximum allowed size (extract only).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Per-IP request rate exceeded; retry after `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"integer","example":60}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing or invalid tenant bearer key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Health":{"type":"object","properties":{"status":{"type":"string","enum":["ok","degraded"]},"version":{"type":"string"},"time":{"type":"string","format":"date-time"}},"required":["status","version","time"]},"HealthSimple":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"timestamp":{"type":"string","format":"date-time"}},"required":["status","timestamp"]},"HealthReport":{"type":"object","properties":{"status":{"type":"string","enum":["healthy","degraded","unhealthy"]},"timestamp":{"type":"string","format":"date-time"},"uptime":{"type":"number"},"environment":{"type":"string"},"version":{"type":"string"},"checks":{"type":"object","properties":{"config":{"type":"object","additionalProperties":{"type":"string"}},"dependencies":{"type":"object","additionalProperties":{"type":"string"}}},"required":["config","dependencies"]},"config":{"type":"object","additionalProperties":true},"details":{"type":"object","additionalProperties":true}},"required":["status","timestamp","version","checks"]},"CatalogItem":{"type":"object","properties":{"endpoint":{"type":"string","example":"/v1/score/{serviceId}"},"method":{"type":"string","example":"GET"},"description":{"type":"string","description":"Intent-driven natural-language description for semantic discovery."},"keywords":{"type":"array","description":"Relevance keywords for BM25 / vector matching of agent prompt intent.","items":{"type":"string"},"example":["reliability score","reputation","counterparty risk"]},"priceUsd":{"type":"number","example":0.01},"network":{"type":"string","example":"base"},"asset":{"type":"string","example":"USDC"},"scheme":{"type":"string","description":"Settled x402 scheme (always `exact` today).","example":"exact"},"acceptedSchemes":{"type":"array","description":"Schemes the endpoint will negotiate; `exact` is the settled primary.","items":{"type":"string"},"example":["exact"]},"billing":{"type":"string","enum":["x402","prepaid_credit"],"description":"Direct x402 settlement, or spend against prepaid State Hub credit."},"priceTiers":{"type":"object","additionalProperties":{"type":"number"},"description":"TTL-tiered pricing, when the endpoint prices by retention."},"slaP99Ms":{"type":"integer","description":"Published p99 latency SLA in milliseconds, when offered."},"inputSchema":{"type":"object","additionalProperties":true,"description":"JSON Schema for the request input; every property carries a detailed\n`description` so an agent can construct its tool call unambiguously.\n"},"outputExample":{"description":"Realistic example of the 200 response body."},"model":{"allOf":[{"$ref":"#/components/schemas/ModelInfo"}],"description":"Inference model + data egress for endpoints backed by a model\n(e.g. /v1/extract). Absent on endpoints that use no model.\n"}},"required":["endpoint","method","description","priceUsd","network","asset","scheme","inputSchema","outputExample"]},"ModelInfo":{"type":"object","description":"Structured inference-model metadata for autonomous buyers.","properties":{"provider":{"type":"string","example":"anthropic"},"family":{"type":"string","example":"claude-sonnet"},"model":{"type":"string","example":"claude-sonnet-4-5"},"egress":{"type":"string","enum":["third_party","on_platform"],"description":"Where request content goes when the model runs."}},"required":["provider","family","model","egress"]},"DataPolicy":{"type":"object","description":"Machine-readable description of accepted vs. rejected content and the\nsize/TTL/quota limits that bound it. Served free at GET /v1/policy.\n","properties":{"version":{"type":"string","example":"1.3"},"summary":{"type":"string"},"acceptedShapes":{"type":"array","items":{"type":"string"}},"screening":{"type":"object","properties":{"mode":{"type":"string","enum":["reject","redact","flag"],"description":"Active deployment storage-screening policy (applies to State Hub)."},"surfaces":{"type":"array","description":"Per-endpoint screening behavior. Storage surfaces follow `mode`;\nsurfaces that forward content to a third-party model reject ANY\ndetected PII/secret regardless of `mode`.\n","items":{"type":"object","properties":{"endpoint":{"type":"string","example":"POST /v1/extract"},"destination":{"type":"string","enum":["stored","third_party_model"]},"onDetect":{"type":"object","description":"Disposition for each detector class on this surface.","properties":{"opaque":{"$ref":"#/components/schemas/Disposition"},"secret_or_pii":{"$ref":"#/components/schemas/Disposition"},"soft_identifier":{"$ref":"#/components/schemas/Disposition"}},"required":["opaque","secret_or_pii","soft_identifier"]},"thirdPartyEgress":{"type":"object","description":"Third-party model that reads content on this surface, if\nany. Present on /v1/extract (inline) and /v1/state/save\n(async governance review); omitted when data never leaves\nthe platform.\n","properties":{"provider":{"type":"string","example":"anthropic"},"family":{"type":"string","example":"claude-haiku"},"model":{"type":"string","example":"claude-haiku-4-5"},"when":{"type":"string","enum":["inline","async_review"],"description":"inline = synchronous to fulfil the call; async_review = later governance scan."},"note":{"type":"string"}},"required":["provider","family","model","when"]},"note":{"type":"string"}},"required":["endpoint","destination","onDetect"]}},"detectors":{"type":"array","description":"Catalog of what each detector matches and its risk class.","items":{"type":"object","properties":{"id":{"type":"string","example":"ssn"},"label":{"type":"string"},"class":{"type":"string","enum":["opaque","secret_or_pii","soft_identifier"]},"description":{"type":"string"}},"required":["id","label","class"]}}},"required":["mode","surfaces","detectors"]},"limits":{"type":"object","properties":{"state":{"type":"object","properties":{"maxDocBytes":{"type":"integer","example":65536},"keyPattern":{"type":"string","example":"^[a-zA-Z0-9._:-]+$"},"keyMaxLength":{"type":"integer","example":256},"defaultTtlSeconds":{"type":"integer","example":300},"maxTtlSeconds":{"type":"integer","example":604800},"quotaRowsPerWallet":{"type":"integer","example":10000},"quotaBytesPerWallet":{"type":"integer","example":52428800}},"required":["maxDocBytes","keyPattern","keyMaxLength"]},"extract":{"type":"object","properties":{"maxContentChars":{"type":"integer","example":100000},"note":{"type":"string"}},"required":["maxContentChars"]}},"required":["state","extract"]},"rejectionCodes":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","example":422},"error":{"type":"string","example":"screening_rejected"},"meaning":{"type":"string"}},"required":["status","error","meaning"]}},"discovery":{"type":"object","properties":{"wellKnown":{"type":"string","example":"/.well-known/x402"},"policy":{"type":"string","example":"/v1/policy"},"catalog":{"type":"string","example":"/v1/catalog"},"openapi":{"type":"string","example":"/openapi.json"}}}},"required":["version","summary","screening","limits","rejectionCodes"]},"Disposition":{"type":"string","enum":["reject","redact","allow"],"description":"Outcome for content that trips a detector: `reject` blocks the write,\n`redact` masks the match and stores the rest, `allow` stores it as-is\n(the detector hit is still recorded).\n"},"PaymentRequiredBody":{"type":"object","description":"x402 payment-required envelope. Beyond the standard `accepts` array it\ninlines the discovery surfaces (`policyUrl` + `discovery`) so an agent\nlearns the policy/manifest/catalog/spec at the moment it hits the\npaywall, with no pre-flight crawl.\n","properties":{"x402Version":{"type":"integer","example":1},"error":{"type":"string","example":"payment required"},"accepts":{"type":"array","items":{"$ref":"#/components/schemas/PaymentRequirements"}},"policyUrl":{"type":"string","description":"Absolute URL of the free data acceptance policy.","example":"https://x402rail.net/v1/policy"},"discovery":{"$ref":"#/components/schemas/DiscoveryLinks"}},"required":["x402Version","accepts"]},"DiscoveryLinks":{"type":"object","description":"Absolute URLs to the platform discovery surfaces.","properties":{"policyUrl":{"type":"string","example":"https://x402rail.net/v1/policy"},"wellKnownUrl":{"type":"string","example":"https://x402rail.net/.well-known/x402"},"catalogUrl":{"type":"string","example":"https://x402rail.net/v1/catalog"},"openapiUrl":{"type":"string","example":"https://x402rail.net/openapi.json"},"mcpUrl":{"type":"string","example":"https://x402rail.net/v2/x402/discovery/mcp"}},"required":["policyUrl","wellKnownUrl","catalogUrl","openapiUrl","mcpUrl"]},"WellKnownManifest":{"type":"object","description":"Root platform manifest served free at GET /.well-known/x402.","properties":{"x402Version":{"type":"integer","example":1},"provider":{"type":"string","example":"Agentics"},"description":{"type":"string"},"paymentEnv":{"type":"string","enum":["testnet","mainnet"]},"scheme":{"type":"string","example":"exact"},"payTo":{"type":"string","example":"0x0000000000000000000000000000000000000000"},"facilitator":{"type":"string","example":"https://x402.org/facilitator"},"supportedChains":{"type":"array","items":{"type":"object","properties":{"network":{"type":"string","example":"base-sepolia"},"caip2":{"type":"string","nullable":true,"example":"eip155:84532"},"chainId":{"type":"integer","nullable":true,"example":84532},"asset":{"type":"object","properties":{"address":{"type":"string","example":"0x036CbD53842c5426634e7929541eC2318f3dCF7e"},"symbol":{"type":"string","example":"USDC"},"decimals":{"type":"integer","example":6}},"required":["address","symbol","decimals"]},"active":{"type":"boolean"}},"required":["network","asset","active"]}},"models":{"type":"array","description":"Inference models the platform uses and where content goes, so an\nagent can decide before paying (extract) or before storing (state).\n","items":{"type":"object","properties":{"use":{"type":"string","enum":["extract","state-screening"]},"endpoint":{"type":"string","example":"POST /v1/extract"},"provider":{"type":"string","example":"anthropic"},"family":{"type":"string","example":"claude-sonnet"},"model":{"type":"string","example":"claude-sonnet-4-5"},"egress":{"type":"string","enum":["third_party","on_platform"]},"note":{"type":"string"}},"required":["use","endpoint","provider","family","model","egress"]}},"pricing":{"type":"object","description":"Settlement-scheme capability.","properties":{"settledScheme":{"type":"string","example":"exact"},"advertisedSchemes":{"type":"array","items":{"type":"string"},"example":["exact","upto"]}}},"trust":{"type":"object","description":"Active trust signals for ranking this endpoint when parsing a 402.","properties":{"ledgerIsTruth":{"type":"boolean","example":true},"reconciliation":{"type":"string"},"evidenceTrail":{"type":"string"},"healthEndpoint":{"type":"string"},"sourceRepo":{"type":"string"},"receiveOnly":{"type":"boolean","example":true}}},"policyEndpoint":{"type":"string","example":"https://x402rail.net/v1/policy"},"catalogEndpoint":{"type":"string","example":"https://x402rail.net/v1/catalog"},"openapiEndpoint":{"type":"string","example":"https://x402rail.net/openapi.json"},"healthEndpoint":{"type":"string","example":"https://x402rail.net/v1/health/simple"},"mcpEndpoint":{"type":"string","example":"https://x402rail.net/v2/x402/discovery/mcp"},"endpoints":{"type":"object","properties":{"policy":{"type":"string"},"catalog":{"type":"string"},"openapi":{"type":"string"},"health":{"type":"string"},"docs":{"type":"string"},"mcp":{"type":"string"}}},"generatedAt":{"type":"string","format":"date-time"}},"required":["x402Version","provider","paymentEnv","scheme","payTo","supportedChains","policyEndpoint","catalogEndpoint"]},"PaymentRequirements":{"type":"object","description":"One acceptable way to pay (mirrors the x402 spec; pin field names to the\ninstalled x402 library version).\n","properties":{"scheme":{"type":"string","example":"exact"},"network":{"type":"string","example":"base"},"maxAmountRequired":{"type":"string","description":"Amount in the asset's smallest unit (e.g. USDC 6dp).","example":"10000"},"resource":{"type":"string","example":"https://api.agentics.example/v1/score/abc"},"description":{"type":"string"},"mimeType":{"type":"string","example":"application/json"},"payTo":{"type":"string","example":"0x0000000000000000000000000000000000000000"},"asset":{"type":"string","example":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"},"maxTimeoutSeconds":{"type":"integer","example":60},"extra":{"type":"object","additionalProperties":true}},"required":["scheme","network","maxAmountRequired","payTo","asset"]},"ServiceScore":{"type":"object","example":{"serviceId":"demo-service","score":92.4,"components":{"availability":99.1,"latency":87,"fidelity":95.2,"identity":88},"sampleSize":144,"lastProbeAt":"2026-06-18T12:00:00.000Z","evidenceHash":"9f2b1c4d…"},"properties":{"serviceId":{"type":"string","example":"demo-service"},"score":{"type":"number","minimum":0,"maximum":100,"example":92.4},"components":{"type":"object","properties":{"availability":{"type":"number","minimum":0,"maximum":100,"example":99.1},"latency":{"type":"number","minimum":0,"maximum":100,"example":87},"fidelity":{"type":"number","minimum":0,"maximum":100,"example":95.2},"identity":{"type":"number","minimum":0,"maximum":100,"example":88}},"required":["availability","latency","fidelity","identity"]},"sampleSize":{"type":"integer","example":144},"lastProbeAt":{"type":"string","format":"date-time"},"evidenceHash":{"type":"string","description":"Hash anchoring the append-only probe evidence trail."},"lastProbe":{"type":"object","description":"Summary of the most recent probe sweep for this service.","properties":{"probeType":{"type":"string"},"ok":{"type":"boolean"},"latencyMs":{"type":"integer","nullable":true},"fidelity":{"type":"number","nullable":true},"createdAt":{"type":"string","format":"date-time"},"httpStatus":{"type":"integer","nullable":true},"payTo":{"type":"string","nullable":true},"network":{"type":"string","nullable":true},"probeKind":{"type":"string","enum":["health","x402"]}}}},"required":["serviceId","score","components","lastProbeAt"]},"ScorePoint":{"type":"object","properties":{"score":{"type":"number"},"computedAt":{"type":"string","format":"date-time"}},"required":["score","computedAt"]},"ExtractRequest":{"type":"object","properties":{"content":{"type":"string","description":"Raw text, markdown, or HTML to extract from. Capped at\n`limits.extract.maxContentChars` (GET /v1/policy); oversized input\nreturns 413 before settlement. Must not contain plaintext PII/secrets\n— those are screened and rejected (422) before the model is called.\n","example":"Acme Corp reported Q2-2026 revenue of $1.25M, up from $0.98M."},"schema":{"type":"object","description":"JSON Schema describing the desired output object. Richer per-property\ndescriptions yield better extraction. The result conforms to this shape.\n","additionalProperties":true,"example":{"type":"object","properties":{"company":{"type":"string"},"revenueUsd":{"type":"number"},"fiscalQuarter":{"type":"string"}},"required":["company","revenueUsd"]}},"instructions":{"type":"string","description":"Optional extra natural-language guidance to steer the extraction.","example":"Return revenue as a plain number in USD without currency symbols."}},"required":["content","schema"],"example":{"content":"Acme Corp reported Q2-2026 revenue of $1.25M.","schema":{"type":"object","properties":{"company":{"type":"string"},"revenueUsd":{"type":"number"}}}}},"ExtractResult":{"type":"object","properties":{"data":{"type":"object","description":"Extracted object conforming to the requested schema.","additionalProperties":true,"example":{"company":"Acme Corp","revenueUsd":1250000,"fiscalQuarter":"Q2-2026"}},"model":{"type":"string","example":"claude-sonnet-4-5"},"tokenUsage":{"type":"object","properties":{"input":{"type":"integer","example":812},"output":{"type":"integer","example":64}},"required":["input","output"]}},"required":["data","model"],"example":{"data":{"company":"Acme Corp","revenueUsd":1250000,"fiscalQuarter":"Q2-2026"},"model":"claude-sonnet-4-5","tokenUsage":{"input":812,"output":64}}},"Attestation":{"type":"object","description":"Off-chain Ed25519 signature binding a /v1/redact input to its output.","properties":{"id":{"type":"string","example":"8f14e45f-ceea-4e2a-9b1a-3c2e6f0a1b2c"},"algorithm":{"type":"string","enum":["ed25519"]},"hash":{"type":"string","description":"SHA-256 (hex) of the canonical attested payload."},"signature":{"type":"string","description":"Base64 Ed25519 signature over the hash."},"publicKey":{"type":"string","description":"SPKI PEM public key for independent verification."},"detectorVersion":{"type":"string","example":"redact-v1"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","algorithm","hash","signature","publicKey"]},"RedactResult":{"type":"object","properties":{"redacted":{"description":"The input with detected PII/secret spans replaced per `redactionMode`."},"detectors":{"type":"array","items":{"type":"string"},"example":["email","phone"]},"redactionMode":{"type":"string","enum":["remove","mask","pseudonymize"],"example":"mask"},"attestation":{"$ref":"#/components/schemas/Attestation"},"attestationUrl":{"type":"string","example":"https://x402rail.net/v1/attest/8f14e45f-ceea-4e2a-9b1a-3c2e6f0a1b2c"}},"required":["redacted","detectors","redactionMode","attestation"]},"AttestationResponse":{"type":"object","properties":{"attestation":{"$ref":"#/components/schemas/Attestation"},"detectors":{"type":"array","items":{"type":"string"}},"verified":{"type":"boolean","example":true}},"required":["attestation","verified"]},"PreflightResult":{"type":"object","description":"Aggregated vetting of an external x402 service (manifest + health + reputation).","properties":{"url":{"type":"string","format":"uri"},"origin":{"type":"string","format":"uri"},"serviceId":{"type":"string","example":"api-example-com"},"manifest":{"nullable":true,"type":"object","properties":{"provider":{"type":"string"},"paymentEnv":{"type":"string"},"scheme":{"type":"string"},"payTo":{"type":"string"},"facilitator":{"type":"string"},"networks":{"type":"array","items":{"type":"string"}},"advertisedSchemes":{"type":"array","items":{"type":"string"}},"receiveOnly":{"type":"boolean"}}},"health":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"ok":{"type":"boolean"},"httpStatus":{"type":"integer","nullable":true},"latencyMs":{"type":"integer"}},"required":["url","ok","latencyMs"]},"reputation":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/ServiceScore"}]},"assessment":{"type":"object","properties":{"selfDescribes":{"type":"boolean"},"reachable":{"type":"boolean"},"hasReliabilityScore":{"type":"boolean"},"notes":{"type":"array","items":{"type":"string"}}},"required":["selfDescribes","reachable","hasReliabilityScore","notes"]},"checkedAt":{"type":"string","format":"date-time"}},"required":["url","origin","serviceId","health","assessment","checkedAt"]},"ValidationResult":{"type":"object","description":"Verdict from validating a JSON value against a JSON Schema.","properties":{"valid":{"type":"boolean","example":false},"errorCount":{"type":"integer","example":1},"errors":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","description":"JSON Pointer to the offending location (empty = root).","example":"/email"},"keyword":{"type":"string","example":"format"},"message":{"type":"string","example":"must match format \"email\""}},"required":["path","keyword","message"]}}},"required":["valid","errorCount","errors"]},"DataFeedResponse":{"type":"object","properties":{"feed":{"type":"string","example":"x402-directory"},"asOf":{"type":"string","format":"date-time","example":"2026-06-18T12:00:00.000Z"},"rows":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["feed","asOf","rows"],"example":{"feed":"x402-directory","asOf":"2026-06-18T12:00:00.000Z","rows":[{"serviceId":"demo-service","url":"https://x402rail.net/v1/health/simple","network":"base-sepolia","score":92.4,"sampleSize":144,"lastProbeType":"x402","lastProbeAt":"2026-06-18T12:00:00.000Z"}]}},"StateDepositResponse":{"type":"object","properties":{"tenantKey":{"type":"string","description":"Bearer key for State Hub ops; shown once at deposit."},"creditUsd":{"type":"number","description":"Wallet prepaid balance after this deposit (USD)."}},"required":["tenantKey","creditUsd"]},"StateBalanceResponse":{"type":"object","properties":{"creditUsd":{"type":"number","description":"Remaining prepaid credit (USD)."}},"required":["creditUsd"]},"StateSaveRequest":{"type":"object","properties":{"key":{"type":"string"},"doc":{"type":"object","additionalProperties":true},"ttlSeconds":{"type":"integer","minimum":1}},"required":["key","doc"]},"StateSaveResponse":{"type":"object","properties":{"ok":{"type":"boolean"},"key":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"scanStatus":{"type":"string","enum":["clean","pending","flagged"]}},"required":["ok","key","expiresAt","scanStatus"]},"StateQueryResponse":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"doc":{"type":"object","additionalProperties":true},"expiresAt":{"type":"string","format":"date-time"},"scanStatus":{"type":"string"}},"required":["key","doc","expiresAt","scanStatus"]}}},"required":["items"]},"CacheSetRequest":{"type":"object","properties":{"value":{"description":"JSON-serializable value to cache."},"ttlSeconds":{"type":"integer","minimum":1,"maximum":86400}},"required":["value"]},"CacheSetResponse":{"type":"object","properties":{"ok":{"type":"boolean"},"key":{"type":"string"},"ttlSeconds":{"type":"integer"}},"required":["ok","key","ttlSeconds"]},"CacheValueResponse":{"type":"object","properties":{"value":{"description":"Cached JSON value."},"expiresAt":{"type":"string","format":"date-time"}},"required":["value","expiresAt"]},"StateSearchRequest":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":4096},"k":{"type":"integer","minimum":1}},"required":["query"]},"StateSearchResponse":{"type":"object","properties":{"hits":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"distance":{"type":"number"},"doc":{"type":"object","additionalProperties":true}},"required":["key","distance"]}},"count":{"type":"integer"}},"required":["hits","count"]},"Error":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable error code.","example":"cost_guard_exceeded"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"required":["error","message"]}}},"x-discovery":{"ownershipProofs":["0x4b4bC6c4862e42E5FC94112d81C389958132EF50"]}}