{ "openapi": "3.1.0", "info": { "title": "Keeper Holdings API", "version": "0.16.0", "description": "Reference prices for sealed tech, custody receipts, proof of holding and a delivery-versus-payment market. Sandbox on Base Sepolia (chain id 84532); test USDC only." }, "servers": [ { "url": "https://keeperholdings.io" } ], "components": { "securitySchemes": { "session": { "type": "http", "scheme": "bearer", "description": "Token from POST /v1/auth/verify (SIWE). Also accepted as the kh_s cookie." }, "x402": { "type": "apiKey", "in": "header", "name": "PAYMENT-SIGNATURE", "description": "x402 v2 payment, 0.01 test USDC on Base Sepolia." } } }, "paths": { "/v1/skus": { "get": { "summary": "All parts with the 24h-delayed index", "parameters": [], "responses": { "200": { "description": "OK" } } } }, "/v1/index/{sku}": { "get": { "summary": "Delayed index for one part", "parameters": [ { "name": "sku", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/v1/index/{sku}/live": { "get": { "summary": "Real-time index (x402, 0.01 test USDC)", "parameters": [ { "name": "sku", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } }, "security": [ { "x402": [] } ] } }, "/v1/custody-fees": { "get": { "summary": "Fee tier per part", "parameters": [], "responses": { "200": { "description": "OK" } } } }, "/v1/attestations": { "get": { "summary": "EIP-712 signed index attestations (price, tier) for contracts", "parameters": [], "responses": { "200": { "description": "OK" } } } }, "/v1/attestations/{sku}": { "get": { "summary": "Signed attestation for one part", "parameters": [ { "name": "sku", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/v1/chain": { "get": { "summary": "Chain id, contract addresses, attester, EIP-712 domain", "parameters": [], "responses": { "200": { "description": "OK" } } } }, "/v1/testnet": { "get": { "summary": "Sandbox dashboard feed", "parameters": [], "responses": { "200": { "description": "OK" } } } }, "/v1/keepers/sandbox": { "get": { "summary": "Self-serve sandbox Keepers", "parameters": [], "responses": { "200": { "description": "OK" } } } }, "/v1/hold/quote?sku=&months=": { "get": { "summary": "Custody quote: tier, period fee, prepay", "parameters": [], "responses": { "200": { "description": "OK" } } } }, "/v1/auth/nonce": { "get": { "summary": "SIWE nonce", "parameters": [], "responses": { "200": { "description": "OK" } } } }, "/v1/auth/verify": { "post": { "summary": "Verify a SIWE message + signature; returns a bearer token and sets a cookie. A wallet seen for the first time gets a sandbox faucet grant (gas + test USDC) in the background", "security": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "OK" }, "401": { "description": "Sign in first" } } } }, "/v1/auth/me": { "get": { "summary": "Who am I (includes the latest faucet grant)", "parameters": [], "responses": { "200": { "description": "OK" } } } }, "/v1/faucet": { "get": { "summary": "Faucet amounts and limits", "parameters": [], "responses": { "200": { "description": "OK" } } }, "post": { "summary": "Ask for a sandbox grant: gas drip + test USDC, once per wallet per 24 h, 20 per IP per day", "security": [ { "session": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "OK" }, "401": { "description": "Sign in first" } } } }, "/v1/keeper/apply": { "post": { "summary": "Become a sandbox Keeper (display_name, region)", "security": [ { "session": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "OK" }, "401": { "description": "Sign in first" } } } }, "/v1/keeper/me": { "get": { "summary": "Keeper console data: bond, coverage, receipts, open proofs", "parameters": [], "responses": { "200": { "description": "OK" } } } }, "/v1/hold/request": { "post": { "summary": "Open a hold (sku_id, keeper_id, serial?)", "security": [ { "session": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "OK" }, "401": { "description": "Sign in first" } } } }, "/v1/hold/mine": { "get": { "summary": "My receipts with intake attestations and mint calldata", "parameters": [], "responses": { "200": { "description": "OK" } } } }, "/v1/receipts/{id}": { "get": { "summary": "Public receipt", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/v1/receipts/{id}/intake": { "post": { "summary": "Keeper confirms arrival with an intake photo (multipart \"photo\"); returns the intake attestation", "security": [ { "session": [] } ], "responses": { "200": { "description": "VERIFIED + attestation" } } } }, "/v1/receipts/{id}/proof": { "post": { "summary": "Keeper requests a one-time proof code (48 h window)", "security": [ { "session": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "OK" }, "401": { "description": "Sign in first" } } } }, "/v1/proofs/{id}/submit": { "post": { "summary": "Submit the proof photo (multipart \"photo\"); vision check, hash, signed ProofAttestation and releaseOnProof calldata", "security": [ { "session": [] } ], "responses": { "200": { "description": "passed | failed | review" } } } }, "/v1/receipts/{id}/proofs": { "get": { "summary": "Proof history for a receipt", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/v1/receipts/{id}/sync": { "post": { "summary": "Reconcile a receipt with chain state after a transaction (tx, kind)", "security": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "OK" }, "401": { "description": "Sign in first" } } } }, "/v1/tx/prepare": { "post": { "summary": "Calldata for a wallet: {contract, method, args}", "security": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "OK" }, "401": { "description": "Sign in first" } } } }, "/v1/market/offers": { "get": { "summary": "Open offers next to the index price", "parameters": [], "responses": { "200": { "description": "OK" } } }, "post": { "summary": "Post a signed EIP-712 Offer (receipt_id, price_atomic, expiry, nonce, signature, buyer?)", "security": [ { "session": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "OK" }, "401": { "description": "Sign in first" } } } }, "/v1/market/offers/{id}/filled": { "post": { "summary": "Report a fill transaction; the Worker verifies title moved on chain", "security": [ { "session": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "OK" }, "401": { "description": "Sign in first" } } } }, "/v1/market/offers/{id}/cancel": { "post": { "summary": "Cancel an offer: returns Settlement.cancel calldata; the offer is cancelled once the nonce is used on chain", "security": [ { "session": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "OK" }, "401": { "description": "Sign in first" } } } }, "/v1/webhooks": { "get": { "summary": "My webhook subscriptions", "parameters": [], "responses": { "200": { "description": "OK" } }, "security": [ { "session": [] } ] }, "post": { "summary": "Subscribe an https URL to events (receipt.state, proof.result, offer.posted, offer.filled, signal.fired, signal.cleared); returns the signing secret once", "security": [ { "session": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "OK" }, "401": { "description": "Sign in first" } } } }, "/v1/webhooks/{id}/test": { "post": { "summary": "Send a ping delivery", "security": [ { "session": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "OK" }, "401": { "description": "Sign in first" } } } }, "/v1/webhooks/{id}/deliveries": { "get": { "summary": "Recent deliveries with status", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } }, "security": [ { "session": [] } ] } }, "/mcp": { "post": { "summary": "MCP server (JSON-RPC 2.0, Streamable HTTP). Read tools free; index.live is x402-paid.", "responses": { "200": { "description": "JSON-RPC result" } } } } } }