> ## Documentation Index
> Fetch the complete documentation index at: https://retinaos.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Tokens API: List and Profile Tokens on Robinhood Chain

> Use GET /tokens to list and filter tokens on Robinhood Chain, and GET /tokens/:address for a full token profile including AI summary and risk score.

The Tokens API gives you programmatic access to the same token data that powers the Retina Terminal discovery feed and token pages. Use it to build custom filters, feed automated strategies, or pull AI summaries for any indexed token.

## GET /tokens — List Tokens

```
GET https://api.retinaos.xyz/v1/tokens
```

### Query Parameters

<ParamField query="sort" type="string">
  Sort order. Options: `trending` (default), `newest`, `liquidity`, `volume`, `risk_asc`.
</ParamField>

<ParamField query="min_liquidity_usd" type="number">
  Minimum liquidity in USD.
</ParamField>

<ParamField query="max_market_cap_usd" type="number">
  Maximum market cap in USD.
</ParamField>

<ParamField query="min_market_cap_usd" type="number">
  Minimum market cap in USD.
</ParamField>

<ParamField query="max_risk_score" type="number">
  Maximum Cortex risk score (0–100).
</ParamField>

<ParamField query="exclude_flags" type="string">
  Comma-separated list of risk flags to exclude: `wash_trading`, `liquidity_pulled`, `concentrated_ownership`, `sybil_cluster`, `smart_money_exiting`.
</ParamField>

<ParamField query="min_holder_growth_1h_pct" type="number">
  Minimum % holder growth in the past hour.
</ParamField>

<ParamField query="max_age_hours" type="number">
  Maximum token age in hours.
</ParamField>

<ParamField query="page" type="integer">
  Page number (default: 1).
</ParamField>

<ParamField query="limit" type="integer">
  Results per page (default: 50, max: 200).
</ParamField>

### Example Request

```bash theme={null}
curl -X GET "https://api.retinaos.xyz/v1/tokens?sort=trending&max_market_cap_usd=2000000&min_liquidity_usd=100000&exclude_flags=wash_trading" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Example Response

```json theme={null}
{
  "data": [
    {
      "address": "0xabc123...",
      "name": "ExampleToken",
      "symbol": "EXT",
      "market_cap_usd": 1200000,
      "volume_24h_usd": 340000,
      "liquidity_usd": 180000,
      "holder_count": 412,
      "age_hours": 14,
      "risk_score": 28,
      "risk_flags": [],
      "ai_summary": "Momentum building since 06:00 UTC...",
      "launchpad": "PumpFun"
    }
  ],
  "total": 237,
  "page": 1,
  "limit": 50
}
```

## GET /tokens/:address — Token Profile

```
GET https://api.retinaos.xyz/v1/tokens/{address}
```

### Path Parameter

<ParamField path="address" type="string" required>
  The on-chain contract address of the token.
</ParamField>

### Example Response

```json theme={null}
{
  "address": "0xabc123...",
  "name": "ExampleToken",
  "symbol": "EXT",
  "market_cap_usd": 1200000,
  "volume_24h_usd": 340000,
  "liquidity_usd": 180000,
  "holder_count": 412,
  "age_hours": 14,
  "risk_score": 28,
  "risk_flags": [],
  "ai_summary": "Momentum building since 06:00 UTC driven by 3 Early Mover wallets. Liquidity stable at $180K.",
  "top_holders": [
    {
      "address": "0xdef456...",
      "holding_pct": 8.4,
      "classification": "Early Mover",
      "reputation_score": 83,
      "net_activity": "accumulating"
    }
  ],
  "launchpad": "PumpFun",
  "created_at": "2025-01-15T06:00:00Z"
}
```