{ "openapi": "3.1.0", "info": { "title": "LupaRiel paid APIs", "version": "1.8.0", "description": "Pay-per-call x402 APIs: catalog lookup (SKU#2 $0.005; SKU#5 $0.01 when status is present), AR settle-readiness condition, AR rail matrix (SKU#9), catalog URL liveness (SKU#14), auth-capture hold brief (SKU#16), settle receipt (SKU#17), Mandato AR mandate scope (SKU#19), and live auth-capture HOLD (SKU#21). HTML and static /rieles.json /catalog.json stay free. Lookup never dumps the catalog. status alone is not a valid lookup query. Settle-ready, rail-matrix, liveness, reserve-brief, settle-receipt, mandate-scope and reserve-hold are explicit LupaRiel rulesets, not oracles. Liveness probes only catalog-resolved URLs. Reserve-brief is informational only (no on-chain hold; wire scheme exact). Reserve-hold is on-chain escrow authorize (wire scheme auth-capture, NOT exact); HTTP 200 is HOLD, settlement truth is checkout COMPLETED. Settle-receipt is informational tx attestation (settle \u2260 consent; not a Basescan re-oracle). Mandate-scope verifies a signed Intent Mandate v0.1.0 against a proposed spend (does not create or sign).", "x-guidance": "Call GET /api/lookup?q=&rail=x402|ap2|acp|mpp&limit=5 without auth to receive HTTP 402 + PAYMENT-REQUIRED ($0.005 USDC Base, amount 5000). Call GET /api/lookup?rail=x402&status=produccion&limit=5 (SKU#5 x402-live) for HTTP 402 amount 10000 ($0.01). status alone \u2192 400 missing_query. Call GET /api/condition/settle-ready?rail=mercado_pago&wants_usdc_settle=true without auth for HTTP 402 ($0.02 USDC Base, amount 20000). Call GET /api/rail/matrix?case=m2m_usdc without auth for HTTP 402 ($0.01 USDC Base, amount 10000). Call POST /api/liveness with JSON { ids: string[] } (1\u201310) without auth for HTTP 402 ($0.02 USDC Base, amount 20000). GET /api/liveness \u2192 405. Empty or >10 ids \u2192 400 before payment. Call GET /api/reserve/brief?resource= without auth for HTTP 402 ($0.01 USDC Base, amount 10000). Missing or non-http(s) resource \u2192 400 before payment. Call GET /api/settle/receipt?tx=<0x+64hex> without auth for HTTP 402 ($0.01 USDC Base, amount 10000). Missing or invalid tx \u2192 400 before payment. Call GET /api/mandate/scope?resource=&price_usdc=0.02&mandate= without auth for HTTP 402 ($0.02 USDC Base, amount 20000). Missing or invalid required query \u2192 400 before payment. Retry with PAYMENT-SIGNATURE (x402 v2 Exact, eip155:8453). Invalid or missing required query params \u2192 400 { error, hint }. Call GET /api/reserve/hold without auth (no required query) for HTTP 402 ($0.05 USDC Base, amount 50000, scheme auth-capture NOT exact). Poll: GET /api/reserve/hold?checkoutId=. Refund: POST /api/reserve/hold/{holdId}/refund. Retry hold with PAYMENT-SIGNATURE using AuthCaptureEvmScheme (not exact).", "contact": { "name": "LupaRiel", "url": "https://lupariel.com", "email": "mswitach@gmail.com" } }, "servers": [ { "url": "https://lupariel.com", "description": "Production" } ], "paths": { "/api/lookup": { "get": { "operationId": "lookupFichas", "summary": "Catalog lookup (x402 paid)", "description": "Returns a small JSON match list after x402 payment. Unpaid requests receive HTTP 402. Missing q and rail receive HTTP 400 \u2014 status alone is not enough (avoids enumeration). q/rail without status stays SKU#2 at $0.005 (amount 5000). When status is present (SKU#5 x402-live, including ?rail=x402&status=produccion) the quote is $0.01 (amount 10000). Filter matches fichas whose status equals the value OR whose statuses[] includes it.", "tags": [ "catalog", "lookup", "x402", "x402-live" ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Free-text match on name, slug, tags, one_liner, category", "schema": { "type": "string", "example": "x402" } }, { "name": "rail", "in": "query", "required": false, "description": "Filter by agentic payment rail", "schema": { "type": "string", "enum": [ "x402", "ap2", "acp", "mpp" ], "example": "x402" } }, { "name": "status", "in": "query", "required": false, "description": "Filter fichas whose status equals this value or whose statuses[] includes it. Allowed: produccion|piloto|anunciado. status alone is not a valid query (400 missing_query). When present, price is $0.01 (atomic 10000) instead of $0.005 (5000). Marketplace smoke: ?rail=x402&status=produccion&limit=5", "schema": { "type": "string", "enum": [ "produccion", "piloto", "anunciado" ], "example": "produccion" } }, { "name": "limit", "in": "query", "required": false, "description": "Max matches (default 5, max 20)", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 5, "example": 3 } } ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.005" }, "priceWhenStatus": { "mode": "fixed", "currency": "USD", "amount": "0.01", "atomic": "10000", "when": "status query param present (SKU#5 x402-live). Smoke: GET /api/lookup?rail=x402&status=produccion&limit=5" }, "protocols": [ { "x402": {} } ], "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }, "responses": { "200": { "description": "Paid \u2014 small match list (never the full catalog)", "content": { "application/json": { "schema": { "type": "object", "required": [ "query", "count", "matches" ], "properties": { "query": { "type": "object", "properties": { "q": { "type": "string" }, "rail": { "type": "string", "enum": [ "x402", "ap2", "acp", "mpp", "" ] }, "status": { "type": "string", "enum": [ "produccion", "piloto", "anunciado", "" ] }, "limit": { "type": "integer" } } }, "count": { "type": "integer" }, "matches": { "type": "array", "items": { "type": "object", "required": [ "slug", "name", "rails", "category", "status", "ficha_url" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "rails": { "type": "array", "items": { "type": "string", "enum": [ "x402", "ap2", "acp", "mpp" ] } }, "role": { "type": "string" }, "category": { "type": "string" }, "status": { "type": "string" }, "statuses": { "type": "array", "items": { "type": "string" } }, "one_liner": { "type": "string" }, "url": { "type": "string" }, "ficha_url": { "type": "string" } } } } } } } } }, "400": { "description": "missing_query, unsupported_rail, or unsupported_status" }, "402": { "description": "Payment Required \u2014 x402 v2 Exact on Base (eip155:8453). $0.005 (amount 5000) without status; $0.01 (amount 10000) when status is present (SKU#5). See PAYMENT-REQUIRED header and extensions.bazaar." }, "503": { "description": "pay_to_unconfigured" } } } }, "/api/condition/settle-ready": { "get": { "operationId": "settleReadyCondition", "summary": "AR settle-readiness condition (x402 paid)", "description": "Returns ar-settle-ready-v1 verdict after x402 payment: whether USDC settle is ready vs a fiat consent hop. Unpaid requests receive HTTP 402. Missing rail or wants_usdc_settle receive HTTP 400. Explicit LupaRiel rules \u2014 not an oracle. has_mp_consent / has_card_auth never flip settle_ready on fiat rails.", "tags": [ "condition", "settle-ready", "x402" ], "parameters": [ { "name": "rail", "in": "query", "required": true, "description": "Payment rail under evaluation", "schema": { "type": "string", "enum": [ "x402", "mercado_pago", "cards", "ap2", "acp", "mpp" ], "example": "mercado_pago" } }, { "name": "wants_usdc_settle", "in": "query", "required": true, "description": "Whether the caller wants USDC settle on Base (true|false, case-insensitive)", "schema": { "type": "string", "enum": [ "true", "false" ], "example": "true" } }, { "name": "has_mp_consent", "in": "query", "required": false, "description": "Mercado Pago consent flag. Default false. Does not flip settle_ready.", "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false" } }, { "name": "has_card_auth", "in": "query", "required": false, "description": "Card authorization flag. Default false. Does not flip settle_ready.", "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false" } }, { "name": "psp", "in": "query", "required": false, "description": "Informative PSP slug only \u2014 echoed in query, does not affect rules", "schema": { "type": "string", "example": "mercado-pago" } } ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.02" }, "protocols": [ { "x402": {} } ], "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }, "responses": { "200": { "description": "Paid \u2014 ar-settle-ready-v1 verdict (never a catalog or fee dump)", "content": { "application/json": { "schema": { "type": "object", "required": [ "settle_ready", "reasons", "hop", "ruleset", "disclaimer" ], "properties": { "settle_ready": { "type": "boolean" }, "reasons": { "type": "array", "items": { "type": "string" } }, "hop": { "type": "string", "enum": [ "mercado_pago", "cards", "none" ] }, "ruleset": { "type": "string", "const": "ar-settle-ready-v1" }, "disclaimer": { "type": "string" }, "query": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "x402", "mercado_pago", "cards", "ap2", "acp", "mpp" ] }, "wants_usdc_settle": { "type": "boolean" }, "has_mp_consent": { "type": "boolean" }, "has_card_auth": { "type": "boolean" }, "psp": { "type": "string" } } } }, "example": { "settle_ready": false, "reasons": [ "Fiat consent/auth \u2260 USDC settle", "Falta puente stable/PSP o riel x402." ], "hop": "mercado_pago", "ruleset": "ar-settle-ready-v1", "disclaimer": "Reglas expl\u00edcitas LupaRiel; no es or\u00e1culo ni consejo legal." } } } } }, "400": { "description": "missing_rail, missing_wants_usdc_settle, unsupported_rail, or invalid bool" }, "402": { "description": "Payment Required \u2014 x402 v2 Exact $0.02 USDC on Base (eip155:8453, amount 20000). See PAYMENT-REQUIRED header and extensions.bazaar." }, "503": { "description": "pay_to_unconfigured" } } } }, "/api/rail/matrix": { "get": { "operationId": "railMatrix", "summary": "AR rail matrix (x402 paid)", "description": "Returns ar-rail-matrix-v1 after x402 payment: which of x402 / AP2 / ACP / MPP applies for m2m USDC settle, fiat consent, or checkout. Lock: settle \u2260 consent. Unpaid requests receive HTTP 402. Invalid case receives HTTP 400. Explicit LupaRiel rules \u2014 not an oracle. Always four rails.", "tags": [ "rail-matrix", "x402", "ap2", "acp", "mpp" ], "parameters": [ { "name": "case", "in": "query", "required": false, "description": "Decision case. Default m2m_usdc. Invalid value \u2192 400 { error, hint }.", "schema": { "type": "string", "enum": [ "m2m_usdc", "fiat_consent", "checkout" ], "default": "m2m_usdc", "example": "m2m_usdc" } } ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.01" }, "protocols": [ { "x402": {} } ], "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }, "responses": { "200": { "description": "Paid \u2014 ar-rail-matrix-v1 (never a catalog or fee dump)", "content": { "application/json": { "schema": { "type": "object", "required": [ "product", "kind", "case", "lock", "rails" ], "properties": { "product": { "type": "string", "const": "LupaRiel" }, "kind": { "type": "string", "const": "rail_matrix" }, "case": { "type": "string", "enum": [ "m2m_usdc", "fiat_consent", "checkout" ] }, "lock": { "type": "string", "const": "settle_ne_consent" }, "ruleset": { "type": "string", "const": "ar-rail-matrix-v1" }, "rails": { "type": "array", "minItems": 4, "maxItems": 4, "items": { "type": "object", "required": [ "rail", "applies", "role", "needs_ars_fiat_hop", "hub_url", "why" ], "properties": { "rail": { "type": "string", "enum": [ "x402", "ap2", "acp", "mpp" ] }, "applies": { "type": "boolean" }, "role": { "type": "string", "enum": [ "settle", "mandate", "checkout", "card_mpp" ] }, "needs_ars_fiat_hop": { "type": "boolean" }, "hub_url": { "type": "object", "required": [ "es", "en" ], "properties": { "es": { "type": "string", "format": "uri" }, "en": { "type": "string", "format": "uri" } } }, "why": { "type": "string", "description": "One-line Spanish rationale from hub copy" } } } } }, "example": { "product": "LupaRiel", "kind": "rail_matrix", "case": "m2m_usdc", "lock": "settle_ne_consent", "ruleset": "ar-rail-matrix-v1", "rails": [ { "rail": "x402", "applies": true, "role": "settle", "needs_ars_fiat_hop": false, "hub_url": { "es": "https://lupariel.com/x402/", "en": "https://lupariel.com/en/agentic-payment-rails/" }, "why": "Pago por request HTTP 402 Exact+USDC: settle nativo, sin hop ARS." } ] } } } } }, "400": { "description": "invalid_case" }, "402": { "description": "Payment Required \u2014 x402 v2 Exact $0.01 USDC on Base (eip155:8453, amount 10000). See PAYMENT-REQUIRED header and extensions.bazaar." }, "503": { "description": "pay_to_unconfigured" } } } }, "/api/liveness": { "post": { "operationId": "livenessCheck", "summary": "Catalog URL liveness (x402 paid)", "description": "Returns riel-liveness-v1 after x402 payment: per-id reachability of LupaRiel catalog URLs (ficha slug / plaza_id / canonical endpoint URL). Unpaid requests receive HTTP 402. Missing body, empty ids, or more than 10 ids receive HTTP 400 before payment. Unknown ids are live:false and are never fetched (SSRF-safe). GET is 405. Checks catalog URLs only \u2014 not advice.", "tags": [ "liveness", "x402", "catalog" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "string" }, "description": "Ficha slug, plaza_id, or canonical catalog endpoint URL. Cap 10.", "example": [ "lupapago-consent-hop", "lupaplaza-plaza-discover", "lupaplaza-plaza-probe", "lupariel-rail-matrix", "lupapago-psp-recommend" ] } } } } } }, "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.02" }, "protocols": [ { "x402": {} } ], "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }, "responses": { "200": { "description": "Paid \u2014 riel-liveness-v1 (never a catalog or fee dump)", "content": { "application/json": { "schema": { "type": "object", "required": [ "product", "kind", "ruleset", "results", "count", "disclaimer" ], "properties": { "product": { "type": "string", "const": "LupaRiel" }, "kind": { "type": "string", "const": "liveness" }, "ruleset": { "type": "string", "const": "riel-liveness-v1" }, "results": { "type": "array", "items": { "type": "object", "required": [ "id", "live", "http_status", "is_402", "notes" ], "properties": { "id": { "type": "string" }, "live": { "type": "boolean" }, "http_status": { "type": "integer" }, "is_402": { "type": "boolean" }, "notes": { "type": "string" } } } }, "count": { "type": "integer" }, "disclaimer": { "type": "string" } }, "example": { "product": "LupaRiel", "kind": "liveness", "ruleset": "riel-liveness-v1", "results": [ { "id": "lupapago-consent-hop", "live": true, "http_status": 402, "is_402": true, "notes": "HTTP 402 Payment Required" } ], "count": 1, "disclaimer": "Checks LupaRiel catalog URLs; no es asesoramiento." } } } } }, "400": { "description": "missing_body, invalid_json, missing_ids, empty_ids, invalid_ids, or too_many_ids" }, "402": { "description": "Payment Required \u2014 x402 v2 Exact $0.02 USDC on Base (eip155:8453, amount 20000). See PAYMENT-REQUIRED header and extensions.bazaar." }, "405": { "description": "method_not_allowed \u2014 POST only" }, "503": { "description": "pay_to_unconfigured" } } } }, "/api/reserve/brief": { "get": { "operationId": "reserveBrief", "summary": "Auth-capture hold brief (x402 paid)", "description": "Returns x402-auth-capture-brief-v1 after x402 payment: an informational auth-capture hold brief for a resource URL (authorize \u2192 capture|void|reclaim|refund). Unpaid requests receive HTTP 402. Missing resource or a value that is not an http(s) URL receives HTTP 400 before payment. Not-indexed resources still get a generic brief (never 404). Does not execute on-chain hold, EIP-3009 authorize, or write reservation state.", "tags": [ "reserve-brief", "auth-capture", "x402" ], "parameters": [ { "name": "resource", "in": "query", "required": true, "description": "Target http(s) URL to brief. Marketplace smoke: lupapago.com/api/fee/quote?psp=mobbex&amount=50000&cuotas=3", "schema": { "type": "string", "format": "uri", "example": "https://lupapago.com/api/fee/quote?psp=mobbex&amount=50000&cuotas=3" } }, { "name": "amount", "in": "query", "required": false, "description": "Hold amount as a positive decimal string. Default 0.10. Informational \u2014 not the SKU price ($0.01).", "schema": { "type": "string", "default": "0.10", "example": "0.10" } }, { "name": "asset", "in": "query", "required": false, "description": "Hold asset symbol. Default USDC.", "schema": { "type": "string", "default": "USDC", "example": "USDC" } }, { "name": "network", "in": "query", "required": false, "description": "Hold network CAIP-2. Default eip155:8453.", "schema": { "type": "string", "default": "eip155:8453", "example": "eip155:8453" } }, { "name": "lang", "in": "query", "required": false, "description": "Copy language for flow/summary. Default es.", "schema": { "type": "string", "enum": [ "es", "en" ], "default": "es", "example": "es" } } ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.01" }, "protocols": [ { "x402": {} } ], "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }, "responses": { "200": { "description": "Paid \u2014 x402-auth-capture-brief-v1 (informational; never an on-chain hold)", "content": { "application/json": { "schema": { "type": "object", "required": [ "scheme", "resource", "network", "asset", "amount", "flow", "autoCapture", "deadlines", "settlementTruth", "notInventory", "summary", "ruleset", "examples" ], "properties": { "product": { "type": "string", "const": "LupaRiel" }, "kind": { "type": "string", "const": "reserve-brief" }, "scheme": { "type": "string", "const": "auth-capture" }, "resource": { "type": "string", "format": "uri" }, "network": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "flow": { "type": "object", "required": [ "phases", "authorize", "capture", "void", "reclaim", "refund" ], "properties": { "phases": { "type": "array", "items": { "type": "string" } }, "authorize": { "type": "string" }, "capture": { "type": "string" }, "void": { "type": "string" }, "reclaim": { "type": "string" }, "refund": { "type": "string" } } }, "autoCapture": { "type": "boolean", "const": false }, "deadlines": { "type": "object", "required": [ "captureDeadline", "refundDeadline" ], "properties": { "captureDeadline": { "type": "null" }, "refundDeadline": { "type": "null" } } }, "settlementTruth": { "type": "string" }, "notInventory": { "type": "boolean", "const": true }, "summary": { "type": "string" }, "ruleset": { "type": "string", "const": "x402-auth-capture-brief-v1" }, "examples": { "type": "object", "required": [ "holdThenCapture", "holdThenVoid", "holdExpireReclaim" ], "properties": { "holdThenCapture": { "type": "string" }, "holdThenVoid": { "type": "string" }, "holdExpireReclaim": { "type": "string" } } }, "disclaimer": { "type": "string" }, "briefed_at": { "type": "string", "format": "date-time" } }, "example": { "scheme": "auth-capture", "resource": "https://lupapago.com/api/fee/quote?psp=mobbex&amount=50000&cuotas=3", "network": "eip155:8453", "asset": "USDC", "amount": "0.10", "flow": { "phases": [ "authorize", "capture", "void", "reclaim", "refund" ], "authorize": "Autoriza / retiene el monto (hold). No transfiere inventario ni completa el settle.", "capture": "Captura el monto retenido tras cumplir. El settle real es COMPLETED (o el status de sesi\u00f3n), no el HTTP 200 del authorize.", "void": "Libera el hold sin capturar (cancelaci\u00f3n del vendedor).", "reclaim": "El comprador reclama el hold si expir\u00f3 sin capture ni void.", "refund": "Reembolso despu\u00e9s de un capture." }, "autoCapture": false, "deadlines": { "captureDeadline": null, "refundDeadline": null }, "settlementTruth": "COMPLETED (o status de sesi\u00f3n), no el HTTP 200 del authorize", "notInventory": true, "summary": "Reserva fondos, no inventario. Hold \u2192 capture|void|reclaim|refund.", "ruleset": "x402-auth-capture-brief-v1", "examples": { "holdThenCapture": "authorize 0.10 USDC \u2192 fulfill \u2192 capture", "holdThenVoid": "authorize \u2192 cancel \u2192 void", "holdExpireReclaim": "authorize \u2192 timeout \u2192 reclaim" } } } } } }, "400": { "description": "missing_resource, invalid_resource, invalid_amount, or invalid_lang" }, "402": { "description": "Payment Required \u2014 x402 v2 Exact $0.01 USDC on Base (eip155:8453, amount 10000). See PAYMENT-REQUIRED header and extensions.bazaar." }, "503": { "description": "pay_to_unconfigured" } } } }, "/api/settle/receipt": { "get": { "operationId": "settleReceipt", "summary": "Settle receipt / tx attestation (x402 paid)", "description": "Returns settle-receipt-v1 after x402 payment: an informational post-settle attestation of a tx hash (proof settle \u2260 consent). Unpaid requests receive HTTP 402. Missing tx or a value that is not 0x + 64 hex receives HTTP 400 before payment. Does not invent on-chain status, query Basescan, or act as a consent/payment-plan condition (that is settle-ready / consent-hop). settled=true attests this paid response, not a mandatory Basescan re-oracle.", "tags": [ "settle-receipt", "settle", "x402" ], "parameters": [ { "name": "tx", "in": "query", "required": true, "description": "Settle transaction hash (0x + 64 hex). Marketplace smoke: 0x6ec312ffab72460da6fae791711471a80b6375e0c89ccf1a509f73249caea14b", "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{64}$", "example": "0x6ec312ffab72460da6fae791711471a80b6375e0c89ccf1a509f73249caea14b" } }, { "name": "resource", "in": "query", "required": false, "description": "Optional http(s) URL to echo. Not fetched.", "schema": { "type": "string", "format": "uri" } }, { "name": "lang", "in": "query", "required": false, "description": "Copy language for summary. Echoed when provided.", "schema": { "type": "string", "enum": [ "es", "en" ], "example": "es" } } ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.01" }, "protocols": [ { "x402": {} } ], "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }, "responses": { "200": { "description": "Paid \u2014 settle-receipt-v1 (informational attestation; never a Basescan re-oracle)", "content": { "application/json": { "schema": { "type": "object", "required": [ "product", "kind", "ruleset", "tx", "network", "asset", "settled", "settle_vs_consent", "summary", "disclaimer", "attested_at" ], "properties": { "product": { "type": "string", "const": "LupaRiel" }, "kind": { "type": "string", "const": "settle-receipt" }, "ruleset": { "type": "string", "const": "settle-receipt-v1" }, "tx": { "type": "string", "pattern": "^0x[a-fA-F0-9]{64}$" }, "network": { "type": "string", "const": "eip155:8453" }, "asset": { "type": "string", "const": "USDC" }, "settled": { "type": "boolean", "const": true }, "settle_vs_consent": { "type": "object", "required": [ "settle", "consent" ], "properties": { "settle": { "type": "string", "const": "on-chain Exact USDC Base" }, "consent": { "type": "string", "const": "fiat/OAuth/3DS hop \u2014 NOT this endpoint" } } }, "summary": { "type": "string" }, "disclaimer": { "type": "string" }, "attested_at": { "type": "string", "format": "date-time" }, "resource": { "type": "string", "format": "uri" }, "lang": { "type": "string", "enum": [ "es", "en" ] } }, "example": { "product": "LupaRiel", "kind": "settle-receipt", "ruleset": "settle-receipt-v1", "tx": "0x6ec312ffab72460da6fae791711471a80b6375e0c89ccf1a509f73249caea14b", "network": "eip155:8453", "asset": "USDC", "settled": true, "settle_vs_consent": { "settle": "on-chain Exact USDC Base", "consent": "fiat/OAuth/3DS hop \u2014 NOT this endpoint" }, "summary": "Atestaci\u00f3n informativa del settle on-chain Exact USDC en Base. No es consentimiento fiat ni un hop OAuth/3DS.", "disclaimer": "Not a consent hop or payment-plan condition. Informational settle attestation only. settled=true attests this paid response, not a Basescan re-oracle.", "attested_at": "2026-09-23T00:00:00.000Z", "lang": "es" } } } } }, "400": { "description": "missing_tx, invalid_tx, invalid_resource, or invalid_lang" }, "402": { "description": "Payment Required \u2014 x402 v2 Exact $0.01 USDC on Base (eip155:8453, amount 10000). See PAYMENT-REQUIRED header and extensions.bazaar." }, "503": { "description": "pay_to_unconfigured" } } } }, "/api/mandate/scope": { "get": { "operationId": "mandateScope", "summary": "Mandato AR Intent Mandate scope (x402 paid)", "description": "Returns mandate-scope-v1 after x402 payment: verification of a signed Intent Mandate v0.1.0 (Mandato AR) against a proposed spend (resource + price_usdc). Unpaid requests receive HTTP 402. Missing or invalid resource, price_usdc, or mandate receive HTTP 400 before payment. Failed checks stay HTTP 200 with ok:false (do not re-402). Does not create or sign a mandate.", "tags": [ "mandate-scope", "mandate", "x402" ], "parameters": [ { "name": "resource", "in": "query", "required": true, "description": "Absolute http(s) URL of the proposed spend. Marketplace smoke: https://lupariel.com/api/settle/receipt", "schema": { "type": "string", "format": "uri", "example": "https://lupariel.com/api/settle/receipt" } }, { "name": "price_usdc", "in": "query", "required": true, "description": "Proposed spend as a decimal USDC string.", "schema": { "type": "string", "example": "0.02" } }, { "name": "mandate", "in": "query", "required": true, "description": "base64url JSON Intent Mandate v0.1.0 (github.com/mswitach/mandato-ar packages/mandate).", "schema": { "type": "string" } }, { "name": "spent_usdc", "in": "query", "required": false, "description": "Already-spent USDC decimal. Default 0.", "schema": { "type": "string", "default": "0", "example": "0" } }, { "name": "pubkey", "in": "query", "required": false, "description": "ed25519 public key hex. Required when mandate.signature starts with ed25519:.", "schema": { "type": "string" } }, { "name": "lang", "in": "query", "required": false, "description": "Copy language. Echoed on the 200 body.", "schema": { "type": "string", "enum": [ "es", "en" ], "example": "es" } } ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.02" }, "protocols": [ { "x402": {} } ], "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }, "responses": { "200": { "description": "Paid \u2014 mandate-scope-v1 (verify only; never create/sign; failed checks stay 200 ok:false)", "content": { "application/json": { "schema": { "type": "object", "required": [ "product", "kind", "ruleset", "ok", "checks", "constraints", "resource", "priceUsdc", "scope_vs_create", "disclaimer", "attested_at", "lang" ], "properties": { "product": { "type": "string", "const": "Mandato AR" }, "kind": { "type": "string", "const": "mandate-scope" }, "ruleset": { "type": "string", "const": "mandate-scope-v1" }, "ok": { "type": "boolean" }, "checks": { "type": "object", "required": [ "schemaValid", "signatureValid", "notExpired", "networkMatch", "resourceAllowed", "budgetSufficient" ], "properties": { "schemaValid": { "type": "boolean" }, "signatureValid": { "type": "boolean" }, "notExpired": { "type": "boolean" }, "networkMatch": { "type": "boolean" }, "resourceAllowed": { "type": "boolean" }, "budgetSufficient": { "type": "boolean" } } }, "constraints": { "type": "object", "required": [ "version", "principal", "network", "resourceBase", "allowlist", "budgetUsdc", "remainingUsdc", "expiresAt" ], "properties": { "version": { "type": "string", "const": "0.1.0" }, "principal": { "type": "string" }, "network": { "type": "string" }, "resourceBase": { "type": "string" }, "allowlist": { "type": "array", "items": { "type": "string" } }, "budgetUsdc": { "type": "string" }, "remainingUsdc": { "type": "string" }, "expiresAt": { "type": "string" } } }, "resource": { "type": "string", "format": "uri" }, "priceUsdc": { "type": "string" }, "scope_vs_create": { "type": "object", "required": [ "scope", "create" ], "properties": { "scope": { "type": "string", "const": "server verify allowlist+budget+expiry+signature against a proposed spend" }, "create": { "type": "string", "const": "local createSignedMandate/signMandate \u2014 NOT this endpoint" } } }, "disclaimer": { "type": "string" }, "attested_at": { "type": "string", "format": "date-time" }, "lang": { "type": "string", "enum": [ "es", "en" ] } }, "example": { "product": "Mandato AR", "kind": "mandate-scope", "ruleset": "mandate-scope-v1", "ok": true, "checks": { "schemaValid": true, "signatureValid": true, "notExpired": true, "networkMatch": true, "resourceAllowed": true, "budgetSufficient": true }, "constraints": { "version": "0.1.0", "principal": "did:example:compras-smoke", "network": "eip155:8453", "resourceBase": "https://lupariel.com", "allowlist": [ "https://lupariel.com/api/settle/receipt*", "https://lupariel.com/api/mandate/scope*" ], "budgetUsdc": "0.05", "remainingUsdc": "0.05", "expiresAt": "2027-12-31T23:59:59.000Z" }, "resource": "https://lupariel.com/api/settle/receipt", "priceUsdc": "0.02", "scope_vs_create": { "scope": "server verify allowlist+budget+expiry+signature against a proposed spend", "create": "local createSignedMandate/signMandate \u2014 NOT this endpoint" }, "disclaimer": "Does not create or sign a mandate. Verifies Intent Mandate v0.1.0 scope/constraints only.", "attested_at": "2026-09-23T00:00:00.000Z", "lang": "es" } } } } }, "400": { "description": "missing_resource, invalid_resource, missing_price_usdc, invalid_price_usdc, missing_mandate, invalid_mandate, invalid_spent_usdc, missing_pubkey, invalid_pubkey, or invalid_lang" }, "402": { "description": "Payment Required \u2014 x402 v2 Exact $0.02 USDC on Base (eip155:8453, amount 20000). See PAYMENT-REQUIRED header and extensions.bazaar." }, "503": { "description": "pay_to_unconfigured" } } } }, "/api/reserve/hold": { "get": { "operationId": "reserveHold", "summary": "Auth-capture HOLD live (x402 paid)", "description": "Returns x402-auth-capture-hold-v1 after auth-capture authorize: an on-chain escrow HOLD (status authorized). Unpaid GET has no required query and receives HTTP 402 with scheme auth-capture (NOT exact), amount 50000 ($0.05 USDC Base). Live unpaid creates a Coinbase Business Checkout and binds checkoutId / x402_url. HTTP 200 is HOLD, not settle \u2014 settlement truth is checkout COMPLETED. Poll alias: GET /api/reserve/hold?checkoutId= returns ACTIVE|PROCESSING|COMPLETED|FAILED|EXPIRED (transactionHash when COMPLETED). Distinct from SKU#16 /api/reserve/brief (informational, scheme exact, $0.01, no on-chain hold).", "tags": [ "reserve-hold", "auth-capture", "x402", "sku21" ], "parameters": [ { "name": "checkoutId", "in": "query", "required": false, "description": "When present, GET is poll mode (Coinbase Checkout status). Unpaid challenge requires no query.", "schema": { "type": "string", "pattern": "^[0-9a-f]{24}$", "example": "68f7a946db0529ea9b6d3a12" } } ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.05" }, "scheme": "auth-capture", "protocols": [ { "x402": {} } ], "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }, "responses": { "200": { "description": "Authorized HOLD (not settled) or poll checkout status", "content": { "application/json": { "schema": { "type": "object", "required": [ "product", "kind", "scheme", "status", "holdId", "checkoutId", "ruleset" ], "properties": { "product": { "type": "string", "const": "LupaRiel" }, "kind": { "type": "string", "const": "reserve-hold" }, "scheme": { "type": "string", "const": "auth-capture" }, "status": { "type": "string", "description": "authorized on paid HOLD; poll returns ACTIVE|PROCESSING|COMPLETED|FAILED|EXPIRED (plus Checkouts DEACTIVATED|REFUNDED|PARTIALLY_REFUNDED)." }, "holdId": { "type": "string" }, "checkoutId": { "type": "string" }, "amount": { "type": "string", "example": "0.05" }, "asset": { "type": "string", "const": "USDC" }, "network": { "type": "string", "const": "eip155:8453" }, "payTo": { "type": "string" }, "autoCapture": { "type": "boolean", "const": true }, "settlementTruth": { "type": "string" }, "notInventory": { "type": "boolean", "const": true }, "txAuthorize": { "type": "null" }, "poll": { "type": "string" }, "void": { "type": "string" }, "capture": { "type": "string" }, "refund": { "type": "string" }, "ruleset": { "type": "string", "const": "x402-auth-capture-hold-v1" }, "disclaimer": { "type": "string" }, "transactionHash": { "type": "string", "description": "Present on poll when status is COMPLETED." } }, "example": { "product": "LupaRiel", "kind": "reserve-hold", "scheme": "auth-capture", "status": "authorized", "holdId": "68f7a946db0529ea9b6d3a12", "checkoutId": "68f7a946db0529ea9b6d3a12", "amount": "0.05", "asset": "USDC", "network": "eip155:8453", "payTo": "0x6fc99c8a5334e00f6fce854700959930a3c62dbc", "autoCapture": true, "settlementTruth": "COMPLETED (checkout status), not HTTP 200 authorize", "notInventory": true, "txAuthorize": null, "poll": "GET /api/reserve/hold?checkoutId=68f7a946db0529ea9b6d3a12", "void": "N/A after authorize; wait EXPIRED or refund post-COMPLETED. ACTIVE-only deactivate: POST /api/reserve/hold/68f7a946db0529ea9b6d3a12/void", "capture": "Coinbase Checkouts captures server-side after authorize. No merchant captureAuthorizer in this path.", "refund": "POST /api/reserve/hold/68f7a946db0529ea9b6d3a12/refund", "ruleset": "x402-auth-capture-hold-v1", "disclaimer": "Reserva fondos (escrow), no inventario." } } } } }, "400": { "description": "invalid_checkout_id, invalid_payment_signature, or missing_checkout_id" }, "402": { "description": "Payment Required \u2014 x402 v2 auth-capture $0.05 USDC on Base (eip155:8453, amount 50000). Scheme is auth-capture, NOT exact. See PAYMENT-REQUIRED header and extensions.bazaar." }, "503": { "description": "pay_to_unconfigured or checkouts_unconfigured" } } } }, "/api/reserve/hold/{holdId}/refund": { "post": { "operationId": "reserveHoldRefund", "summary": "Refund a COMPLETED hold", "description": "Wraps Coinbase Business Checkouts refund. holdId === checkoutId. Optional JSON body { amount?, reason? }. Post-COMPLETED only.", "tags": [ "reserve-hold", "auth-capture", "x402", "sku21" ], "parameters": [ { "name": "holdId", "in": "path", "required": true, "description": "Same as checkoutId (24-char hex).", "schema": { "type": "string", "pattern": "^[0-9a-f]{24}$" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "string", "description": "Refund amount (default 0.05).", "example": "0.05" }, "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "Refund initiated" }, "400": { "description": "invalid_hold_id, invalid_json, or invalid_amount" }, "405": { "description": "method_not_allowed \u2014 POST only" }, "409": { "description": "refund_not_completed" }, "503": { "description": "checkouts_unconfigured" } } } }, "/api/reserve/hold/{holdId}/void": { "post": { "operationId": "reserveHoldVoid", "summary": "Deactivate an ACTIVE unpaid checkout", "description": "Wraps Checkouts deactivate. ACTIVE only. After authorize, void is N/A \u2014 wait EXPIRED or refund post-COMPLETED.", "tags": [ "reserve-hold", "auth-capture", "x402", "sku21" ], "parameters": [ { "name": "holdId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{24}$" } } ], "responses": { "200": { "description": "Checkout deactivated" }, "409": { "description": "void_not_active" } } } } } }