{ "openapi": "3.0.3", "info": { "title": "CedarProof HTTP response diagnostics", "version": "cedarproof-http-v1-js1", "description": "Fixed-rule HTTP/JSON response classification: success, failure, partial or unknown. Public non-sensitive snippets only. No root-cause analysis, repair, AI inference or business-success guarantee. Unknown is a delivered paid result." }, "servers": [ { "url": "https://cedarproof-diagnostics.cedarproof-lab.workers.dev" } ], "paths": { "/v1/diagnose": { "post": { "operationId": "diagnoseHttpResponse", "summary": "Classify a public HTTP/JSON response snippet using fixed rules", "description": "POST exactly four JSON fields to get a payment quote when new payments are enabled. Price: 0.01 native USDC on Base per delivered classification, including unknown. No server account or API key is required. After an accepted proof and independently reconciled payment, the fixed result is returned; an unresolved order returns 202. This endpoint does not fetch URLs, execute submitted text, repair code or provide AI root-cause analysis. Preserve the original request_id, input and payment proof privately. Never automatically create a replacement payment. A 202 response does not prove success or failure of settlement; wait at least Retry-After seconds and retry the identical input with the original proof. Recovery of an existing pending or paid order does not resubmit settlement, even after that proof expires. A retry without its original proof cannot retrieve a result. Host infrastructure processes requests. Application persistence keeps hashes, fixed results and order/payment evidence rather than raw snippet bodies or signatures; hashes are not anonymity and this is not a promise about infrastructure logs.", "x-payment-info": { "protocols": [ "x402" ], "price": { "mode": "fixed", "currency": "USD", "amount": "0.01" } }, "security": [ { "x402": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "request_id", "http_status", "profile", "body" ], "description": "Exactly four fields. Entire serialized request must be valid UTF-8 JSON of at most 32768 bytes. Duplicate keys, unknown fields, NaN/Infinity and nonfinite numeric overflow are rejected before any payment attempt. No URL query string is accepted.", "x-max-request-utf8-bytes": 32768, "properties": { "request_id": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$", "example": "94f1a6cd-73de-4d8a-9c26-24b15db04f5b", "description": "Generate a fresh UUIDv4 for each intended purchase. This fixed synthetic UUID is for unsigned examples/probes only; do not reuse it for a real purchase. The server normalizes hex to lowercase. Recovery reuses the original ID and identical input/proof." }, "http_status": { "type": "integer", "minimum": 100, "maximum": 599, "example": 200, "description": "Observed HTTP status. Use a JSON integer token: 200 is accepted, while 200.0 and 2e2 are rejected. OpenAPI integer alone does not express this lexical restriction." }, "profile": { "type": "string", "enum": [ "generic", "etherscan" ], "example": "generic", "description": "Choose from trusted knowledge of the response source. generic checks narrowly recognized top-level boolean/status, JSON-RPC and GraphQL signals. etherscan additionally recognizes string status=\"0\", message=\"NOTOK\" and a nonempty string result. The payload does not authenticate its provider." }, "body": { "type": "string", "example": "{\"ok\":true}", "x-max-utf8-bytes": 16384, "x-max-json-container-depth": 64, "description": "Public, non-sensitive response snippet; at most 16384 UTF-8 bytes after JSON string decoding. This is a byte limit, not a character count. Supply the response text as a JSON string, not an object. Empty, malformed, duplicate-key, nonfinite or over-depth JSON inside this field can produce a paid unknown result; it is not rejected as invalid outer input. Do not send credentials, secrets or personal data. HTTP 4xx/5xx is classified from status without examining this snippet." } } }, "example": { "request_id": "94f1a6cd-73de-4d8a-9c26-24b15db04f5b", "http_status": 200, "profile": "generic", "body": "{\"ok\":true}" } } } }, "responses": { "200": { "description": "Delivered fixed classification after payment reconciliation, or the same stored result on an identical same-proof retry. HTTP 200 here does not mean the diagnosed response succeeded. unknown is a valid paid result.", "headers": { "PAYMENT-RESPONSE": { "description": "Base64-encoded UTF-8 JSON receipt for the reconciled x402 payment. Retain privately with the original request and proof.", "schema": { "type": "string", "format": "byte" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "request_id", "engine", "verdict", "reason_codes" ], "properties": { "request_id": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$", "example": "94f1a6cd-73de-4d8a-9c26-24b15db04f5b", "description": "The submitted UUID normalized to lowercase." }, "engine": { "type": "string", "enum": [ "cedarproof-http-v1-js1" ], "example": "cedarproof-http-v1-js1" }, "verdict": { "type": "string", "enum": [ "success", "failure", "partial", "unknown" ], "example": "success", "description": "success means a recognized success signal; failure means a recognized HTTP/application failure; partial means a GraphQL-shaped object has data plus errors without another explicit failure signal; unknown means no supported conclusion. These are fixed rules, not root-cause analysis or proof of business success. unknown is a delivered result at the same price." }, "reason_codes": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "HTTP_ERROR_STATUS", "HTTP_NON_2XX_STATUS", "EMPTY_BODY", "INVALID_JSON", "NON_OBJECT_JSON", "EXPLICIT_FALSE_FLAG", "EXPLICIT_TRUE_FLAG", "EXPLICIT_FAILURE_STATUS", "EXPLICIT_SUCCESS_STATUS", "JSON_RPC_ERROR", "JSON_RPC_RESULT", "MALFORMED_JSON_RPC_ENVELOPE", "GRAPHQL_ERRORS", "GRAPHQL_DATA_WITH_ERRORS", "CONFLICTING_SUCCESS_FAILURE_SIGNALS", "NO_RECOGNIZED_APPLICATION_SIGNAL", "ETHERSCAN_NOTOK" ] }, "example": [ "EXPLICIT_TRUE_FLAG" ], "description": "Fixed code vocabulary only. No snippet text or upstream exception text is returned." } } }, "example": { "request_id": "94f1a6cd-73de-4d8a-9c26-24b15db04f5b", "engine": "cedarproof-http-v1-js1", "verdict": "success", "reason_codes": [ "EXPLICIT_TRUE_FLAG" ] } } } }, "202": { "description": "Preserve the original request_id, input and payment proof privately. Never automatically create a replacement payment. A 202 response does not prove success or failure of settlement; wait at least Retry-After seconds and retry the identical input with the original proof. Recovery of an existing pending or paid order does not resubmit settlement, even after that proof expires. A retry without its original proof cannot retrieve a result.", "headers": { "Retry-After": { "description": "Wait at least 30 seconds before an identical same-proof retry.", "schema": { "type": "string", "enum": [ "30" ], "example": "30" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pending" }, "example": { "request_id": "94f1a6cd-73de-4d8a-9c26-24b15db04f5b", "status": "pending", "message": "Outcome unresolved. Reuse this request ID, identical input and original payment proof. Do not send a new payment. Keep the original proof privately." } } } }, "400": { "description": "unsupported_url (including any query string), invalid_input, invalid_or_unsupported_payment_proof, or authorization_time_out_of_bounds. Invalid outer requests do not obtain a quote. Do not retry malformed data unchanged or automatically generate a new payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Unsigned valid new request: no order is reserved and no payment attempt is made. The quote is returned in both JSON and PAYMENT-REQUIRED. EOA EIP-3009 with a 65-byte signature only; smart-wallet signatures and Bazaar proof extensions are unsupported. EIP-3009 authorizes a transfer, not the input or URL; the server binds the first accepted proof to an immutable result. Use the exact live quote.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64-encoded UTF-8 JSON matching paymentRequired in the response body; x402Version is 2.", "schema": { "type": "string", "format": "byte" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentChallenge" } } } }, "405": { "description": "This path only accepts POST (plus OPTIONS for preflight).", "headers": { "Allow": { "schema": { "type": "string", "example": "POST, OPTIONS" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Immutable request/input/proof conflict: order_input_conflict, order_payment_conflict, concurrent_order_conflict or authorization_already_bound. Return to the original input/proof instead of paying again. pre_settlement_reservation_expired means this server never submitted settlement for that stale reservation; it has been closed without an automatic replacement payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Content-Type must be application/json (a charset parameter is permitted).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "verification_not_accepted: this verification attempt was rejected before settlement. A recovery of an already rejected order instead returns status rejected_before_settlement. Do not interpret either as pending settlement or create a replacement payment automatically.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/RejectedOrder" } ] } } } }, "503": { "description": "payments_unavailable, pilot_capacity_reached, reservation_changed_retry_same_request, service_unavailable, or the detailed pre_settlement_unavailable shape. For pre_settlement_unavailable, stage and settlement_submitted=false are authoritative for this attempt; same-proof retry is only allowed while the original authorization has more than 6 seconds left. Generic service_unavailable does not rule out submitted settlement: preserve the original request/proof and use same-proof recovery only.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/PreSettlementUnavailable" } ] }, "examples": { "preSettlement": { "value": { "error": "pre_settlement_unavailable", "request_id": "94f1a6cd-73de-4d8a-9c26-24b15db04f5b", "stage": "facilitator_verify", "upstream_code": "transport_failed", "settlement_submitted": false, "retry": "same_request_same_input_original_proof_while_valid", "message": "This attempt did not submit settlement. Retry the identical request ID, input and original proof only while its authorization has more than 6 seconds remaining. Do not automatically create a replacement payment. An expired proof cannot start settlement." } }, "generic": { "value": { "error": "service_unavailable", "message": "Preserve request_id, body and original proof. Retry the same request; do not create a replacement payment." } } } } } } } } }, "/v1/diagnose-nano": { "post": { "operationId": "diagnoseHttpResponseNano", "summary": "Classify a public HTTP/JSON response snippet with a Nano payment", "description": "POST exactly four JSON fields. A valid new request without PAYMENT-SIGNATURE returns the live x402 v2 exact nano:mainnet offer when Nano purchases are available. Price: 0.05 XNO per delivered fixed classification, including unknown. No server account or API key is required. The classification rules and input limits are the same as /v1/diagnose. This endpoint does not fetch submitted URLs, execute text, repair code or provide AI root-cause analysis. Payment uses a signed Nano state send block with work; a confirmed state-block predecessor is checked before settlement. Nonempty proof extensions and unrelated payment schemes are unsupported. Keep the original request_id, identical input and original payment proof privately. Never automatically create a replacement payment. The first accepted proof permanently binds the request ID, input, quote and signed block. Matching existing input without the original proof returns 409 original_payment_proof_required; waiting alone cannot retrieve it. On 202, honor the actual Retry-After value and retry the identical request with its original proof. Recovery first checks confirmation and can retransmit only that same bound Nano block when purchases are enabled and the transport lease permits it. The service allows at most three settlement transport claims, separated by 90-second leases; confirmation recovery remains possible after those claims are exhausted. There is no Base EIP-3009 time window or 24-hour order expiry in this Nano handler. The advertised maxTimeoutSeconds=30 is not a state-block or order-binding expiry. Host infrastructure processes requests. Application persistence retains hashes, fixed results and order/payment evidence rather than raw snippet bodies or signatures; hashes do not provide anonymity or make promises about infrastructure logs.", "security": [ {}, { "x402": [] } ], "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "description": "Omit for the initial unsigned quote. For an intentional purchase or recovery, supply the privately retained base64 x402 v2 Nano payload using the exact accepted offer and original signed state block with work. The original proof is required for result retrieval. No proof or signature example is supplied.", "schema": { "type": "string", "format": "byte" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "request_id", "http_status", "profile", "body" ], "description": "Exactly four fields. Entire serialized request must be valid UTF-8 JSON of at most 32768 bytes. Duplicate keys, unknown fields, NaN/Infinity and nonfinite numeric overflow are rejected before any payment attempt. No URL query string is accepted.", "x-max-request-utf8-bytes": 32768, "properties": { "request_id": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$", "example": "94f1a6cd-73de-4d8a-9c26-24b15db04f5b", "description": "Generate a fresh UUIDv4 for each intended purchase. This fixed synthetic UUID is for unsigned examples/probes only; do not reuse it for a real purchase. The server normalizes hex to lowercase. Recovery reuses the original ID and identical input/proof." }, "http_status": { "type": "integer", "minimum": 100, "maximum": 599, "example": 200, "description": "Observed HTTP status. Use a JSON integer token: 200 is accepted, while 200.0 and 2e2 are rejected. OpenAPI integer alone does not express this lexical restriction." }, "profile": { "type": "string", "enum": [ "generic", "etherscan" ], "example": "generic", "description": "Choose from trusted knowledge of the response source. generic checks narrowly recognized top-level boolean/status, JSON-RPC and GraphQL signals. etherscan additionally recognizes string status=\"0\", message=\"NOTOK\" and a nonempty string result. The payload does not authenticate its provider." }, "body": { "type": "string", "example": "{\"ok\":true}", "x-max-utf8-bytes": 16384, "x-max-json-container-depth": 64, "description": "Public, non-sensitive response snippet; at most 16384 UTF-8 bytes after JSON string decoding. This is a byte limit, not a character count. Supply the response text as a JSON string, not an object. Empty, malformed, duplicate-key, nonfinite or over-depth JSON inside this field can produce a paid unknown result; it is not rejected as invalid outer input. Do not send credentials, secrets or personal data. HTTP 4xx/5xx is classified from status without examining this snippet." } } }, "example": { "request_id": "94f1a6cd-73de-4d8a-9c26-24b15db04f5b", "http_status": 200, "profile": "generic", "body": "{\"ok\":true}" } } } }, "responses": { "200": { "description": "Delivered fixed classification after confirmation of the bound Nano send, or the same stored result on an identical original-proof retry. HTTP 200 does not mean the diagnosed response succeeded; unknown is a delivered result at the same price.", "headers": { "PAYMENT-RESPONSE": { "description": "Base64-encoded UTF-8 JSON containing success=true, transaction (the bound Nano block hash), network=nano:mainnet and payer. It confirms the server reconciled the send; recipient wallet receive/open and asset control are separate. No real receipt example is supplied.", "schema": { "type": "string", "format": "byte" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "request_id", "engine", "verdict", "reason_codes" ], "properties": { "request_id": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$", "example": "94f1a6cd-73de-4d8a-9c26-24b15db04f5b", "description": "The submitted UUID normalized to lowercase." }, "engine": { "type": "string", "enum": [ "cedarproof-http-v1-js1" ], "example": "cedarproof-http-v1-js1" }, "verdict": { "type": "string", "enum": [ "success", "failure", "partial", "unknown" ], "example": "success", "description": "success means a recognized success signal; failure means a recognized HTTP/application failure; partial means a GraphQL-shaped object has data plus errors without another explicit failure signal; unknown means no supported conclusion. These are fixed rules, not root-cause analysis or proof of business success. unknown is a delivered result at the same price." }, "reason_codes": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "HTTP_ERROR_STATUS", "HTTP_NON_2XX_STATUS", "EMPTY_BODY", "INVALID_JSON", "NON_OBJECT_JSON", "EXPLICIT_FALSE_FLAG", "EXPLICIT_TRUE_FLAG", "EXPLICIT_FAILURE_STATUS", "EXPLICIT_SUCCESS_STATUS", "JSON_RPC_ERROR", "JSON_RPC_RESULT", "MALFORMED_JSON_RPC_ENVELOPE", "GRAPHQL_ERRORS", "GRAPHQL_DATA_WITH_ERRORS", "CONFLICTING_SUCCESS_FAILURE_SIGNALS", "NO_RECOGNIZED_APPLICATION_SIGNAL", "ETHERSCAN_NOTOK" ] }, "example": [ "EXPLICIT_TRUE_FLAG" ], "description": "Fixed code vocabulary only. No snippet text or upstream exception text is returned." } } }, "example": { "request_id": "94f1a6cd-73de-4d8a-9c26-24b15db04f5b", "engine": "cedarproof-http-v1-js1", "verdict": "success", "reason_codes": [ "EXPLICIT_TRUE_FLAG" ] } } } }, "202": { "description": "The bound outcome remains unresolved; this does not establish payment success or failure. Honor Retry-After and retry identical input, ID and original proof. Recovery may retransmit that same bound block under the transport lease and attempt limit; it does not request a new payment. New-purchase disablement prevents retransmission but still permits confirmation recovery. Keep the original request_id, identical input and original payment proof privately. Never automatically create a replacement payment.", "headers": { "Retry-After": { "description": "Required minimum wait in seconds. Honor the returned value; the current implementation uses a minimum of 10 seconds and a 90-second settlement transport lease. It is not the fixed Base 30-second retry interval.", "schema": { "type": "string", "pattern": "^[0-9]+$" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "request_id", "status", "message" ], "properties": { "request_id": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$", "example": "94f1a6cd-73de-4d8a-9c26-24b15db04f5b" }, "status": { "type": "string", "enum": [ "pending" ] }, "message": { "type": "string" } } } } } }, "400": { "description": "Unsupported origin/query string, invalid outer input, or malformed/unsupported Nano proof. Invalid outer input receives no quote. No EIP-3009 authorization-time error applies to this Nano route.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "unsupported_url", "invalid_input", "invalid_or_unsupported_payment_proof" ] }, "required": { "type": "string" } } } } } }, "402": { "description": "Valid unsigned new request while Nano purchases are available. No order is reserved and no payment attempt is made. The response body is the bare x402 object with x402Version, resource and accepts; PAYMENT-REQUIRED encodes that same object. Use its exact Nano offer. A signed state send block and work are required for a subsequent purchase; the payer needs a confirmed state-block predecessor. This is not the Base request_id/paymentRequired wrapper.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64-encoded UTF-8 JSON equal to the entire response body.", "schema": { "type": "string", "format": "byte" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "x402Version", "resource", "accepts" ], "properties": { "x402Version": { "type": "integer", "enum": [ 2 ] }, "resource": { "type": "object", "additionalProperties": false, "required": [ "url", "description", "mimeType" ], "properties": { "url": { "type": "string", "enum": [ "https://cedarproof-diagnostics.cedarproof-lab.workers.dev/v1/diagnose-nano" ] }, "description": { "type": "string" }, "mimeType": { "type": "string", "enum": [ "application/json" ] } } }, "accepts": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "additionalProperties": false, "required": [ "scheme", "network", "amount", "asset", "payTo", "maxTimeoutSeconds", "extra" ], "properties": { "scheme": { "type": "string", "enum": [ "exact" ] }, "network": { "type": "string", "enum": [ "nano:mainnet" ] }, "amount": { "type": "string", "enum": [ "50000000000000000000000000000" ], "description": "Raw Nano amount: 50000000000000000000000000000 raw equals 0.05 XNO. This is not a USD price." }, "asset": { "type": "string", "enum": [ "XNO" ] }, "payTo": { "type": "string", "pattern": "^nano_[13][13456789abcdefghijkmnopqrstuwxyz]{59}$", "description": "Public recipient from the actual live offer. Use the exact live value; static documentation does not authorize a payment." }, "maxTimeoutSeconds": { "type": "integer", "enum": [ 30 ], "description": "Advertised x402 quote field. This is not an expiry of the Nano signed state block or the stored order binding." }, "extra": { "type": "object", "additionalProperties": false, "required": [ "work", "workThreshold" ], "properties": { "work": { "type": "string", "enum": [ "required" ] }, "workThreshold": { "type": "string", "enum": [ "fffffff800000000" ] } } } }, "description": "Current fixed Nano offer. Read and use the actual unsigned 402 offer; do not construct a payment from this static descriptor alone." } } }, "description": "The entire Nano 402 response body is this object. There is no request_id/paymentRequired wrapper." } } } }, "405": { "description": "This path only accepts POST (plus OPTIONS for preflight).", "headers": { "Allow": { "schema": { "type": "string", "example": "POST, OPTIONS" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "use_POST" ] } } } } } }, "409": { "description": "order_input_conflict means this ID is bound to different input. original_payment_proof_required means matching existing input was sent without its original proof; this response does not reveal the order payment state and does not issue a replacement quote. Other codes report a conflicting proof/block or concurrent binding. Preserve and use the original ID, input and proof; do not pay again.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "order_input_conflict", "original_payment_proof_required", "order_payment_conflict", "payment_already_bound", "concurrent_order_conflict" ] }, "request_id": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$", "example": "94f1a6cd-73de-4d8a-9c26-24b15db04f5b" }, "message": { "type": "string" } } } } } }, "415": { "description": "Content-Type must be application/json (a charset parameter is permitted).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "json_required" ] } } } } } }, "422": { "description": "verification_not_accepted or unsupported_or_unconfirmed_predecessor. settlement_submitted_by_this_attempt=false is scoped only to this attempt; it is not a claim about another or concurrent attempt. No replacement payment is requested. Preserve the original proof.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "error", "request_id", "settlement_submitted_by_this_attempt" ], "properties": { "error": { "type": "string", "enum": [ "verification_not_accepted", "unsupported_or_unconfirmed_predecessor" ] }, "request_id": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$", "example": "94f1a6cd-73de-4d8a-9c26-24b15db04f5b" }, "settlement_submitted_by_this_attempt": { "type": "boolean", "enum": [ false ] }, "message": { "type": "string" } } } } } }, "503": { "description": "nano_service_not_configured or nano_payments_unavailable means a new Nano purchase cannot currently proceed. pilot_capacity_reached, pre_settlement_unavailable and pre_settlement_chain_unavailable carry settlement_submitted_by_this_attempt=false where shown by the response; this flag applies only to that attempt. Generic service_unavailable does not establish whether settlement was submitted. Preserve the original ID, input and proof. Never automatically create a replacement payment.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "nano_service_not_configured", "nano_payments_unavailable", "pilot_capacity_reached", "pre_settlement_unavailable", "pre_settlement_chain_unavailable", "service_unavailable" ] }, "request_id": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$", "example": "94f1a6cd-73de-4d8a-9c26-24b15db04f5b" }, "message": { "type": "string" }, "settlement_submitted_by_this_attempt": { "type": "boolean", "enum": [ false ] }, "retry": { "type": "string", "enum": [ "same_request_same_input_original_proof" ] } } } } } } } } } }, "components": { "securitySchemes": { "x402": { "type": "apiKey", "in": "header", "name": "PAYMENT-SIGNATURE", "description": "Base64 x402 v2 payment payload using the exact live PAYMENT-REQUIRED quote. Omit on the initial request to receive 402; a matching original proof is required for paid-result retrieval/recovery. This is a payment proof, not a server API key. No proof/signature example is supplied." } }, "schemas": { "PaymentRequirements": { "type": "object", "additionalProperties": false, "required": [ "scheme", "network", "amount", "asset", "payTo", "maxTimeoutSeconds", "extra" ], "description": "Current advertised offer. Read the actual 402 response and use its exact accepted offer; do not construct a payment from static documentation alone.", "properties": { "scheme": { "type": "string", "enum": [ "exact" ], "example": "exact" }, "network": { "type": "string", "enum": [ "eip155:8453" ], "example": "eip155:8453" }, "amount": { "type": "string", "enum": [ "10000" ], "example": "10000", "description": "10000 atomic units of native Base USDC (6 decimals), equal to 0.01 USDC." }, "asset": { "type": "string", "enum": [ "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" ], "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }, "payTo": { "type": "string", "enum": [ "0x67F2512447Ad352638EeFeC0655fdEb6C436cAF3" ], "example": "0x67F2512447Ad352638EeFeC0655fdEb6C436cAF3" }, "maxTimeoutSeconds": { "type": "integer", "enum": [ 300 ], "example": 300 }, "extra": { "type": "object", "additionalProperties": false, "required": [ "name", "version" ], "properties": { "name": { "type": "string", "enum": [ "USD Coin" ], "example": "USD Coin" }, "version": { "type": "string", "enum": [ "2" ], "example": "2" } } } } }, "PaymentRequired": { "type": "object", "additionalProperties": false, "required": [ "x402Version", "resource", "accepts" ], "properties": { "x402Version": { "type": "integer", "enum": [ 2 ], "example": 2 }, "resource": { "type": "object", "additionalProperties": false, "required": [ "url", "description", "mimeType" ], "properties": { "url": { "type": "string", "enum": [ "https://cedarproof-diagnostics.cedarproof-lab.workers.dev/v1/diagnose" ], "example": "https://cedarproof-diagnostics.cedarproof-lab.workers.dev/v1/diagnose" }, "description": { "type": "string" }, "mimeType": { "type": "string", "enum": [ "application/json" ], "example": "application/json" } } }, "accepts": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/PaymentRequirements" } } } }, "PaymentChallenge": { "type": "object", "additionalProperties": false, "required": [ "request_id", "paymentRequired" ], "properties": { "request_id": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$", "example": "94f1a6cd-73de-4d8a-9c26-24b15db04f5b" }, "paymentRequired": { "$ref": "#/components/schemas/PaymentRequired" } } }, "Pending": { "type": "object", "additionalProperties": false, "required": [ "request_id", "status", "message" ], "properties": { "request_id": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$", "example": "94f1a6cd-73de-4d8a-9c26-24b15db04f5b" }, "status": { "type": "string", "enum": [ "pending" ], "example": "pending" }, "message": { "type": "string" } }, "description": "Preserve the original request_id, input and payment proof privately. Never automatically create a replacement payment. A 202 response does not prove success or failure of settlement; wait at least Retry-After seconds and retry the identical input with the original proof. Recovery of an existing pending or paid order does not resubmit settlement, even after that proof expires. A retry without its original proof cannot retrieve a result." }, "Error": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "unsupported_url", "invalid_input", "invalid_or_unsupported_payment_proof", "authorization_time_out_of_bounds", "order_input_conflict", "order_payment_conflict", "authorization_already_bound", "concurrent_order_conflict", "pre_settlement_reservation_expired", "verification_not_accepted", "json_required", "use_POST", "payments_unavailable", "reservation_changed_retry_same_request", "pilot_capacity_reached", "service_unavailable" ] }, "request_id": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$", "example": "94f1a6cd-73de-4d8a-9c26-24b15db04f5b" }, "message": { "type": "string" }, "required": { "type": "string" } } }, "RejectedOrder": { "type": "object", "additionalProperties": false, "required": [ "request_id", "status", "message" ], "properties": { "request_id": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$", "example": "94f1a6cd-73de-4d8a-9c26-24b15db04f5b" }, "status": { "type": "string", "enum": [ "rejected_before_settlement" ], "example": "rejected_before_settlement" }, "message": { "type": "string" } }, "description": "Existing rejected-order recovery response; this closed order has no settlement submitted by this server." }, "PreSettlementUnavailable": { "type": "object", "additionalProperties": false, "required": [ "error", "request_id", "stage", "settlement_submitted", "retry", "message" ], "properties": { "error": { "type": "string", "enum": [ "pre_settlement_unavailable" ], "example": "pre_settlement_unavailable" }, "request_id": { "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$", "example": "94f1a6cd-73de-4d8a-9c26-24b15db04f5b" }, "stage": { "type": "string", "enum": [ "facilitator_verify", "chain_anchor" ], "description": "facilitator_verify is payment-proof verification; chain_anchor is obtaining a chain starting point before settlement." }, "upstream_code": { "type": "string", "enum": [ "fetch_receiver_mismatch", "transport_failed", "redirect_refused", "response_unreadable", "response_not_json", "response_invalid_shape" ], "description": "Optional fixed diagnostic, only when stage is facilitator_verify. Never contains an upstream body, URL, signature or exception text." }, "upstream_status": { "type": "integer", "minimum": 100, "maximum": 599, "description": "Optional upstream HTTP status when available; not the HTTP status of the snippet being diagnosed." }, "settlement_submitted": { "type": "boolean", "enum": [ false ], "example": false }, "retry": { "type": "string", "enum": [ "same_request_same_input_original_proof_while_valid" ], "example": "same_request_same_input_original_proof_while_valid" }, "message": { "type": "string" } }, "description": "This attempt did not submit settlement. Only retry the same ID, identical input and original proof while authorization has more than 6 seconds remaining; never generate a replacement payment automatically. New-order admission requires validAfter <= current server time and 6 < validBefore-current time <= 600 seconds. The advertised quote uses maxTimeoutSeconds=300. Expired proofs cannot start a new settlement. These fields are specific to this error; generic 503 service_unavailable does not establish whether settlement was submitted." } } } }