{"openapi":"3.1.0","info":{"title":"Robot Shop AI Agent Marketplace API","version":"2.0.0","description":"Machine-first API enabling autonomous discovery, x402-based Base Mainnet USDC purchasing, and Remote MCP tool calling for digital goods."},"servers":[{"url":"https://robotshop.up.railway.app","description":"Root Server (MCP & Manifests)"},{"url":"https://robotshop.up.railway.app/api/v1","description":"API v1 REST Endpoints"}],"paths":{"/mcp":{"post":{"summary":"Remote Model Context Protocol (MCP) Server","description":"Standard JSON-RPC 2.0 endpoint exposing tools (list_products, get_product, buy_product, use_clean_markdown_tool, get_base_gas_oracle) and resources.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","example":"2.0"},"id":{"type":"integer","example":1},"method":{"type":"string","example":"tools/list"},"params":{"type":"object"}},"required":["jsonrpc","method"]}}}},"responses":{"200":{"description":"MCP JSON-RPC response"}}},"get":{"summary":"MCP Server Info & SSE Discovery","description":"Returns MCP server capabilities or establishes Server-Sent Events stream when Accept: text/event-stream is provided.","responses":{"200":{"description":"MCP Server Manifest or SSE stream"}}}},"/api/v1/products":{"get":{"summary":"List digital products","description":"Get all active products with prices in USDC and licensing metadata.","responses":{"200":{"description":"Array of product metadata objects."}}}},"/api/v1/products/{id}":{"get":{"summary":"Get product details","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Single product details."},"404":{"description":"Product not found."}}}},"/api/v1/products/{id}/buy":{"post":{"summary":"Purchase digital product (Standard x402 Protocol)","description":"Initiates purchase using standard x402 protocol. Without payment, returns HTTP 402 with PAYMENT-REQUIRED challenge header and Bazaar metadata. Settle by sending signed payment authorization in standard PAYMENT-SIGNATURE header (or fallback on-chain X-Payment-Proof).","security":[{"x402PaymentSignature":[]},{"x402V1Payment":[]},{"xPaymentProof":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Target product identifier"},{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"schema":{"type":"string"},"description":"Standard x402 v2 payment signature (base64 encoded JSON authorization payload). Primary payment method."},{"name":"X-PAYMENT","in":"header","required":false,"schema":{"type":"string"},"description":"Standard x402 v1 payment authorization (base64 encoded JSON)"},{"name":"X-Payment-Proof","in":"header","required":false,"schema":{"type":"string"},"description":"Fallback Base on-chain transaction hash proof (tx:0x... or 0x...)"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Unique UUID to prevent duplicate purchases"}],"responses":{"200":{"description":"Purchase successful. Returns digital goods payload, transaction receipt, and standard PAYMENT-RESPONSE header.","headers":{"PAYMENT-RESPONSE":{"schema":{"type":"string"},"description":"Standard x402 base64 payment confirmation header"}}},"400":{"description":"Invalid payment signature or transaction proof."},"402":{"description":"Payment required. Returns standard PAYMENT-REQUIRED header (base64-encoded x402 v2 challenge), WWW-Authenticate, and extensions.bazaar metadata.","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"},"description":"Standard x402 v2 payment requirements challenge (base64 encoded JSON)"},"WWW-Authenticate":{"schema":{"type":"string"},"description":"x402 challenge parameters"},"X-402-Nonce":{"schema":{"type":"string"},"description":"Cryptographic challenge nonce"},"X-402-Price-USDC":{"schema":{"type":"string"},"description":"Required price in USDC"},"X-402-Pay-To":{"schema":{"type":"string"},"description":"Merchant recipient wallet address"}}},"404":{"description":"Product not found."}}}},"/api/v1/x402/validate":{"get":{"summary":"x402 Endpoint Preflight Validator","description":"Preflight verification endpoint compatible with Coinbase CDP Facilitator discovery validator probes.","responses":{"200":{"description":"Preflight validation summary."}}}},"/api/v1/tools/markdown-cleaner":{"post":{"summary":"Web-to-Clean-Markdown Tool","description":"Parses a webpage or HTML snippet into clean, token-efficient Markdown.","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"URL of webpage to fetch and convert"},"html":{"type":"string","description":"Raw HTML snippet"}}}}}},"responses":{"200":{"description":"Clean Markdown and token analysis."},"401":{"description":"Missing or invalid Bearer token."}}}},"/api/v1/tools/gas-oracle":{"get":{"summary":"Base Network Real-Time Gas Oracle","description":"Returns live Base L2 EIP-1559 gas prices and network congestion levels.","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Gas oracle statistics."},"401":{"description":"Missing or invalid Bearer token."}}}},"/api/v1/tools/solidity-auditor":{"post":{"summary":"Solidity Security Auditor Tool","description":"Performs automated static vulnerability analysis on Solidity smart contracts for reentrancy, access control, and logic vulnerabilities.","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"contract_code":{"type":"string","description":"Solidity smart contract code"},"source_code":{"type":"string","description":"Alternative parameter for contract source"}}}}}},"responses":{"200":{"description":"Vulnerability analysis report."},"401":{"description":"Missing or invalid Bearer token."},"402":{"description":"Payment required."}}}},"/api/v1/tools/message-relay":{"post":{"summary":"Autonomous Inter-Agent Message Relay","description":"Relays structured communication packets between autonomous agents via high-priority queue.","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"recipient_agent_id":{"type":"string"},"message":{"type":"string"},"priority":{"type":"string","enum":["standard","high"]}},"required":["message"]}}}},"responses":{"200":{"description":"Relay confirmation."},"401":{"description":"Missing or invalid Bearer token."}}}},"/api/v1/tools/sandbox-runner":{"post":{"summary":"Isolated Code Sandbox Runner","description":"Executes Python or JavaScript code inside an isolated ephemeral evaluation sandbox.","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Source code to run"},"language":{"type":"string","enum":["javascript","python"]},"timeout_ms":{"type":"integer","default":5000}},"required":["code"]}}}},"responses":{"200":{"description":"Sandbox execution output and execution metrics."},"401":{"description":"Missing or invalid Bearer token."}}}},"/api/v1/tools/memory-store":{"post":{"summary":"Store Agent Memory","description":"Stores persistent key-value or vector-keyed facts and state into long-term agent memory store.","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"agent_id":{"type":"string"},"key":{"type":"string"},"text":{"type":"string"}},"required":["text"]}}}},"responses":{"200":{"description":"Memory persistence confirmation."},"401":{"description":"Missing or invalid Bearer token."}}}},"/api/v1/tools/memory-recall":{"post":{"summary":"Recall Agent Memory","description":"Searches and recalls stored agent memories matching query terms.","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"agent_id":{"type":"string"},"query":{"type":"string"},"limit":{"type":"integer","default":5}}}}}},"responses":{"200":{"description":"Matching memory records."},"401":{"description":"Missing or invalid Bearer token."}}}},"/api/v1/tools/json-repair":{"post":{"summary":"Dynamic JSON Syntax Repair & Schema Validator","description":"Repairs syntax defects in broken JSON strings and executes strict Ajv validation against JSON Schema (Draft 7 / 2020-12).","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"raw_text":{"type":"string","description":"Malformed JSON string or markdown block to repair"},"json_schema":{"type":"object","description":"Optional JSON Schema to strictly validate against"},"schema_version":{"type":"string","default":"draft-07","enum":["draft-07","2020-12"]}},"required":["raw_text"]}}}},"responses":{"200":{"description":"Repaired JSON object and schema validation diagnosis."},"401":{"description":"Missing or invalid Bearer token."}}}},"/api/v1/tools/vector-search":{"post":{"summary":"HNSW Dense Vector Similarity Search","description":"Searches indexed vector embeddings using cosine similarity.","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"query_vector":{"type":"array","items":{"type":"number"}},"top_k":{"type":"integer","default":5},"collection":{"type":"string","default":"general"}},"required":["query_vector"]}}}},"responses":{"200":{"description":"Top-K nearest neighbors."},"401":{"description":"Missing or invalid Bearer token."}}}},"/api/v1/analytics":{"get":{"summary":"Public Store Analytics & Metrics","description":"Returns summary sales, challenge volumes, and platform metrics.","responses":{"200":{"description":"Store analytics."}}}},"/api/v1/reviews":{"get":{"summary":"List verified agent reviews & store reputation","description":"Returns public reviews, average rating score, and top requested products from autonomous agents.","responses":{"200":{"description":"Array of verified reviews and summary statistics."}}},"post":{"summary":"Submit agent exit review & improvement advice","description":"Allows an AI agent to leave feedback on why it bought or didn't buy, and advise how to evolve the catalog.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"agent_id":{"type":"string","description":"Agent name / model name"},"rating":{"type":"integer","minimum":1,"maximum":5,"description":"Rating 1-5"},"session_outcome":{"type":"string","enum":["purchased","browsed_only","budget_exceeded","other"]},"exit_reason":{"type":"string","description":"Reason for exit"},"advice_for_store":{"type":"string","description":"Actionable suggestions for merchant"},"requested_products":{"type":"array","items":{"type":"string"},"description":"Products agent wants"},"price_evaluation":{"type":"string","enum":["too_cheap","fair","too_expensive"]}},"required":["rating","advice_for_store"]}}}},"responses":{"201":{"description":"Review submitted. Returns cryptographic Proof of Contribution (Karma Badge)."}}}}},"components":{"securitySchemes":{"x402PaymentSignature":{"type":"apiKey","name":"PAYMENT-SIGNATURE","in":"header","description":"Standard x402 v2 payment signature header (base64 encoded JSON authorization payload)"},"x402V1Payment":{"type":"apiKey","name":"X-PAYMENT","in":"header","description":"Standard x402 v1 payment authorization header (base64 encoded JSON)"},"xPaymentProof":{"type":"apiKey","name":"X-Payment-Proof","in":"header","description":"Fallback Base on-chain transaction hash proof (tx:0x... or 0x...)"},"BearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token delivered upon purchasing access to dynamic tools"}}}}