{"openapi":"3.1.0","info":{"title":"HoodSniper agent API (Robinhood Chain, paper + real money from your own wallet)","version":"1.3.0","description":"Read the market and place PAPER orders for your own account. Opt-in real money (Robinhood only): unsigned transactions for your own wallet. There is no HoodSniper platform fee right now. Network gas still applies. Terms: /terms  Risks: /risks  Privacy: /privacy. Nothing here is financial advice."},"servers":[{"url":"https://hoodsniper.fun/api/agent/v1"}],"components":{"securitySchemes":{"key":{"type":"http","scheme":"bearer","description":"hsk_… key from More → 🤖 API / Agents"}},"schemas":{"Order":{"type":"object","required":["type"],"properties":{"type":{"enum":["buy","sell","limit","exits","cancel"]},"token":{"type":"string","description":"token contract (buy, limit)"},"pair":{"type":"string","description":"position's pool address (sell, exits)"},"usd":{"type":"number","minimum":1,"description":"paper dollars to spend (buy, limit)"},"portion":{"type":"number","minimum":0.01,"maximum":1,"description":"share of the position to sell (sell; default all)"},"priceUsd":{"type":"number","description":"limit price, USD per token (limit). Fills when the price is at or below it."},"ttlMin":{"type":"integer","minimum":5,"maximum":10080,"description":"how long a limit waits (default 1440)"},"tpPct":{"type":"number","minimum":1,"maximum":10000,"description":"take profit, % above entry (limit, exits)"},"slPct":{"type":"number","minimum":1,"maximum":99,"description":"stop loss, % below entry (limit, exits)"},"trailPct":{"type":"number","minimum":1,"maximum":90,"description":"trailing stop, % below the peak (limit, exits)"},"ref":{"type":"string","description":"id of the limit order to cancel (cancel)"}}},"Error":{"type":"object","required":["error","code","status"],"properties":{"error":{"type":"string","description":"a sentence for people; may change"},"code":{"enum":["AGENT_API_OFF","COOKIE_NOT_ACCEPTED","KEY_MISSING","KEY_UNKNOWN","ACCOUNT_UNAVAILABLE","SCOPE_REQUIRED","BAD_ORDER_TYPE","ORDER_REJECTED","BAD_IDEMPOTENCY_KEY","IDEMPOTENCY_CONFLICT","BAD_ORIGIN","NOT_FOUND","ORDER_NOT_FOUND","METHOD_NOT_ALLOWED","PAYLOAD_TOO_LARGE","RATE_LIMITED","INTERNAL"],"description":"stable: branch on this"},"status":{"type":"integer"},"docs":{"type":"string"}}}}},"paths":{"/me":{"get":{"summary":"Who this key is","description":"Key name and scopes, the account and the chain.","security":[{"key":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"KEY_MISSING, KEY_UNKNOWN or COOKIE_NOT_ACCEPTED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"ACCOUNT_UNAVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: over 60 requests a minute (Retry-After header)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/real/limits":{"get":{"summary":"Real-money access for this key","description":"Robinhood only. Bound wallet, fee (currently off unless feeBps > 0), per-trade/daily caps, used and left today.","security":[{"key":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"KEY_MISSING, KEY_UNKNOWN or COOKIE_NOT_ACCEPTED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"ACCOUNT_UNAVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: over 60 requests a minute (Retry-After header)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/real/quote":{"post":{"summary":"Real-money quote (no transaction)","description":"Needs the real scope (switched on by the key owner, bound to one wallet). Body {side:\"buy\",token,usd} or {side:\"sell\",token,portion}. There is no HoodSniper platform fee right now. Network gas still applies.","security":[{"key":[]}],"responses":{"200":{"description":"quote"},"400":{"description":"REAL_REFUSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"REAL_OFF, REAL_SCOPE_REQUIRED or REAL_CAP","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/real/build":{"post":{"summary":"Build UNSIGNED real-money transactions","description":"Same body as /real/quote. Returns txs[] to sign and send from the bound wallet. There is no HoodSniper platform fee right now. Network gas still applies. HoodSniper never signs or sends.","security":[{"key":[]}],"responses":{"200":{"description":"{ unsigned: true, txs, quote, fee }"},"400":{"description":"REAL_REFUSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"REAL_OFF, REAL_SCOPE_REQUIRED or REAL_CAP","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/real/confirm":{"post":{"summary":"Record a sent real swap","description":"Body {txHash}. Verified on-chain: success, from the bound wallet, exactly the transaction built for this key. 202 while pending. HoodSniper does not sign or send the swap.","security":[{"key":[]}],"responses":{"200":{"description":"recorded"},"202":{"description":"pending"},"400":{"description":"REAL_CONFIRM_REFUSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"REAL_OFF or REAL_SCOPE_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/markets":{"get":{"summary":"Live tokens","description":"The Pond: tokens trading now on this chain, measured depth first, then estimates; deepest first. Each row has symbolFlags (invisible, mixedScript, lookalike, glyphs, major, majorTicker; empty when clean) and symbolWarning; flagged tokens are never left out. EVM rows also have issuer ({name, kind, symbol} for a verified stablecoin / wrapped coin / Robinhood Stock Token, else null) and stockRef (Robinhood Stock Tokens: bidUsd, askUsd, refUsd = Robinhood's quote × multiplier, premiumPct of this pool vs that mid, halted, quotedAt; else null). ?limit=1..200, ?measured=1, ?minLiquidityUsd=, ?maxAgeMin=, ?stocks=1, ?sort=premium","security":[{"key":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"KEY_MISSING, KEY_UNKNOWN or COOKIE_NOT_ACCEPTED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"ACCOUNT_UNAVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: over 60 requests a minute (Retry-After header)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","maximum":200}},{"name":"measured","in":"query","schema":{"type":"string","enum":["1"]},"description":"measured depth only (leave out Uniswap v4 estimates)"},{"name":"minLiquidityUsd","in":"query","schema":{"type":"number","minimum":0},"description":"USD liquidity floor; unknown depth is left out"},{"name":"maxAgeMin","in":"query","schema":{"type":"number","minimum":0},"description":"only pools younger than N minutes (new launches); unknown age is left out"},{"name":"token","in":"query","schema":{"type":"string"},"description":"one token: all its pools"},{"name":"pair","in":"query","schema":{"type":"string"},"description":"one pool (pair address or v4 pool id)"},{"name":"stocks","in":"query","schema":{"type":"string","enum":["1"]},"description":"Robinhood Chain: only official Robinhood Stock Tokens"},{"name":"sort","in":"query","schema":{"type":"string","enum":["premium"]},"description":"premium: widest gap between this pool and Robinhood's quote first (stockRef.premiumPct, either side); ranked before ?limit"}]}},"/radar":{"get":{"summary":"Radar","description":"New pools the bot sees on this chain, the launch funnel and the top reasons it skipped tokens (the Radar page). Read-only.","security":[{"key":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"KEY_MISSING, KEY_UNKNOWN or COOKIE_NOT_ACCEPTED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"ACCOUNT_UNAVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: over 60 requests a minute (Retry-After header)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/portfolio":{"get":{"summary":"Paper portfolio","description":"Cash, equity, open positions with their exit rules, waiting limit orders and recent orders.","security":[{"key":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"KEY_MISSING, KEY_UNKNOWN or COOKIE_NOT_ACCEPTED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"ACCOUNT_UNAVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: over 60 requests a minute (Retry-After header)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/analytics":{"get":{"summary":"PnL analytics","description":"Win rate, profit factor, expectancy, drawdown, streaks, equity curve, by strategy and by day.","security":[{"key":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"KEY_MISSING, KEY_UNKNOWN or COOKIE_NOT_ACCEPTED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"ACCOUNT_UNAVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: over 60 requests a minute (Retry-After header)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/status":{"get":{"summary":"Service status, no key","description":"ok / degraded, market-feed age, Robinhood quotes (Robinhood Chain), 24-h uptime and feed freshness from this app's own minute samples (restarts count as down). CORS, cached 10 s.","security":[],"responses":{"200":{"description":"OK"}}}},"/changelog":{"get":{"summary":"API changelog, no key","description":"Agent-facing API changes, newest first: { entries: [{ date, kind, area, text }] }.","security":[],"responses":{"200":{"description":"OK"}}}},"/public/markets":{"get":{"summary":"Live tokens, no key","description":"Read-only, no key needed. Same rows as /markets. 30 requests a minute per IP, cached 15 s. ?limit=1..200, ?measured=1, ?minLiquidityUsd=, ?maxAgeMin=, ?stocks=1, ?sort=premium","security":[],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","maximum":200}},{"name":"measured","in":"query","schema":{"type":"string","enum":["1"]},"description":"measured depth only (leave out Uniswap v4 estimates)"},{"name":"minLiquidityUsd","in":"query","schema":{"type":"number","minimum":0},"description":"USD liquidity floor; unknown depth is left out"},{"name":"maxAgeMin","in":"query","schema":{"type":"number","minimum":0},"description":"only pools younger than N minutes (new launches); unknown age is left out"},{"name":"token","in":"query","schema":{"type":"string"},"description":"one token: all its pools"},{"name":"pair","in":"query","schema":{"type":"string"},"description":"one pool (pair address or v4 pool id)"},{"name":"stocks","in":"query","schema":{"type":"string","enum":["1"]},"description":"Robinhood Chain: only official Robinhood Stock Tokens"},{"name":"sort","in":"query","schema":{"type":"string","enum":["premium"]},"description":"premium: widest gap between this pool and Robinhood's quote first (stockRef.premiumPct, either side); ranked before ?limit"}],"responses":{"200":{"description":"OK"},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/trades":{"get":{"summary":"Closed trades","description":"Your closed paper trades, newest last. ?limit=1..500. ?format=csv returns all of them as a CSV file.","security":[{"key":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"KEY_MISSING, KEY_UNKNOWN or COOKIE_NOT_ACCEPTED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"ACCOUNT_UNAVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: over 60 requests a minute (Retry-After header)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","maximum":500}},{"name":"format","in":"query","schema":{"enum":["json","csv"]}}]}},"/mcp":{"post":{"summary":"MCP endpoint (Streamable HTTP, JSON responses)","description":"One JSON-RPC 2.0 message per POST: initialize, tools/list, tools/call, ping. Same Bearer key, scopes and rate limit as the REST API. No SSE stream (GET returns 405), no sessions.","security":[{"key":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"JSON-RPC response"},"202":{"description":"notification accepted"},"401":{"description":"key problems","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"BAD_ORIGIN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sandbox":{"post":{"summary":"Create a 24-hour sandbox account + key (no key needed)","description":"$1,000 paper, read + trade key, deleted after 24 h. 3 a day per IP. Not ranked.","security":[],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":30}}}}}},"responses":{"201":{"description":"{ key, keyId, scopes, account, paperUsd, expires }"},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"SANDBOX_FULL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"End your sandbox now (its key, paper book and events are deleted)","description":"Frees its place in the shared sandbox cap. Sandbox keys only.","security":[{"key":[]}],"responses":{"200":{"description":"{ ok, deleted }"},"400":{"description":"NOT_SANDBOX","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"SCOPE_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sandbox/reset":{"post":{"summary":"Reset a sandbox paper book to $1,000","security":[{"key":[]}],"responses":{"200":{"description":"OK"},"400":{"description":"NOT_SANDBOX","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"SCOPE_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/events":{"get":{"summary":"Event feed","description":"order.accepted, order.filled, order.expired, order.cancelled, order.failed, trade.opened, trade.closed, alert.fired, ping. ?after=<seq>&limit=1..200","security":[{"key":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"KEY_MISSING, KEY_UNKNOWN or COOKIE_NOT_ACCEPTED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"ACCOUNT_UNAVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: over 60 requests a minute (Retry-After header)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"after","in":"query","schema":{"type":"integer"}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":200}}]}},"/events/stream":{"get":{"summary":"Server-Sent Events stream of the event feed","description":"text/event-stream. data lines are {t, signature, payload}. Resumes from Last-Event-ID. 2 per account.","security":[{"key":[]}],"responses":{"200":{"description":"text/event-stream"},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks":{"get":{"summary":"List webhooks","description":"Your webhooks with fails, lastOk and lastError.","security":[{"key":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"KEY_MISSING, KEY_UNKNOWN or COOKIE_NOT_ACCEPTED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"ACCOUNT_UNAVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: over 60 requests a minute (Retry-After header)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Add a signed webhook (trade key)","security":[{"key":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"enum":["order.accepted","trade.opened","trade.closed","alert.fired","ping"]}}}}}}},"responses":{"201":{"description":"{ hook, signingSecret? }"},"400":{"description":"BAD_WEBHOOK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}":{"delete":{"summary":"Delete a webhook","security":[{"key":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}/test":{"post":{"summary":"Send a signed ping to a webhook","security":[{"key":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"queued"}}}},"/signing-secret":{"post":{"summary":"Create or rotate the signing secret (shown once)","security":[{"key":[]}],"responses":{"200":{"description":"{ signingSecret }"}}}},"/leaderboard":{"get":{"summary":"Your leaderboard listing","description":"listed, name, minTrades.","security":[{"key":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"KEY_MISSING, KEY_UNKNOWN or COOKIE_NOT_ACCEPTED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"ACCOUNT_UNAVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED: over 60 requests a minute (Retry-After header)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Opt in to / out of the public agent board (trade key)","security":[{"key":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"listed":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK"},"400":{"description":"BAD_NAME or SANDBOX_NOT_RANKED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"NAME_TAKEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/chains":{"get":{"summary":"Every HoodSniper chain's agent endpoints, no key","description":"Base URLs, MCP URLs and order types for all chains. Use one key per chain.","security":[],"responses":{"200":{"description":"OK"}}}},"/public/leaderboard":{"get":{"summary":"Public agent leaderboard, no key","description":"Paper results only, opt-in agents with 3+ closed trades.","security":[],"responses":{"200":{"description":"OK"},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders":{"get":{"summary":"Your last 50 paper orders with their status","description":"status: queued, waiting, filled, failed, expired, cancelled, rejected, done or ended. ?id= returns one order as { order }; ?status= filters.","security":[{"key":[]}],"parameters":[{"name":"id","in":"query","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["queued","waiting","filled","failed","expired","cancelled","rejected","done","ended"]}}],"responses":{"200":{"description":"{ orders: [...] } or { order }"},"404":{"description":"ORDER_NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Place a paper order","description":"Needs a key with the trade scope. Orders are queued and the bot fills them within about a minute. Send an Idempotency-Key header so a retry never places a second order.","security":[{"key":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{8,64}$"},"description":"Same key + same body within 24 h returns the first answer (replayed: true); same key + different body returns 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"responses":{"200":{"description":"queued: { ok, id }"},"400":{"description":"BAD_ORDER_TYPE, ORDER_REJECTED or BAD_IDEMPOTENCY_KEY","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"SCOPE_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"IDEMPOTENCY_CONFLICT","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}