{ "openapi": "3.1.0", "info": { "title": "ReceiptSure", "version": "0.1.0", "summary": "Deterministic Base transaction receipt verification against a declared intent, paid per call.", "description": "ReceiptSure is the other half of a transaction preflight: not what a transaction will do, but what it actually did. It fetches the receipt, decodes every Transfer, TransferSingle, TransferBatch and Approval log, and holds them against the transfers the caller said they intended — reporting each one as matched, missing or short, with the shortfall quantified in base units and in display units where the token's decimals are readable. It catches the cases a status code hides: a revert whose reason the receipt does not carry, a transaction that succeeded while moving nothing, a token that skimmed a fee on the way through, and funds leaving a declared sender for an address nobody named. There is no model anywhere in it, and a receipt it cannot read comes back as unknown rather than as approval.", "contact": { "email": "support@schemasure.com" }, "x-policy-version": "2026-09-19" }, "servers": [ { "url": "https://receipt.schemasure.com" } ], "paths": { "/v1/tx/receipt-verify": { "post": { "operationId": "receiptsure_v1_tx_receipt_verify", "summary": "Verify what a Base transaction actually did against the intent you declared", "description": "Check whether a mined Base transaction did what your agent meant it to do. Fetches the receipt, decodes its ERC-20, ERC-721 and ERC-1155 transfer and approval logs, and reports each declared movement as matched, missing or short, with the observed amount beside the expected one. Catches reverts, success with no effect, fee-on-transfer skims and transfers to recipients you never named. Returns unknown rather than guessing. Not a guarantee that a transaction was safe.", "x-payment-info": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amountAtomic": "10000", "priceUsd": 0.01, "payTo": "0x9876af0F6D8Ed5155Cd02d1ca56D128601612690", "policy": "charge only on a successful, usable result" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ReceiptVerifyRequest", "type": "object", "additionalProperties": false, "required": [ "tx_hash", "expected_transfers" ], "description": "A mined Base transaction plus the movements you meant it to make. Both are required: with no declared intent there is nothing for a receipt to agree or disagree with.", "properties": { "tx_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "description": "The Base transaction to check. A hash with no receipt yet answers unknown." }, "expected_transfers": { "type": "array", "minItems": 1, "maxItems": 32, "description": "What you intended to move. Each entry is checked against the decoded logs and reported as matched, missing, short, or unverifiable.", "items": { "type": "object", "additionalProperties": false, "required": [ "to", "amount" ], "properties": { "asset": { "type": [ "string", "null" ], "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Token contract. Omit or null for native ETH, which emits no log and is therefore reported unverifiable rather than matched." }, "asset_kind": { "type": "string", "enum": [ "native", "erc20", "erc721", "erc1155", "unknown" ], "description": "Optional. Inferred from asset and token_id when absent." }, "from": { "type": [ "string", "null" ], "pattern": "^0x[0-9a-fA-F]{40}$", "description": "The sender, when you know it. Naming it is what lets undeclared recipients be judged: outflows are only held against you when they leave the account that signed the transaction, or leave a declared sender in the asset you said it would send." }, "to": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "The intended recipient." }, "amount": { "type": "string", "pattern": "^[0-9]+$", "description": "Base units, not display units: 1 USDC is \"1000000\". Must be above zero." }, "token_id": { "type": [ "string", "null" ], "pattern": "^[0-9]+$", "description": "ERC-721 or ERC-1155 token id, when the movement names one." } } } } } }, "example": { "tx_hash": "0x7f1c3a58e0b94d26c5af7318d0e42b96c1d85f0a3b72e648d9c05147ae2b6f30", "expected_transfers": [ { "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "from": "0x9F2C5E4A8db1C3a7E6B0d4f8C1E2a5b7D9C0e3F4", "to": "0x5d3e1a9b7c2f4e8a0b6d3c5f9e1a7b4d2c8f0a6e", "amount": "10000" } ] } } } }, "responses": { "200": { "description": "Successful result envelope", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ReceiptVerifyEnvelope", "type": "object", "required": [ "ok", "verdict", "confidence", "risk_codes", "evidence", "result", "policy_version", "request_hash", "data_versions", "warnings" ], "properties": { "ok": { "type": "boolean" }, "verdict": { "type": "string", "enum": [ "allow", "warn", "block", "unknown" ], "description": "allow means every declared movement happened exactly as declared. Precedence: block, then unknown, then warn, then allow." }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "risk_codes": { "type": "array", "items": { "type": "string" } }, "evidence": { "type": "array", "items": { "type": "object" } }, "policy_version": { "type": "string" }, "request_hash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }, "warnings": { "type": "array", "items": { "type": "string" } }, "data_versions": { "type": "object", "required": [ "denylist", "event_abis", "policy", "chain" ] }, "result": { "type": "object", "required": [ "tx_hash", "chain", "receipt", "revert", "effect", "expected_transfers", "transfer_checks", "observed_transfers", "observed_approvals", "fee_on_transfer", "unexpected_recipients", "denylist_hits", "tokens", "unresolved", "rpc" ], "properties": { "receipt": { "type": "object", "required": [ "status", "log_count", "detail" ], "properties": { "status": { "type": "string", "enum": [ "success", "reverted", "unknown", "not_mined", "unavailable" ], "description": "not_mined is a real answer from a node that has no receipt. unavailable means no node answered, which the paid route returns as an error rather than charging for." } } }, "revert": { "type": "object", "required": [ "reverted", "reason", "kind", "detail" ], "properties": { "kind": { "type": [ "string", "null" ], "enum": [ "error_string", "panic", "empty", "unknown", null ], "description": "unknown when the receipt carries no revert data. Never inferred." } } }, "transfer_checks": { "type": "array", "items": { "type": "object", "required": [ "expected", "status", "detail" ], "properties": { "status": { "type": "string", "enum": [ "matched", "amount_mismatch", "missing", "unverifiable" ] } } } } } } } }, "example": { "ok": true, "verdict": "block", "confidence": 1, "risk_codes": [ "AMOUNT_MISMATCH", "FEE_ON_TRANSFER_SKIM" ], "evidence": [ { "code": "AMOUNT_MISMATCH", "severity": "critical", "detail": "0x5D3e1a9b7c2f4E8A0b6d3c5F9E1A7b4D2C8f0a6E received 9900 base units, short of the declared 10000 by 100 base units.", "source": "intent-match", "data": { "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "to": "0x5D3e1a9b7c2f4E8A0b6d3c5F9E1A7b4D2C8f0a6E", "expected_base_units": "10000", "observed_base_units": "9900", "delta_base_units": "-100", "shortfall_base_units": "100", "shortfall_display": null, "decimals": null, "symbol": null } }, { "code": "FEE_ON_TRANSFER_SKIM", "severity": "medium", "detail": "0x9f2C5E4a8DB1C3A7e6b0d4f8C1e2A5b7d9c0E3f4 sent 10000 base units of 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 but 0x5D3e1a9b7c2f4E8A0b6d3c5F9E1A7b4D2C8f0a6E received 9900. The missing 100 (1.00%) went to 1 other address(es) in the same transfer chain, which is the signature of a fee-on-transfer token.", "source": "skim", "data": { "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "from": "0x9f2C5E4a8DB1C3A7e6b0d4f8C1e2A5b7d9c0E3f4", "to": "0x5D3e1a9b7c2f4E8A0b6d3c5F9E1A7b4D2C8f0a6E", "sent_base_units": "10000", "received_base_units": "9900", "skimmed_base_units": "100", "implied_fee_bps": 100, "plausible_fee_ceiling_bps": 1000, "other_recipients": [ { "to": "0x4CbE9fd4a2B7c0e1D8f3A6b9C2E5d8F1A4B7C0e3", "amount": "100" } ] } } ], "result": { "tx_hash": "0x7f1c3a58e0b94d26c5af7318d0e42b96c1d85f0a3b72e648d9c05147ae2b6f30", "chain": "eip155:8453", "receipt": { "status": "success", "block_number": "0x1f4a2c0", "transaction_index": 12, "gas_used": "0xd6d8", "from": "0x9F2C5E4A8db1C3a7E6B0d4f8C1E2a5b7D9C0e3F4", "to": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "contract_address": null, "log_count": 2, "detail": "mined in block 0x1f4a2c0 with status 1 and 2 log(s)" }, "revert": { "reverted": false, "reason": null, "kind": null, "raw": null, "detail": "the receipt reports status 1, so the transaction was applied" }, "effect": { "has_logs": true, "decoded_logs": 2, "undecodable_logs": 0, "unrelated_logs": 0, "silent_success": false, "detail": "2 log(s): 2 transfer(s), 0 approval(s), 0 unrelated event(s), 0 that did not decode" }, "expected_transfers": [ { "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "asset_kind": "erc20", "from": "0x9f2C5E4a8DB1C3A7e6b0d4f8C1e2A5b7d9c0E3f4", "to": "0x5D3e1a9b7c2f4E8A0b6d3c5F9E1A7b4D2C8f0a6E", "amount": "10000", "token_id": null } ], "transfer_checks": [ { "expected": { "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "asset_kind": "erc20", "from": "0x9f2C5E4a8DB1C3A7e6b0d4f8C1e2A5b7d9c0E3f4", "to": "0x5D3e1a9b7c2f4E8A0b6d3c5F9E1A7b4D2C8f0a6E", "amount": "10000", "token_id": null }, "status": "amount_mismatch", "amounts": { "expected_base_units": "10000", "observed_base_units": "9900", "delta_base_units": "-100", "shortfall_base_units": "100", "decimals": null, "symbol": null, "expected_display": null, "observed_display": null, "shortfall_display": null }, "matched_log_indexes": [ 0 ], "detail": "0x5D3e1a9b7c2f4E8A0b6d3c5F9E1A7b4D2C8f0a6E received 9900 base units, short of the declared 10000 by 100 base units." } ], "observed_transfers": [ { "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "asset_kind": "erc20", "event": "Transfer", "from": "0x9f2C5E4a8DB1C3A7e6b0d4f8C1e2A5b7d9c0E3f4", "to": "0x5D3e1a9b7c2f4E8A0b6d3c5F9E1A7b4D2C8f0a6E", "amount": "9900", "token_id": null, "operator": null, "log_index": 0 }, { "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "asset_kind": "erc20", "event": "Transfer", "from": "0x9f2C5E4a8DB1C3A7e6b0d4f8C1e2A5b7d9c0E3f4", "to": "0x4CbE9fd4a2B7c0e1D8f3A6b9C2E5d8F1A4B7C0e3", "amount": "100", "token_id": null, "operator": null, "log_index": 1 } ], "observed_approvals": [], "fee_on_transfer": [ { "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "from": "0x9f2C5E4a8DB1C3A7e6b0d4f8C1e2A5b7d9c0E3f4", "to": "0x5D3e1a9b7c2f4E8A0b6d3c5F9E1A7b4D2C8f0a6E", "sent_base_units": "10000", "received_base_units": "9900", "skimmed_base_units": "100", "implied_fee_bps": 100, "implied_fee_percent": "1.00%", "skimmed_display": null, "plausible_fee": true, "other_recipients": [ { "to": "0x4CbE9fd4a2B7c0e1D8f3A6b9C2E5d8F1A4B7C0e3", "amount": "100" } ], "detail": "0x9f2C5E4a8DB1C3A7e6b0d4f8C1e2A5b7d9c0E3f4 sent 10000 base units of 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 but 0x5D3e1a9b7c2f4E8A0b6d3c5F9E1A7b4D2C8f0a6E received 9900. The missing 100 (1.00%) went to 1 other address(es) in the same transfer chain, which is the signature of a fee-on-transfer token." } ], "unexpected_recipients": [], "denylist_hits": [], "tokens": [ { "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "symbol": null, "decimals": null, "detail": "no RPC configured, so token metadata could not be read" } ], "unresolved": [], "rpc": { "receipts_configured": true, "reads_configured": false, "detail": "receipts are read from the configured Base endpoints; token metadata is best-effort and never changes a verdict" } }, "policy_version": "2026-09-19", "request_hash": "sha256:50864960b295fd6c1d41ddf29b9da8397286701a16480b7184a14444f0ecf1d3", "data_versions": { "denylist": "2026-08-03.1", "event_abis": "2026-09-19.1", "policy": "2026-09-19", "chain": "eip155:8453", "fee_plausibility_bps": "1000" }, "warnings": [ "No Base RPC endpoint is configured for token reads, so symbols and decimals are absent and every amount is reported in base units only. This affects presentation, never a verdict." ] } } } }, "400": { "description": "INPUT_INVALID", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "402": { "description": "Payment required. Body carries the x402 challenge; see PAYMENT-REQUIRED header.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "422": { "description": "UNSUPPORTED or INDETERMINATE. Not charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "502": { "description": "Upstream or facilitator unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "504": { "description": "UPSTREAM_TIMEOUT", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } } }, "components": { "schemas": { "Error": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }