# Roach Agent API

> Solana token holder analysis (who holds a coin, how concentrated it is, linked wallets, fresh and sniper wallets) and Bag Watch alerts, for AI agents. One credit ledger is shared by REST and MCP.

Base URL: https://api.stillroach.com. Human docs: https://app.stillroach.com/docs. Agent setup guide: https://app.stillroach.com/setup.md. Auth: `Authorization: Bearer rk_live_...`. Get a key at https://app.stillroach.com/watch#keys: sign in with a Solana wallet, create the key, buy credit packs (stored hashed and shown once; making a new key revokes the old one). Bag Watch plans add monthly API credits to the same wallet.

## Pricing
- Free: up to 10 credits/month on a wallet-signed key. The basic check (cached data) is free.
- Lite read (depth=lite: top-10 holders, dev stake, launch buy / dev sold, KOL wallets, basic flags): 3 fresh reads per day free, then 1 credit. Cached lite reads cost 0.
- 1 credit = one fresh full analysis. A cached result inside your max_data_age_seconds costs 0.
- Bag Watch plans include 400 (Watch) or 1,000 (Plus) credits/month. $STILL holder tiers add credits.
- Credit packs: 100 credits for 0.05 SOL or 5 USDC, or $STILL at 20% off. Solana only; no cards. Pack credits last 12 months and are used after the monthly pool runs out.
- Monthly pool: refills every 30 days from your start date (Bag Watch plan start, the day your $STILL tier was first granted, or your first key). Full pool from day one; unused monthly credits do not roll over. GET /v1/quota returns pool_resets_at. Every payment transaction counts once.
- Keyless pay per call (x402 v2, USDC on Solana): lite 0.02 USDC; full 0.08 USDC fresh, 0.02 cached; AI read +0.04 (full only). Payment is settled only after a successful scan.

## Endpoints
- [OpenAPI 3.1](/openapi.json): the full contract
- [MCP setup](/docs/mcp-setup.md): connect Claude, Cursor, Grok Bot or any MCP client to /mcp
- POST /v1/token-analysis {mint, depth: basic|lite|full, max_data_age_seconds}: analysis, schema roach.analysis.v1. Send an Idempotency-Key header to make retries safe.
- GET /v1/quota: credits left (monthly pool + packs)
- GET /v1/watch/report/{mint}, GET /v1/alerts?since=: Bag Watch (Watch plan)
- POST /v1/webhooks {url}: signed alert push (Watch plan). Standard Webhooks headers webhook-id (= alert_id, so dedupe on it), webhook-timestamp and webhook-signature (v1, HMAC-SHA256 with the whsec_ secret shown once). Reject timestamps more than 5 minutes off. Non-2xx replies retry at 1m, 5m, 30m, 2h, 6h and 24h, then go to dead_letters (visible in /v1/alerts).
- GET /v1/packs, POST /v1/packs/quote {kind: sol|usdc|still}, POST /v1/packs/verify {quote_id, signature}: buy credits on-chain
- POST /x402/v1/token-analysis {mint, depth: lite|full, include_ai, max_data_age_seconds}: keyless. The first reply is 402 with a PAYMENT-REQUIRED header; retry with PAYMENT-SIGNATURE within 120 s.
- GET /.well-known/x402: x402 discovery manifest (resources, input schema, prices).

## Result fields: operators, dump impact, wallet memory (full depth)
- result.holders.bundles.operators: top holders grouped into people by funding and trading links. wallets = top wallets checked; people = upper bound on the people behind them; top_operator_pct_supply (% of total supply) = the biggest linked group; operators[] lists linked groups with short addresses, links and confidence. Exchange-only links never merge people.
- result.checks.dump_impact: price_change_pct (negative %) if the top operator sold the whole bag in one go. venue curve (bonding curve) or amm (pool vaults read on-chain) is high confidence; approx (sized from reported liquidity) is low confidence and the real drop is likely bigger. Fees and other traders are ignored; a worst case, not a prediction.
- result.checks.wallet_memory: holders that were snipers, bundlers or the dev on coins scanned before and held nothing at that scan (repeat_dumpers, repeat_dumpers_pct_supply, dev_prior_dumps). Only covers coins already scanned; empty memory says so.
- result.verdict.info_codes: LINKED_WALLETS_HOLD_5PCT_PLUS, TOP_OPERATOR_DUMP_OVER_50PCT, REPEAT_DUMPERS_IN_HOLDERS, DEV_DUMPED_BEFORE. Informational; they never change the label.

## MCP tools
check_solana_token_basic, analyze_solana_token, watch_report, alerts_since, get_quota, get_credit_packs

## Errors
JSON `{error, message}`. 429 quota_exhausted includes pack_url, plan_url and x402_url. 429 rate_limited includes Retry-After. 502 scan_failed costs nothing. include_ai is not enabled yet (409 ai_unavailable, nothing charged); once enabled, a failed AI step returns the holder result with ai.status=ai_unavailable and refunds the AI credit (x402: nothing is settled).