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:

{
  "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

{
  "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

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

{
  "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

curl -X GET https://api.retinaos.xyz/v1/alerts \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "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
}

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.

Authentication

Learn how to generate and use API keys.

Tokens

List and filter tokens, and fetch full token profiles.

Wallets

Retrieve wallet profiles, portfolios, and trade history.

Scores

Access Cortex reputation and risk scores with dimension breakdowns.