{ "openapi": "3.1.0", "info": { "title": "MilkyStorage — Autonomous Coin-Operated SDK & API Bugfix Registry", "version": "1.0.0", "description": "Zero-signup SDK/API bugfix registry serving comment-scrubbed U1 patches in compact TOON format over MCP Streamable HTTP and HTTP 402 (MPP + x402).", "x-guidance": "Connect via MCP Streamable HTTP at POST /mcp (call free scout_lore first, then unlock_lore, unlock_lore_session, or topup_credits_mpp) OR call HTTP 402 endpoints /api/unlock, /api/session/unlock, /api/inscribe, and /api/credits/topup directly with MPP (Authorization: Payment) or x402 (PAYMENT-SIGNATURE)." }, "servers": [ { "url": "https://www.milkycache.dev" } ], "x-service-info": { "categories": [ "ai", "developer-tools", "sdk-debugging", "mcp" ], "docs": { "homepage": "https://www.milkycache.dev/llms.txt", "apiReference": "https://www.milkycache.dev/openapi.json", "llms": "https://www.milkycache.dev/llms.txt" } }, "paths": { "/mcp": { "post": { "operationId": "mcpStreamableHttp", "summary": "Unified MCP Streamable HTTP JSON-RPC endpoint (Aisle 1 Lore + Aisle 2 Drop Cache)", "tags": [ "MCP" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "type": "string", "const": "2.0" }, "id": { "type": [ "string", "integer", "null" ] }, "method": { "type": "string" }, "params": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "JSON-RPC 2.0 response envelope (TOON or JSON tool result).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolTextEnvelope" } } } } } } }, "/drop/mcp": { "post": { "operationId": "dropMcpStreamableHttp", "summary": "Scoped Aisle 2 MCP Streamable HTTP endpoint (open_pod, peek_pod, query_pod, refuel_pod)", "tags": [ "MCP", "ScratchPod" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "type": "string", "const": "2.0" }, "id": { "type": [ "string", "integer", "null" ] }, "method": { "type": "string" }, "params": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "JSON-RPC 2.0 response envelope (TOON or JSON ScratchPod tool result).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolTextEnvelope" } } } } } } }, "/api/pod/open": { "post": { "operationId": "openScratchPod", "summary": "Allocate an isolated 24h SQLite ScratchPod + 15 prepaid SQL queries + zero-token ingest URL", "tags": [ "ScratchPod" ], "security": [ { "mpp": [] }, { "x402": [] } ], "x-payment-info": { "offers": [ { "amount": "15000", "currency": "0x20c0000000000000000000000000000000000000", "description": "Allocate 24h isolated SQLite ScratchPod + 15 SQL query credits via Tempo", "intent": "charge", "method": "tempo" }, { "amount": "15000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "description": "Allocate 24h isolated SQLite ScratchPod + 15 SQL query credits via x402 Base USDC", "intent": "charge", "method": "x402" } ], "price": { "mode": "fixed", "currency": "USD", "amount": "0.015000" }, "protocols": [ { "protocol": "mpp", "method": "tempo", "intent": "charge", "currency": "0x20c0000000000000000000000000000000000000", "recipient": "0x54990501ac52a35acd598107c2b052a21d5e35b3" }, { "protocol": "x402", "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "recipient": "0x54990501ac52a35acd598107c2b052a21d5e35b3" } ] }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "table": { "type": "string", "maxLength": 56, "default": "records" }, "src_url": { "type": "string", "format": "uri" }, "src_fmt": { "type": "string", "enum": [ "auto", "ndjson", "json", "csv", "tsv" ], "default": "auto" }, "fts_cols": { "type": "array", "items": { "type": "string" }, "maxItems": 5 }, "public_bounty": { "type": "boolean", "default": false }, "fmt": { "type": "string", "enum": [ "toon", "json" ], "default": "toon" } } } } } }, "responses": { "200": { "description": "Pod ticket (id, read_cap, write_cap, ingest_url) or auto-ingested table summary.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "402": { "description": "Payment Required. Returns WWW-Authenticate: Payment challenge (MPP) and/or PAYMENT-REQUIRED header (x402).", "headers": { "WWW-Authenticate": { "description": "RFC 9110 Payment challenge (id, realm, method, intent, request).", "schema": { "type": "string" } }, "PAYMENT-REQUIRED": { "description": "Base64-encoded x402 v2 payment requirements payload.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentChallengeError" } } } } } } }, "/api/pod/refuel": { "post": { "operationId": "refuelScratchPod", "summary": "Add +25 SQL query credits and +24h TTL to an existing ScratchPod", "tags": [ "ScratchPod" ], "security": [ { "mpp": [] }, { "x402": [] } ], "x-payment-info": { "offers": [ { "amount": "10000", "currency": "0x20c0000000000000000000000000000000000000", "description": "Add +25 SQL query credits + 24h ScratchPod TTL via Tempo", "intent": "charge", "method": "tempo" }, { "amount": "10000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "description": "Add +25 SQL query credits + 24h ScratchPod TTL via x402 Base USDC", "intent": "charge", "method": "x402" } ], "price": { "mode": "fixed", "currency": "USD", "amount": "0.010000" }, "protocols": [ { "protocol": "mpp", "method": "tempo", "intent": "charge", "currency": "0x20c0000000000000000000000000000000000000", "recipient": "0x54990501ac52a35acd598107c2b052a21d5e35b3" }, { "protocol": "x402", "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "recipient": "0x54990501ac52a35acd598107c2b052a21d5e35b3" } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "pattern": "^[0-9A-Za-z]{10}$" }, "public_bounty": { "type": "boolean" }, "fmt": { "type": "string", "enum": [ "toon", "json" ], "default": "toon" } } } } } }, "responses": { "200": { "description": "Updated fuel_left and ttl_s.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "402": { "description": "Payment Required. Returns WWW-Authenticate: Payment challenge (MPP) and/or PAYMENT-REQUIRED header (x402).", "headers": { "WWW-Authenticate": { "description": "RFC 9110 Payment challenge (id, realm, method, intent, request).", "schema": { "type": "string" } }, "PAYMENT-REQUIRED": { "description": "Base64-encoded x402 v2 payment requirements payload.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentChallengeError" } } } } } } }, "/api/unlock": { "post": { "operationId": "unlockLore", "summary": "Unlock verified U1 SDK/API bugfix patch + $0.001 appraisal rebate ballot", "tags": [ "Lore" ], "security": [ { "mpp": [] }, { "x402": [] } ], "x-payment-info": { "offers": [ { "amount": "5000", "currency": "0x20c0000000000000000000000000000000000000", "description": "Unlock verified U1 bugfix patch via Tempo USDC.e", "intent": "charge", "method": "tempo" }, { "amount": "5000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "description": "Unlock verified U1 bugfix patch via x402 Base USDC", "intent": "charge", "method": "x402" } ], "price": { "mode": "fixed", "currency": "USD", "amount": "0.005000" }, "protocols": [ { "protocol": "mpp", "method": "tempo", "intent": "charge", "currency": "0x20c0000000000000000000000000000000000000", "recipient": "0x54990501ac52a35acd598107c2b052a21d5e35b3" }, { "protocol": "x402", "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "recipient": "0x54990501ac52a35acd598107c2b052a21d5e35b3" } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "pattern": "^[0-9A-Za-z]{10}$", "description": "10-char Base62 lore_id from scout_lore." }, "fmt": { "type": "string", "enum": [ "toon", "json" ], "default": "toon" } } } } } }, "responses": { "200": { "description": "Verified U1 patch or override map plus single-use 10-char rebate ballot stub.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnlockedLoreResponse" } } } }, "402": { "description": "Payment Required. Returns WWW-Authenticate: Payment challenge (MPP) and/or PAYMENT-REQUIRED header (x402).", "headers": { "WWW-Authenticate": { "description": "RFC 9110 Payment challenge (id, realm, method, intent, request).", "schema": { "type": "string" } }, "PAYMENT-REQUIRED": { "description": "Base64-encoded x402 v2 payment requirements payload.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentChallengeError" } } } } } } }, "/api/inscribe": { "post": { "operationId": "inscribeLore", "summary": "Stake $0.02 to publish a schema-checked, comment-scrubbed U1 bugfix patch", "tags": [ "Lore" ], "security": [ { "mpp": [] }, { "x402": [] } ], "x-payment-info": { "offers": [ { "amount": "20000", "currency": "0x20c0000000000000000000000000000000000000", "description": "Refundable stake to publish Mimic-scrubbed U1 patch via Tempo", "intent": "charge", "method": "tempo" }, { "amount": "20000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "description": "Refundable stake to publish Mimic-scrubbed U1 patch via x402 Base USDC", "intent": "charge", "method": "x402" } ], "price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" }, "protocols": [ { "protocol": "mpp", "method": "tempo", "intent": "charge", "currency": "0x20c0000000000000000000000000000000000000", "recipient": "0x54990501ac52a35acd598107c2b052a21d5e35b3" }, { "protocol": "x402", "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "recipient": "0x54990501ac52a35acd598107c2b052a21d5e35b3" } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pkg", "err", "cause", "fix" ], "properties": { "pkg": { "type": "string", "maxLength": 120 }, "ver": { "type": "string", "maxLength": 32, "default": "*" }, "st": { "type": [ "integer", "null" ] }, "err": { "type": "string", "maxLength": 80 }, "cause": { "type": "string", "enum": [ "UNDOC_PARAM", "PAGINATION_CAP", "RL_QUIRK", "SEMVER_REG", "HDR_TRAP", "TYPE_DESYNC" ] }, "fix": { "type": "object", "additionalProperties": true }, "fmt": { "type": "string", "enum": [ "toon", "json" ], "default": "toon" } } } } } }, "responses": { "200": { "description": "Newly created 10-char Base62 lore ID and escrowed stake confirmation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "id", "stake_u" ], "properties": { "ok": { "type": "integer", "const": 1 }, "id": { "type": "string" }, "stake_u": { "type": "integer", "const": 19000 } } } } } }, "402": { "description": "Payment Required. Returns WWW-Authenticate: Payment challenge (MPP) and/or PAYMENT-REQUIRED header (x402).", "headers": { "WWW-Authenticate": { "description": "RFC 9110 Payment challenge (id, realm, method, intent, request).", "schema": { "type": "string" } }, "PAYMENT-REQUIRED": { "description": "Base64-encoded x402 v2 payment requirements payload.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentChallengeError" } } } } } } }, "/stats": { "get": { "operationId": "getGuildStats", "summary": "Read-only catalog, ballot return rate, and vault solvency telemetry", "tags": [ "Telemetry" ], "parameters": [ { "name": "fmt", "in": "query", "schema": { "type": "string", "enum": [ "json", "toon" ] } } ], "responses": { "200": { "description": "Aggregate catalog and solvency metrics.", "content": { "application/json": { "schema": { "type": "object", "required": [ "service", "solvency_invariant_ok", "catalog", "treasury" ], "properties": { "service": { "type": "string" }, "solvency_invariant_ok": { "type": "boolean" }, "catalog": { "type": "object", "additionalProperties": true }, "treasury": { "type": "object", "additionalProperties": true } } } } } } } } }, "/api/session/unlock": { "post": { "operationId": "unlockLoreSession", "summary": "Metered Tempo MPP Session unlock ($0.005/read off-chain voucher, settles every $0.01)", "tags": [ "Lore", "Sessions" ], "security": [ { "mpp": [] } ], "x-payment-info": { "offers": [ { "amount": "5000", "currency": "0x20c0000000000000000000000000000000000000", "description": "Metered $0.005 Tempo session voucher per lore unlock", "intent": "session", "method": "tempo" } ], "price": { "mode": "fixed", "currency": "USD", "amount": "0.005000" }, "protocols": [ { "protocol": "mpp", "method": "tempo", "intent": "session", "currency": "0x20c0000000000000000000000000000000000000", "recipient": "0x54990501ac52a35acd598107c2b052a21d5e35b3" } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "pattern": "^[0-9A-Za-z]{10}$" }, "wallet": { "type": "string", "maxLength": 64 }, "fmt": { "type": "string", "enum": [ "toon", "json" ], "default": "toon" } } } } } }, "responses": { "200": { "description": "Streamed U1 patch unlock with MPP session receipt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnlockedLoreResponse" } } } }, "402": { "description": "Payment Required. Returns WWW-Authenticate: Payment challenge (MPP) and/or PAYMENT-REQUIRED header (x402).", "headers": { "WWW-Authenticate": { "description": "RFC 9110 Payment challenge (id, realm, method, intent, request).", "schema": { "type": "string" } }, "PAYMENT-REQUIRED": { "description": "Base64-encoded x402 v2 payment requirements payload.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentChallengeError" } } } } } } }, "/api/credits/topup": { "post": { "operationId": "topupCreditsMpp", "summary": "Buy 100,000 uUSDC store credits (20 unlocks) for $0.50 via Stripe SPT card or Tempo", "tags": [ "Credits" ], "security": [ { "mpp": [] } ], "x-payment-info": { "offers": [ { "amount": "500000", "currency": "0x20c0000000000000000000000000000000000000", "description": "20-unlock credit pack (100,000 uUSDC) via Tempo USDC.e", "intent": "charge", "method": "tempo" } ], "price": { "mode": "fixed", "currency": "USD", "amount": "0.500000" }, "protocols": [ { "protocol": "mpp", "method": "tempo", "intent": "charge", "currency": "0x20c0000000000000000000000000000000000000", "recipient": "0x54990501ac52a35acd598107c2b052a21d5e35b3" } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "wallet" ], "properties": { "wallet": { "type": "string", "minLength": 32, "maxLength": 64, "description": "EVM 0x address or Ed25519 pubkey that will sign gasless redeem_lore calls." }, "fmt": { "type": "string", "enum": [ "toon", "json" ], "default": "toon" } } } } } }, "responses": { "200": { "description": "Updated closed-loop credit balance (cred_u, free unlocks, next redeem nonce).", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "added_u", "tab" ], "properties": { "ok": { "type": "integer", "const": 1 }, "added_u": { "type": "integer", "const": 100000 }, "tab": { "type": "object", "additionalProperties": true } } } } } }, "402": { "description": "Payment Required. Returns WWW-Authenticate: Payment challenge (MPP) and/or PAYMENT-REQUIRED header (x402).", "headers": { "WWW-Authenticate": { "description": "RFC 9110 Payment challenge (id, realm, method, intent, request).", "schema": { "type": "string" } }, "PAYMENT-REQUIRED": { "description": "Base64-encoded x402 v2 payment requirements payload.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentChallengeError" } } } } } } } }, "components": { "securitySchemes": { "mpp": { "type": "http", "scheme": "payment", "description": "Machine Payments Protocol (IETF draft-httpauth-payment). Send Authorization: Payment . See /.well-known/mpp." }, "x402": { "type": "apiKey", "in": "header", "name": "PAYMENT-SIGNATURE", "description": "x402 v2 Base64-encoded EIP-3009 USDC authorization on Base. See /.well-known/x402." } }, "schemas": { "ToolTextEnvelope": { "type": "object", "properties": { "jsonrpc": { "type": "string" }, "result": { "type": "object", "additionalProperties": true } } }, "UnlockedLoreResponse": { "type": "object", "required": [ "id", "tier", "cause" ], "properties": { "id": { "type": "string" }, "tier": { "type": "string", "enum": [ "UP", "VF", "CC" ] }, "cause": { "type": "string" }, "remediation": { "type": "object", "additionalProperties": true }, "stub": { "type": "object", "additionalProperties": true } } }, "PaymentChallengeError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "protocol": { "type": "string", "enum": [ "mpp", "x402" ] } } } } } }