# TokenRanker — Agent API documentation

TokenRanker is a real-time on-chain token ranking platform for the **Robinhood chain**. Every token pair is enriched with market metrics (price, liquidity, 24h volume and change), an **AI risk audit** (0–100 score with a plain-language summary), and **X/Twitter engagement** (followers, posts, views, replies, retweets, likes over 1h/24h/48h windows). All data is public and read-only.

The whole dataset is exposed three ways, all backed by the same live dumps refreshed every ~30 seconds:

1. **REST API** — versioned JSON endpoints under `/api/v1`, documented in [OpenAPI](https://tokenranker.xyz/openapi.json).
2. **MCP server** — a Model Context Protocol endpoint at `/mcp` (Streamable HTTP) so AI agents can query the data with tools and resources.
3. **Discovery files** — [`/llms.txt`](https://tokenranker.xyz/llms.txt), [`/llms-full.txt`](https://tokenranker.xyz/llms-full.txt), and a [server card](https://tokenranker.xyz/server-card) so agents find the rest without being told.

## Data model

Every pair is returned as a normalized object:

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Pair id (pair contract address, lowercase). |
| `token.name` | string | Token display name. |
| `token.address` | string | Token contract address (lowercase). |
| `token.type` | string | `EQUITY`, `BASE`, or `MEME`. |
| `token.website` / `token.xAccount` / `token.telegram` | string | Verified project links (may be empty). |
| `token.audit` | object or null | AI audit: `model`, `ts`, `score` (0–100, higher is safer), `summary`. |
| `quote.symbol` / `quote.address` | string | Quote currency (e.g. USDG, ETH) and its address. |
| `dex` | string | `V2`, `V3`, `V4`, `SW3`. |
| `price` | number | Current price in quote currency. |
| `chg24h` | number or null | 24h price change in percent. |
| `volume24h` | number | 24h volume in USD. |
| `liquidity` | number | Pool liquidity in USD. |
| `rank` | integer | Display rank (1 = highest). |
| `rankScore` | number | Raw rank score from the feed. |
| `ageMinutes` | integer | Pool age in minutes. |
| `createdAt` / `updatedAt` | integer (unix s) | Pool creation / last update. |
| `x.followers` | number | X account follower count. |
| `x.followerGrowth` | object | Follower growth rate (%) in `1h`, `24h`, `48h` windows. |
| `x.posts` / `x.views` / `x.replies` / `x.retweets` / `x.likes` | object | Engagement counts in `1h`, `24h`, `48h` windows. |

Example (trimmed):

```json
{
  "id": "0x0019150f6efdc622d69d1edc697dc79da477c232159e5b9e761aa1d08a1d4172",
  "token": {
    "name": "Send Nudes",
    "address": "0xbe98b75361935b18d688409424a869a4c3dc7401",
    "type": "MEME",
    "website": "",
    "xAccount": "https://x.com/SendNudesRH",
    "telegram": "",
    "audit": {
      "model": "hy3",
      "ts": 1788942164,
      "score": 18,
      "summary": "Rug behavior critical-red with 3 LP withdrawals in 24h; 195 bundler wallets hold 36.3% supply."
    }
  },
  "quote": { "symbol": "USDG", "address": "0x5fc5360d0400a0fd4f2af552add042d716f1d168" },
  "dex": "V4",
  "price": 0.0054,
  "chg24h": -28.3,
  "volume24h": 530000,
  "liquidity": 172780,
  "rank": 94,
  "rankScore": 20400000,
  "ageMinutes": 13275,
  "createdAt": 1788311018,
  "updatedAt": 1789107530,
  "x": {
    "followers": 2043,
    "followerGrowth": { "1h": 0, "24h": 0, "48h": 0.5 },
    "posts": { "1h": 2, "24h": 8, "48h": 15 },
    "views": { "1h": 434, "24h": 2421, "48h": 4100 },
    "replies": { "1h": 0, "24h": 3, "48h": 5 },
    "retweets": { "1h": 0, "24h": 2, "48h": 4 },
    "likes": { "1h": 1, "24h": 9, "48h": 14 }
  }
}
```

## REST API

Base URL: `https://<host>/api/v1`. All endpoints are `GET`, public, and CORS-enabled (`Access-Control-Allow-Origin: *`). Responses are wrapped as `{ "meta": {...}, "data": ... }`; errors as `{ "error": { "code", "message" } }` with an appropriate HTTP status.

| Endpoint | Description |
| --- | --- |
| `GET /api/v1` | Endpoint index and links to docs/OpenAPI/MCP. |
| `GET /api/v1/pairs` | All pairs, ranked, with filters and pagination. |
| `GET /api/v1/pairs/{idOrAddress}` | One pair by pair id, token address, or exact token name. |
| `GET /api/v1/hyped` | Hyped tokens, default sort `followerGrowth24h desc`. |
| `GET /api/v1/surge` | Surge-zone tokens, default sort `rank asc`. |
| `GET /api/v1/audits/{address}` | AI audit for one token address. |
| `GET /api/v1/stats` | Aggregate stats: totals, averages, breakdowns, top movers. |
| `GET /openapi.json` | Machine-readable OpenAPI 3.1 description of this API. |

Query parameters (lists and `/pairs`, `/hyped`, `/surge`):

| Param | Type | Description |
| --- | --- | --- |
| `q` | string | Substring match on token name, pair id, or token address. |
| `type` | string | Comma-separated: `EQUITY`, `BASE`, `MEME`. |
| `dex` | string | Comma-separated: `V2`, `V3`, `V4`, `SW3`. |
| `quote` | string | Comma-separated quote symbols (e.g. `USDG,ETH`). |
| `minLiq` / `minVol` | number | Minimum liquidity / 24h volume in USD. |
| `minScore` | number | Minimum AI audit score (0–100). |
| `hasAudit` | boolean | Only pairs with an audit. |
| `minFollowerGrowth24h` | number | Minimum 24h X follower growth rate (%). |
| `sort` | string | `rank`, `price`, `chg24h`, `volume24h`, `liquidity`, `ageMinutes`, `auditScore`, `followers`, `followerGrowth1h`, `followerGrowth24h`, `views1h`/`views24h`/`views48h`, `posts1h`/`posts24h`/`posts48h`, `createdAt`. |
| `order` | string | `asc` or `desc` (default `asc`). |
| `limit` | integer | 1–500 (default 100). |
| `offset` | integer | Pagination offset (default 0). |
| `dedupe` | boolean | Collapse rows for the same token quoted against multiple currencies (hyped/surge). |

Examples:

```bash
# Top 3 MEME pairs by 24h volume with an audit score of at least 60
curl -s 'https://<host>/api/v1/pairs?type=MEME&minScore=60&sort=volume24h&order=desc&limit=3'

# Everything about one token address
curl -s 'https://<host>/api/v1/pairs/0xbe98b75361935b18d688409424a869a4c3dc7401'

# Market stats
curl -s 'https://<host>/api/v1/stats'

# The audit alone
curl -s 'https://<host>/api/v1/audits/0xbe98b75361935b18d688409424a869a4c3dc7401'
```

## MCP endpoint

An MCP server is served at `/mcp` using **Streamable HTTP** (stateless, POST). Point any MCP client at it:

```json
{
  "mcpServers": {
    "tokenranker": {
      "type": "http",
      "url": "https://<host>/mcp"
    }
  }
}
```

Tools:

| Tool | Description |
| --- | --- |
| `list_pairs` | Ranked pairs with the same filters as `GET /api/v1/pairs`. |
| `get_pair` | One pair by id, token address, or exact name. |
| `list_hyped` | Hyped tokens by 24h follower growth (`dedupe` supported). |
| `list_surge` | Surge-zone tokens. |
| `get_token_audit` | AI risk audit for a token address. |
| `get_market_stats` | Aggregate market statistics. |

Resources (readable URIs):

| URI | Content |
| --- | --- |
| `tokenranker://stats` | Aggregate market stats (JSON). |
| `tokenranker://pairs/top` | Top 50 ranked pairs (JSON). |
| `tokenranker://pairs/hyped` | Top 50 hyped tokens (JSON). |
| `tokenranker://docs` | This documentation (Markdown). |

## Discovery files for agents

| Path | Purpose |
| --- | --- |
| `/llms.txt` | Curated markdown index of this site for LLMs and coding agents. |
| `/llms-full.txt` | This documentation, bundled as one file. |
| `/server-card` | MCP server card (JSON) describing the `/mcp` endpoint. |
| `/.well-known/mcp/catalog.json` | MCP catalog pointing at the server card. |
| `/robots.txt` | Crawler permissions (AI crawlers explicitly allowed). |

## Notes

- **Freshness**: dumps are rewritten by a background task roughly every 30 seconds; endpoints respond `Cache-Control: no-store` so agents always see the latest snapshot.
- **Staleness**: `updatedAt` / `meta.ts` tell you exactly how old the data is.
- **No auth**: the API is public and read-only. Do not send secrets to it.
- **Not financial advice**: ranking data is informational. TokenRanker makes no guarantees about accuracy or availability.