{ "openapi": "3.1.0", "info": { "title": "LupaRiel paid APIs", "version": "1.8.0", "description": "Pay-per-call x402 APIs from LupaRiel: catalog lookup ($0.005, or $0.01 when status is present), AR settle-readiness check, AR rail matrix, catalog URL liveness, auth-capture hold brief, settle receipt, Mandato AR mandate scope and a live auth-capture hold. HTML pages and the static /rieles.json and /catalog.json stay free. Lookup never returns the full catalog, and 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 an on-chain escrow authorization with wire scheme auth-capture, not exact. HTTP 200 there means the hold is placed, and settlement truth is the checkout reaching COMPLETED. Settle receipt is an informational attestation of a transaction and shows that settlement is separate from consent. It does not re-query Basescan. Mandate scope verifies a signed Intent Mandate v0.1.0 against a proposed spend and does not create or sign mandates.", "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": "lupa@mail.grokbot.com" } }, "servers": [ { "url": "https://lupariel.com", "description": "Production" } ], "paths": { "/api/lookup": { "get": { "operationId": "lookupFichas", "summary": "Catalog lookup (x402 paid)", "description": "Search the LupaRiel catalog of agentic payment rails by name, slug, tag or category. Returns up to 20 matching entries as JSON, not the full catalog. Unpaid requests receive HTTP 402. Requests without q and rail receive HTTP 400, because status alone is not enough (this avoids enumeration). Price: q or rail without status costs $0.005 (atomic 5000). When status is present, for example ?rail=x402&status=produccion, the price is $0.01 (atomic 10000). The status filter matches entries whose status equals the value or whose statuses[] includes it. English aliases production, pilot and announced are accepted, and each match also carries status_en and statuses_en.", "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 entries whose status equals this value or whose statuses[] includes it. Allowed: produccion, piloto, anunciado, or the English aliases production, pilot, announced. status alone is not a valid query (400 missing_query). When present, the 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", "production", "pilot", "announced" ], "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" }, "status_en": { "type": "string", "enum": [ "production", "pilot", "announced" ], "description": "English label of status" }, "statuses_en": { "type": "array", "items": { "type": "string" }, "description": "English labels of statuses" } } } } } } } } }, "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": "Checks whether an agent payment in Argentina can settle directly or first needs a fiat consent step.\n\nReturns 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. 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": "Rail matrix for agent payments in Argentina: which rail settles, which handles consent and which handles checkout for a given case.\n\nReturns 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. 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" }, "why_en": { "type": "string", "description": "One-line English rationale" } } } } }, "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.", "why_en": "Pay per HTTP 402 request with Exact and USDC: native settlement, no ARS hop." } ] } } } } }, "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": "Checks whether the source URLs of LupaRiel catalog entries are reachable.\n\nReturns 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. 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": "Informational brief on an auth-capture hold. Does not place any on-chain hold.\n\nReturns 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": "Informational attestation of a settlement transaction. Shows that settlement is separate from consent.\n\nReturns 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": "Verifies the scope of an Intent Mandate for Argentina: allowlist, budget, expiry and signature. Does not create or sign mandates.\n\nReturns 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" }, "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" }, "example": "0.02" }, { "name": "mandate", "in": "query", "required": true, "description": "base64url JSON Intent Mandate v0.1.0 (github.com/mswitach/mandato-ar packages/mandate). The example is the canonical smoke mandate (HMAC demo, did:example:compras-smoke, budget 0.05 USDC, expires 2027-12-31).", "schema": { "type": "string", "example": "eyJ2ZXJzaW9uIjoiMC4xLjAiLCJwcmluY2lwYWwiOiJkaWQ6ZXhhbXBsZTpjb21wcmFzLXNtb2tlIiwiYnVkZ2V0VXNkYyI6IjAuMDUiLCJleHBpcmVzQXQiOiIyMDI3LTEyLTMxVDIzOjU5OjU5LjAwMFoiLCJhbGxvd2xpc3QiOlsiaHR0cHM6Ly9sdXBhcmllbC5jb20vYXBpL3NldHRsZS9yZWNlaXB0KiIsImh0dHBzOi8vbHVwYXJpZWwuY29tL2FwaS9tYW5kYXRlL3Njb3BlKiJdLCJuZXR3b3JrIjoiZWlwMTU1Ojg0NTMiLCJyZXNvdXJjZUJhc2UiOiJodHRwczovL2x1cGFyaWVsLmNvbSIsIm5vbmNlIjoic21va2UxOS01MWZkNzY5ODNjNDczNmU4Iiwic2lnbmF0dXJlIjoiaG1hYzpmY2RkMmNkNDRmY2VjOTNjYWMyYzM4YzI1Y2FkMWJiOWZkZDM0ZGVkZTdlYjE1OTFhYTdlNjI5MWQyZGEzNGUyIn0" }, "example": "eyJ2ZXJzaW9uIjoiMC4xLjAiLCJwcmluY2lwYWwiOiJkaWQ6ZXhhbXBsZTpjb21wcmFzLXNtb2tlIiwiYnVkZ2V0VXNkYyI6IjAuMDUiLCJleHBpcmVzQXQiOiIyMDI3LTEyLTMxVDIzOjU5OjU5LjAwMFoiLCJhbGxvd2xpc3QiOlsiaHR0cHM6Ly9sdXBhcmllbC5jb20vYXBpL3NldHRsZS9yZWNlaXB0KiIsImh0dHBzOi8vbHVwYXJpZWwuY29tL2FwaS9tYW5kYXRlL3Njb3BlKiJdLCJuZXR3b3JrIjoiZWlwMTU1Ojg0NTMiLCJyZXNvdXJjZUJhc2UiOiJodHRwczovL2x1cGFyaWVsLmNvbSIsIm5vbmNlIjoic21va2UxOS01MWZkNzY5ODNjNDczNmU4Iiwic2lnbmF0dXJlIjoiaG1hYzpmY2RkMmNkNDRmY2VjOTNjYWMyYzM4YzI1Y2FkMWJiOWZkZDM0ZGVkZTdlYjE1OTFhYTdlNjI5MWQyZGEzNGUyIn0" }, { "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" } } } } } }