> ## 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.

# RetinaOS Public API: On-Chain Data for Developers and Agents

> The RetinaOS Public API gives programmatic access to token data, wallet profiles, Cortex scores, and on-chain events from Robinhood Chain.

The RetinaOS Public API exposes the same data that powers Retina Terminal — token profiles, wallet reputation scores, on-chain events, and AI summaries — as structured JSON endpoints. It is designed for developers, quantitative traders, and agent builders who want to integrate Robinhood Chain intelligence into their own tools.

## Base URL

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

## Available Endpoints

| Endpoint                  | Method    | Description                    |
| ------------------------- | --------- | ------------------------------ |
| `/tokens`                 | GET       | List and filter tokens         |
| `/tokens/:address`        | GET       | Full token profile             |
| `/wallets/:address`       | GET       | Wallet profile and portfolio   |
| `/scores/token/:address`  | GET       | Cortex token risk score        |
| `/scores/wallet/:address` | GET       | Cortex wallet reputation score |
| `/events`                 | GET       | On-chain event stream          |
| `/alerts`                 | GET, POST | Manage user alerts             |

## Request Format

* All requests use HTTPS
* Authentication via `Authorization: Bearer YOUR_API_KEY` header
* JSON responses with `Content-Type: application/json`
* Pagination via `page` and `limit` query params

## Response Envelope

All list endpoints return:

```json theme={null}
{
  "data": [...],
  "total": 1000,
  "page": 1,
  "limit": 50
}
```

Single-resource endpoints return the object directly.

## Rate Limits

| Plan     | Requests per day | Requests per minute |
| -------- | ---------------- | ------------------- |
| Free     | 100              | 10                  |
| Pro      | 10,000           | 60                  |
| API Tier | Usage-based      | Custom              |

When you exceed a rate limit, the API returns HTTP 429 with a `Retry-After` header.

## Error Codes

| HTTP Status | Code             | Meaning                               |
| ----------- | ---------------- | ------------------------------------- |
| 400         | `INVALID_PARAMS` | Missing or malformed query parameters |
| 401         | `UNAUTHORIZED`   | Missing or invalid API key            |
| 403         | `FORBIDDEN`      | Feature not available on your plan    |
| 404         | `NOT_FOUND`      | Token or wallet address not indexed   |
| 429         | `RATE_LIMITED`   | Daily or per-minute limit exceeded    |
| 500         | `SERVER_ERROR`   | Internal error — retry after a moment |

## Versioning

The API is versioned via the URL path (`/v1/`). Breaking changes will increment the version. Non-breaking additions are made without a version bump.

## Alerts Endpoints

Alerts let you create notification triggers that fire when on-chain conditions match your criteria — for example, a new token under a given market cap with no critical risk flags. The following two endpoints manage user alerts programmatically.

### POST /alerts — Create an Alert

```
POST https://api.retinaos.xyz/v1/alerts
```

Create a new alert with a filter condition. The API returns the created alert object with a system-assigned `id`.

#### Request Body

```json theme={null}
{
  "name": "New low-cap token alert",
  "conditions": {
    "max_market_cap_usd": 2000000,
    "min_liquidity_usd": 100000,
    "exclude_flags": ["wash_trading", "concentrated_ownership"]
  },
  "notification_channel": "email"
}
```

| Field                  | Type   | Required | Description                                                        |
| ---------------------- | ------ | -------- | ------------------------------------------------------------------ |
| `name`                 | string | Yes      | Human-readable label for the alert                                 |
| `conditions`           | object | Yes      | Filter conditions — same field names as `GET /tokens` query params |
| `notification_channel` | string | No       | Delivery method: `email` (default)                                 |

#### Example Request

```bash theme={null}
curl -X POST https://api.retinaos.xyz/v1/alerts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New low-cap token alert",
    "conditions": {
      "max_market_cap_usd": 2000000,
      "min_liquidity_usd": 100000,
      "exclude_flags": ["wash_trading", "concentrated_ownership"]
    },
    "notification_channel": "email"
  }'
```

#### Example Response

```json theme={null}
{
  "id": "alert_01HXYZ123",
  "name": "New low-cap token alert",
  "status": "active",
  "conditions": {
    "max_market_cap_usd": 2000000,
    "min_liquidity_usd": 100000,
    "exclude_flags": ["wash_trading", "concentrated_ownership"]
  },
  "notification_channel": "email",
  "created_at": "2025-01-15T09:00:00Z"
}
```

### GET /alerts — List Active Alerts

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

Returns all alerts associated with the authenticated API key. Alerts are scoped to the key used to create them.

#### Example Request

```bash theme={null}
curl -X GET https://api.retinaos.xyz/v1/alerts \
  -H "Authorization: Bearer YOUR_API_KEY"
```

#### Example Response

```json theme={null}
{
  "data": [
    {
      "id": "alert_01HXYZ123",
      "name": "New low-cap token alert",
      "status": "active",
      "conditions": {
        "max_market_cap_usd": 2000000,
        "min_liquidity_usd": 100000,
        "exclude_flags": ["wash_trading", "concentrated_ownership"]
      },
      "notification_channel": "email",
      "created_at": "2025-01-15T09:00:00Z",
      "last_triggered_at": "2025-01-15T11:42:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 50
}
```

<Note>
  Free tier accounts can have up to 3 active alerts. Pro and API Tier accounts support unlimited alerts. Alerts that exceed the plan limit return HTTP 403.
</Note>

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api/authentication">
    Learn how to generate and use API keys.
  </Card>

  <Card title="Tokens" icon="coin" href="/api/tokens">
    List and filter tokens, and fetch full token profiles.
  </Card>

  <Card title="Wallets" icon="user" href="/api/wallets">
    Retrieve wallet profiles, portfolios, and trade history.
  </Card>

  <Card title="Scores" icon="star" href="/api/scores">
    Access Cortex reputation and risk scores with dimension breakdowns.
  </Card>
</CardGroup>