# HoodSniper Base — paper trading for AI agents

> HoodSniper Base is a PAPER-trading app for new tokens on Base. Agents can read the live market and place paper orders on the key owner's own account. No real money, wallet or signature is ever involved through this API.

## Start here
- [Quickstart](https://base.46.225.83.168.nip.io/agents/quickstart): health → sandbox key → market → paper order → MCP over curl → client config → clean-up, in order, copy-paste curl
- [Agent API docs](https://base.46.225.83.168.nip.io/docs/agent-api): keys, endpoints, order types, error codes, curl/Python/JS examples
- [OpenAPI 3.1](https://base.46.225.83.168.nip.io/api/agent/v1/openapi.json): machine-readable description
- [Public markets, no key](https://base.46.225.83.168.nip.io/api/agent/v1/public/markets?limit=20): live tokens, read-only, 30 requests a minute per IP
- [MCP endpoint](https://base.46.225.83.168.nip.io/api/agent/v1/mcp): Streamable HTTP (JSON responses), same Bearer key; tools for markets, portfolio, analytics, trades and paper orders

## Auth
- Send `Authorization: Bearer hsk_…`. A person creates the key after signing in (Trade → 🤖 API keys) and chooses read or read+trade, and optionally an expiry. 60 requests a minute per account.
- Errors are JSON: `{"error": "...", "code": "RATE_LIMITED", "status": 429}`. Branch on `code`, not on the sentence.

## Notes
- Tokens are Base contract addresses; the paper bot fills queued orders within about a minute.
- Send an `Idempotency-Key` header on POST /orders so a retry never places a second order.
- Filter markets (keyed /markets and the public one): `measured=1` (leave out Uniswap v4 depth estimates; rows carry `liquidityEstimated` and `hooked`), `minLiquidityUsd=5000` (unknown depth is left out), `maxAgeMin=30` (new launches only; unknown age is left out), `token=0x…` and `pair=0x…` (case-insensitive).
- Every market row has `symbolFlags` (empty when clean) and `symbolWarning`: `invisible`, `mixedScript`, `lookalike`, `glyphs`, `major` (imitates a major's ticker, or isn't its official contract) and `majorTicker` (a major's exact ticker we can't verify). Flagged tokens are never hidden: decide for yourself.
- EVM market rows also carry `issuer` ({name, kind: stable|wrapped|stock, symbol} when the contract is a verified issuer asset, else null) and `stockRef` (official Robinhood Stock Tokens only: Robinhood's own bid/ask for the underlying × the token's multiplier, `refUsd`, `premiumPct` of this pool vs that mid, `halted`, `quotedAt`; null elsewhere or with no quote). Premium/discount scan: `/markets?stocks=1&sort=premium` (or the public one) lists only official Stock Tokens, widest gap first. Outside US market hours the quote can be stale.
- Health: `GET /api/agent/v1/status` (no key) says ok/degraded and how fresh the market feed is; `GET /api/agent/v1/changelog` lists API changes, newest first.
- Poll cheaply: keyed GET answers and /public/markets carry a weak `ETag`. Send it back as `If-None-Match` and an unchanged answer is a body-less 304 (it still counts toward the rate limit).
- Market data is about a minute behind and indicative. Nothing here is financial advice.