{ "openapi": "3.1.0", "info": { "title": "402Proof", "description": "402Proof is SCRIPTMASTERLABS HTTP 402 invoice-based payment verification infrastructure. The payer submits an on-chain payment, then POST /v1/verify verifies it and issues a product-local access token. Optional standard x402 v2 XRPL /verify and /settle routes are implemented behind a disabled-by-default, authenticated SDK sidecar. Real availability must be checked from /supported; empty kinds means no standard settlement is enabled. This is independent of SqueezeOS. The current 402Proof protocol requires an invoice-specific private recovery_secret returned on POST /v1/invoice for both initial POST /v1/verify and recovery; it is never included in on-chain memo data. The Base USDC rail requires an invoice-bound ERC-3009 transferWithAuthorization; generic ERC-20 transfers cannot settle invoices.", "version": "3.2.0", "contact": { "name": "Script Master Labs", "url": "https://www.scriptmasterlabs.com", "email": "tim@scriptmasterlabs.com" } }, "servers": [ { "url": "https://four02proof.onrender.com", "description": "402Proof service" } ], "paths": { "/v1/invoice": { "post": { "operationId": "create_402proof_invoice", "summary": "Create a 402Proof product invoice", "description": "Creates an invoice inside the independent 402Proof settlement domain. It does not create a SqueezeOS PAYMENT-REQUIRED challenge.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "endpoint_id" ], "properties": { "endpoint_id": { "type": "string" }, "currency": { "type": "string", "description": "Optional rail selector. See GET /supported for configured combinations; fresh invoices define executable terms." }, "chain": { "type": "string", "description": "Optional rail selector. See GET /supported for configured combinations; fresh invoices define executable terms." }, "asset": { "type": "string", "description": "Optional rail selector. See GET /supported for configured combinations; fresh invoices define executable terms." }, "network": { "type": "string", "description": "Optional rail selector. See GET /supported for configured combinations; fresh invoices define executable terms." } } } } } }, "responses": { "200": { "description": "Invoice challenge including a private recovery_secret. Keep it off-chain and out of public logs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice_id": { "type": "string" }, "recovery_secret": { "type": "string", "minLength": 32, "description": "Secret returned only to invoice requester; required for first settlement claim and for crash/retry recovery. Never publish in transaction memo or logs." }, "pay_to": { "type": "string" }, "amount": { "type": "string" }, "asset": { "type": "string" }, "network": { "type": "string" }, "base_auth_nonce": { "type": "string", "description": "Base rail ONLY. 32-byte invoice-specific nonce for EIP-3009 transferWithAuthorization on Base USDC, e.g. 0x<64 hex>. Required for payment verification; not an access credential." }, "base_auth_method": { "type": "string", "description": "Base rail ONLY: transferWithAuthorization(address,address,uint256,uint256,uint256,bytes32,uint8,bytes32,bytes32)." } }, "required": [ "invoice_id", "recovery_secret", "pay_to", "amount", "asset", "network" ] } } } }, "4XX": { "description": "Invoice could not be created" } } } }, "/v1/verify": { "post": { "operationId": "verify_402proof_settlement", "summary": "Verify a 402Proof settlement", "description": "Verifies settlement evidence for a 402Proof invoice and may return a product-local access credential. That credential is not a SqueezeOS PAYMENT-SIGNATURE. This POST /v1/verify route is the post-payment step that some external docs call a 'claim' - there is no /v1/claim route on this service by design. BREAKING SECURITY CHANGE: each claim must supply the original invoice recovery_secret; public invoice_id/tx_hash/wallet alone cannot authorize a token. Exact previously-settled retries can recover only the original non-expired token. Base USDC verifies EIP-3009 authorization nonce = the invoice's base_auth_nonce, with exact recipient, value and mined USDC Transfer event. Ordinary transfer() cannot claim a new invoice.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "invoice_id", "recovery_secret", "tx_hash", "agent_wallet" ], "properties": { "invoice_id": { "type": "string" }, "tx_hash": { "type": "string" }, "agent_wallet": { "type": "string" }, "agent_domain": { "type": "string" }, "fee_tx_hash": { "type": "string", "description": "Required when the invoice declares fee_required; hash of its separately specified fee payment." }, "recovery_secret": { "type": "string", "description": "Original private invoice challenge secret. Required for BOTH initial verification and exact retry recovery; never put on-chain." } } } } } }, "responses": { "200": { "description": "402Proof verification result" }, "403": { "description": "Missing or invalid private invoice recovery secret" }, "410": { "description": "Original previously settled access token has expired and cannot be reissued" }, "4XX": { "description": "Settlement could not be verified" } } } }, "/v1/stats": { "get": { "operationId": "get_402proof_stats", "summary": "Read 402Proof-reported service statistics", "responses": { "200": { "description": "402Proof statistics returned by the service" } } } }, "/supported": { "get": { "operationId": "get_402proof_supported", "summary": "Read integration boundaries and configured payment rails", "responses": { "200": { "description": "Read integration boundaries and configured payment rails" }, "4XX": { "description": "Request or identifier not available" } }, "description": "Reports standard-x402 kinds only while the XRPL sidecar responds healthy and enabled; otherwise kinds empty. Other configured payment rails are the independent product-local invoice interface, not standard scheme offers." } }, "/health": { "get": { "operationId": "get_402proof_health", "summary": "Read configured networks and latest self-probe summary", "responses": { "200": { "description": "Read configured networks and latest self-probe summary" }, "4XX": { "description": "Request or identifier not available" } }, "description": "compliance_score is PASS/(PASS+FAIL) in the latest run and excludes blocked/no-data probes. It is not full probe coverage or independent certification." } }, "/v1/attestations": { "get": { "operationId": "get_402proof_attestations", "summary": "Read the hash-chained operator self-probe log", "responses": { "200": { "description": "Read the hash-chained operator self-probe log" }, "4XX": { "description": "Request or identifier not available" } }, "parameters": [ { "name": "n", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } } ], "description": "Returns records with probe_id, status, ts, run_id, expected and observed, plus chain_ok and total. PASS is an operator self-probe result, not an independent security audit. BLOCKED_NO_FUNDS and NO_DATA are not passes." } }, "/v1/attestations/{id}": { "get": { "operationId": "get_402proof_attestation", "summary": "Read one attestation by positive sequence number", "responses": { "200": { "description": "Read one attestation by positive sequence number" }, "4XX": { "description": "Request or identifier not available" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/receipt/{id}": { "get": { "operationId": "get_402proof_receipt", "summary": "Read a receipt by ID", "responses": { "200": { "description": "Read a receipt by ID" }, "4XX": { "description": "Request or identifier not available" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/leaderboard": { "get": { "operationId": "get_402proof_endpoints", "summary": "Read registered endpoint metadata", "responses": { "200": { "description": "Read registered endpoint metadata" }, "4XX": { "description": "Request or identifier not available" } } } }, "/verify": { "post": { "operationId": "verify_x402_v2_xrpl_exact", "summary": "Verify signed XRPL payment (no settlement)", "description": "This standard x402 v2 endpoint is strictly read-only and independently authenticated. Available only when the XRPL sidecar is configured and enabled. Requires signature, issuer, payee, amount, and any requested invoice binding to pass the official XRPL scheme.", "security": [ { "x402ResourceServerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "paymentPayload", "paymentRequirements" ], "properties": { "paymentPayload": { "type": "object", "description": "x402 v2 PaymentPayload, x402Version 2; XRPL exact payload.signedTxBlob signed by payer" }, "paymentRequirements": { "type": "object", "description": "Matching x402 v2 PaymentRequirements for xrpl:0 exact; must match accepted terms" } } } } } }, "responses": { "200": { "description": "x402 v2 VerifyResponse: isValid, payer, invalidReason if rejected" }, "401": { "description": "Unauthorized resource server" }, "503": { "description": "Standard x402 sidecar disabled, unavailable, or unhealthy" } } } }, "/settle": { "post": { "operationId": "settle_x402_v2_xrpl_exact", "summary": "Settle payer-signed XRPL transaction once", "description": "Requires an authenticated trusted resource server and live enabled sidecar. Re-verifies and submits the payer-signed transaction; protects against duplicate settlement via an exclusive persistent claim. Idempotent exact retries recover original confirmed result. Ambiguous broadcasts require XRPL reconciliation; no automatic resubmission.", "security": [ { "x402ResourceServerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "paymentPayload", "paymentRequirements" ], "properties": { "paymentPayload": { "type": "object", "description": "x402 v2 PaymentPayload, x402Version 2; XRPL exact payload.signedTxBlob signed by payer" }, "paymentRequirements": { "type": "object", "description": "Matching x402 v2 PaymentRequirements for xrpl:0 exact; must match accepted terms" } } } } } }, "responses": { "200": { "description": "Standard x402 v2 SettlementResponse (success only after validated on-chain settlement); or explicit failure" }, "401": { "description": "Unauthorized resource server" }, "503": { "description": "Standard settlement unavailable or indeterminate; reconcile on-chain" } } } } }, "externalDocs": { "description": "Public 402Proof hardening and attestation evidence", "url": "https://scriptmasterlabs.com/402proof-facilitator-attestations" }, "components": { "securitySchemes": { "x402ResourceServerBearer": { "type": "http", "scheme": "bearer", "description": "Server-issued resource-server secret (not a payer wallet token)." } } } }