{ "openapi": "3.1.0", "info": { "title": "ScanHood API", "description": "On-chain safety, market data, and launch tooling for Robinhood Chain (EVM chain 4663). No API key required for read endpoints. See https://scanhood.xyz/llms.txt for an agent-oriented summary, or https://scanhood.xyz/mcp for the MCP interface.", "version": "1.0.0", "contact": { "url": "https://scanhood.xyz", "name": "ScanHood" }, "license": { "name": "Source available", "url": "https://github.com/scanhood/scanhood" } }, "servers": [ { "url": "https://scanhood.xyz" } ], "paths": { "/api/scan": { "get": { "summary": "Safety scan a token", "description": "Composite on-chain safety verdict: honeypot buy+sell simulation (real callStatic, not a heuristic), LP-lock status, contract verification, deployer reputation, RWA-impostor detection.", "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "description": "ERC-20 token address" } ], "responses": { "200": { "description": "Safety verdict", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "verdict": { "type": "string", "enum": [ "PASS", "CAUTION", "DANGER" ] }, "sellable": { "type": "boolean", "nullable": true }, "roundTripLossPct": { "type": "number", "nullable": true }, "lp": { "type": "object", "nullable": true }, "verified": { "type": "boolean", "nullable": true }, "launchpad": { "type": "string", "nullable": true }, "rwa": { "type": "string", "nullable": true, "enum": [ "official", "impostor", "unverified", null ] }, "deployer": { "type": "object", "nullable": true }, "market": { "type": "object", "nullable": true }, "flags": { "type": "array", "items": { "type": "object" } }, "note": { "type": "string" } } } } } }, "400": { "description": "Invalid token address" } } } }, "/api/search": { "get": { "summary": "Search for a token", "description": "Find any Robinhood-Chain token by symbol, name, or address — live, not limited to a curated list.", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2 } } ], "responses": { "200": { "description": "Search results" }, "400": { "description": "Query too short" } } } }, "/api/quote": { "get": { "summary": "Get a swap quote", "description": "Best-route (V2/V3) swap quote for a token against WETH.", "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" } }, { "name": "side", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "buy", "sell" ], "default": "buy" } }, { "name": "amount", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Decimal amount, e.g. 0.01" } ], "responses": { "200": { "description": "Quote" }, "400": { "description": "Invalid token or amount" }, "422": { "description": "Quote could not be built" } } } }, "/api/ohlcv": { "get": { "summary": "Get OHLCV candles", "parameters": [ { "name": "pool", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "description": "Pool address" }, { "name": "tf", "in": "query", "required": false, "schema": { "type": "string", "default": "1h" }, "description": "Timeframe, e.g. 1h, 1d" } ], "responses": { "200": { "description": "Candle data" }, "400": { "description": "Invalid pool address" }, "503": { "description": "Rate limited upstream" } } } }, "/api/launch": { "post": { "summary": "Build an unsigned token-launch transaction", "description": "Builds calldata + value to launch a fixed-supply token into a locked liquidity position, on either launchpad version. The server never holds a key — the caller signs and sends the returned transaction with their own wallet. Response includes a CREATE2-predicted token address when `from` is supplied (verified exact-match against real deploys for both v3 and v4).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "symbol" ], "properties": { "name": { "type": "string", "maxLength": 64 }, "symbol": { "type": "string", "maxLength": 16 }, "version": { "type": "string", "enum": [ "v3", "v4" ], "default": "v3", "description": "v3 has anti-snipe protection + atomic initial buy; v4 is Uniswap V4, no anti-snipe window, no atomic initial buy" }, "logo": { "type": "string", "maxLength": 300 }, "description": { "type": "string", "maxLength": 500 }, "socials": { "type": "object", "properties": { "twitter": { "type": "string" }, "telegram": { "type": "string" }, "discord": { "type": "string" }, "website": { "type": "string" }, "farcaster": { "type": "string" } } }, "feeWallet": { "type": "string", "description": "Address to receive the creator's 70% fee share; defaults to the sender if omitted" }, "initialBuyEth": { "type": "string", "description": "v3 only — optional ETH amount for an atomic initial buy at launch. Rejected (400) if set for a v4 launch." }, "initialTick": { "type": "integer", "description": "v4 only — starting price tick, default -204200" }, "from": { "type": "string", "description": "Sender address, used to predict the resulting token address" } } } } } }, "responses": { "200": { "description": "Unsigned tx (to, data, value) plus predicted token address" }, "400": { "description": "Invalid params" } } } }, "/api/bots/stats": { "get": { "summary": "Flash-arb and fee-claim bot stats", "responses": { "200": { "description": "Public stats for the ScanHood arb scanner and auto-claim bot" } } } }, "/mcp": { "post": { "summary": "MCP Streamable HTTP endpoint", "description": "Full Model Context Protocol interface — scan_token, search_token, get_ohlcv, get_swap_quote, build_launch_tx. See https://scanhood.xyz/llms.txt.", "responses": { "200": { "description": "MCP JSON-RPC response" } } } }, "/api/bridge-quote": { "get": { "summary": "Get a cross-chain bridge quote", "description": "Read-only cross-chain quote (no execution) for bridging native ETH/BNB via relay.link — the same route the Bridge tab on /swap uses. No ScanHood fee.", "parameters": [ { "name": "fromChain", "in": "query", "required": true, "schema": { "type": "integer", "enum": [ 4663, 1, 8453, 42161, 56 ] }, "description": "source chain id" }, { "name": "toChain", "in": "query", "required": true, "schema": { "type": "integer", "enum": [ 4663, 1, 8453, 42161, 56 ] }, "description": "destination chain id, must differ from fromChain" }, { "name": "amount", "in": "query", "required": true, "schema": { "type": "string" }, "description": "native-token amount to bridge, decimal string e.g. 0.01" }, { "name": "user", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "description": "wallet that will send the bridge — optional, improves quote accuracy" } ], "responses": { "200": { "description": "Quote, including the unsigned deposit tx (to/value/data) for the caller to sign on fromChain" }, "400": { "description": "Invalid chain id, same fromChain/toChain, or invalid amount" }, "422": { "description": "relay.link could not build a route for this pair" } } } }, "/api/stockback/deck": { "get": { "summary": "List StockBack's earnable stock assets", "description": "StockBack pays a share of real ScanHood trading-fee revenue as real tokenized stock, not points. This lists the current Stock Deck: which real tokens are earnable and whether a reward auto-routes into a real covered-call yield vault. Read-only, no auth. See https://scanhood.xyz/stockback/whitepaper/ for the full mechanism.", "responses": { "200": { "description": "Current Stock Deck", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "deck": { "type": "object", "description": "Keyed by asset symbol (e.g. NVDA, AAPL)", "additionalProperties": { "type": "object", "properties": { "token": { "type": "string", "description": "ERC-20 address of the real stock token" }, "decimals": { "type": "integer" }, "hasYieldVault": { "type": "boolean" }, "yieldVault": { "type": "string", "nullable": true } } } } } } } } } } } }, "/api/stockback/vault": { "get": { "summary": "Read a wallet's real StockBack balances", "description": "Real Pending/Funded/Claimed state for one wallet, read directly from StockBack's ledger — Pending is a promised USD value not yet backed by a purchase, Funded means a real on-chain stock purchase has already confirmed and is waiting to be claimed, Claimed means it's already been sent to the wallet. Read-only, no auth, works for any wallet address whether or not it has ever earned anything.", "parameters": [ { "name": "wallet", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "description": "wallet address to look up" } ], "responses": { "200": { "description": "Real vault state for this wallet", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "wallet": { "type": "string" }, "pendingUsd": { "type": "object", "description": "Keyed by asset symbol, USD value promised but not yet backed" }, "fundedTokens": { "type": "object", "description": "Keyed by asset symbol, real token amount confirmed-purchased and claimable" }, "claimedTokens": { "type": "object", "description": "Keyed by asset symbol, real token amount already sent to this wallet" } } } } } }, "400": { "description": "wallet param missing or not a valid address" } } } } } }