# Robinhood Chain API for AI agents

> Give an AI agent Robinhood Chain data with the Crius API: which endpoints to expose as tools, the OpenAPI document, structured errors and citing the block.

Source: https://docs.crius.sh/use-cases/ai-agents/ · Updated 2026-10-28

AI agents and LLM assistants are asked Robinhood Chain questions all the time: “is this token safe”, “what is it worth”, “who holds it”, “what launched on Pons today”. They can only answer from data they can fetch. The Crius API gives an agent a small set of tools that return compact JSON with plain decimal numbers, human-unit amounts and the block each answer reflects, plus errors that explain themselves. An agent can start without a key, and the OpenAPI document turns into tool definitions directly.

## Tools to give an agent

Expose a handful of tools rather than every endpoint. Models choose better from five clear tools than from thirty.

-   [GET`/search`](https://docs.crius.sh/reference/discovery/search/) name or symbol → address. Every other tool takes an address, so this comes first.
-   [GET`/token/{address}`](https://docs.crius.sh/reference/tokens/token-profile/) the one-call summary: price, market cap, liquidity, holders, launchpad, LP lock, links.
-   [GET`/token/{address}/security`](https://docs.crius.sh/reference/security/security-checks/) “is it safe”: `score`, `risk`, `flags`, taxes, honeypot.
-   [GET`/token/{address}/price`](https://docs.crius.sh/reference/tokens/token-price/) the cheapest call, for price questions and loops.
-   [GET`/token/{address}/candles`](https://docs.crius.sh/reference/trades/ohlcv-candles/) history questions (“how did it do this week”).
-   [GET`/v1/status`](https://docs.crius.sh/reference/chain/service-status/) a freshness check before answering “right now” questions.

Add [top traders](https://docs.crius.sh/reference/holders/top-traders/), [holders](https://docs.crius.sh/reference/holders/live-holders/) or [token lists](https://docs.crius.sh/reference/discovery/token-lists/) when your agent’s job needs them (holders and traders need a Free key).

## Suggested architecture

1.  **Generate tools from OpenAPI.** Fetch `https://api.crius.sh/openapi.json`, keep the endpoints you chose, and write a one-line description for each that says when to use it.
    
2.  **Resolve names before anything else.** Symbols aren’t unique on Robinhood Chain (three tokens match “charge”). Have the agent search, show the candidates with their addresses, and continue only with an address.
    
3.  **Give the agent its own key.** A dedicated key with only the `read` scope, an IP allow-list if it runs on a fixed host and its own rate limit. Revoke it from the dashboard at any time without touching your other keys.
    
4.  **Pass errors to the model as they are.** Errors have a stable `error.code` and a `message` written for people, so the agent can explain a missing plan or a rate limit in plain words.
    
5.  **Cite the block.** Ask the model to include `meta.block` in answers about prices, holders or risk.
    

Each tool call costs what the endpoint costs: 1 credit for search, profile, price and security, 2 for candles. An agent answering 2,000 questions a day with about four calls each uses roughly 8,000 to 16,000 credits a day, within the Free plan’s 1,000,000 a month.

## Errors an agent can explain

Example [Free plan · 2 credits](https://docs.crius.sh/reference/holders/live-holders/)

### A plan error with the fix in it

The agent called the holders endpoint without a key. What does it get back?

GET/v1/robinhood/token/0x7b8892cea949bc60d494681d1bc3ea96071ab0b8/holders

 

**cURL**

```bash
curl "https://api.crius.sh/v1/robinhood/token/0x7b8892cea949bc60d494681d1bc3ea96071ab0b8/holders" \
  -H "x-api-key: $CRIUS_API_KEY"
```

**JavaScript**

```js
const res = await fetch("https://api.crius.sh/v1/robinhood/token/0x7b8892cea949bc60d494681d1bc3ea96071ab0b8/holders", {
  headers: { "x-api-key": process.env.CRIUS_API_KEY },
});
const { data, meta } = await res.json();
```

**Python**

```python
import os, requests

r = requests.get(
    "https://api.crius.sh/v1/robinhood/token/0x7b8892cea949bc60d494681d1bc3ea96071ab0b8/holders",
    headers={"x-api-key": os.environ["CRIUS_API_KEY"]},
)
body = r.json()
print(body["data"])
```

**Real response 403 Captured Oct 28, 2026 · 10 lines (arrays trimmed)**

```json
{
  "error": {
    "code": "plan_required",
    "docs_url": "https://docs.crius.sh/plans-and-limits/",
    "message": "This endpoint needs an API key (Free plan or higher); you called it without one. To use it, get a free API key at https://dashboard.crius.sh.",
    "plan": "anon",
    "required_plan": "free",
    "upgrade_url": "https://dashboard.crius.sh"
  }
}
```

What this tells you

-   HTTP `403` with `error.code: "plan_required"`: the endpoint isn’t on the caller’s plan (`plan: "anon"`).
-   `required_plan: "free"` names the lowest plan that includes it, and `upgrade_url` says where to get it.
-   `message` is a full sentence the agent can relay as it is: the endpoint needs an API key, Free plan or higher.
-   The right reaction is to tell the user, not to retry. Retrying a `plan_required` error never succeeds.

[Live holders reference](https://docs.crius.sh/reference/holders/live-holders/) [Data looks wrong? Report it](mailto:support@crius.sh?subject=Wrong%20data%20in%20docs%20example%3A%20A%20plan%20error%20with%20the%20fix%20in%20it&body=Page%3A%20https%3A%2F%2Fdocs.crius.sh%2Fuse-cases%2Fai-agents%2F%23plan-error%0ARequest%3A%20GET%20%2Fv1%2Frobinhood%2Ftoken%2F0x7b8892cea949bc60d494681d1bc3ea96071ab0b8%2Fholders%0A%0AWhat's%20wrong%20or%20missing%3F%0A%0A)

## Check freshness first

Example [Anonymous · no key · free](https://docs.crius.sh/reference/chain/service-status/)

### Index status before a real-time answer

Is the Robinhood Chain index live, and how far behind the chain is it?

GET/v1/status

  

**cURL**

```bash
curl "https://api.crius.sh/v1/status"
```

**JavaScript**

```js
const res = await fetch("https://api.crius.sh/v1/status");
const { data, meta } = await res.json();
```

**Python**

```python
import requests

r = requests.get(
    "https://api.crius.sh/v1/status",
)
body = r.json()
print(body["data"])
```

**Real response 200 Captured Oct 28, 2026 · 21 lines (arrays trimmed)**

```json
{
  "data": {
    "chains": {
      "robinhood": {
        "addresses": 29509881,
        "block_age_ms": 1203,
        "chain_id": 4663,
        "finalized_block": 100397649,
        "indexed_block": 100406757,
        "lag_ms": 50,
        "pools": 2780862,
        "safe_block": 100401329,
        "start_block": 0,
        "status": "live",
        "tokens": 2406786
      }
    },
    "region": "rigel",
    "version": "0.1.0"
  }
}
```

What this tells you

-   `chains.robinhood.status: "live"`: the index is following the chain head. Other values are `catching_up`, `stalled` and `starting`.
-   `indexed_block: 100406757` with `lag_ms: 50`: the index was 50 ms behind the chain head when this was captured.
-   `tokens: 2406786`, `pools: 2780862` and `addresses: 29509881` are indexed, from `start_block: 0`.
-   An agent that sees anything but `live` should say its answer may be behind, and link [status.crius.sh](https://status.crius.sh).

[Service status reference](https://docs.crius.sh/reference/chain/service-status/) Runs from your browser on the anonymous plan [Data looks wrong? Report it](mailto:support@crius.sh?subject=Wrong%20data%20in%20docs%20example%3A%20Index%20status%20before%20a%20real-time%20answer&body=Page%3A%20https%3A%2F%2Fdocs.crius.sh%2Fuse-cases%2Fai-agents%2F%23status%0ARequest%3A%20GET%20%2Fv1%2Fstatus%0A%0AWhat's%20wrong%20or%20missing%3F%0A%0A)

```json
{
  "name": "robinhood_token_security",
  "description": "Safety check for a Robinhood Chain token: score 0-100, risk level, honeypot, buy and sell tax, owner powers, LP lock. Call it before saying whether a token is safe. Needs the token's 0x address (use robinhood_search first if you only have a name).",
  "parameters": {
    "type": "object",
    "properties": {
      "address": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Token contract address" }
    },
    "required": ["address"]
  }
}
```

The tool calls `GET https://api.crius.sh/v1/robinhood/token/{address}/security` and returns `data` and `meta.block` to the model. More on prompts, the docs files for models and key setup is in [Use the Crius API from AI agents](https://docs.crius.sh/guides/use-crius-with-ai-agents/) and [For AI agents & LLMs](https://docs.crius.sh/ai/).

## Frequently asked questions

**Can an AI assistant call the Crius API without an API key?**

Yes. Search, token profiles, prices, candles, trades, pools, the security check and chain stats are on the anonymous plan at 2 requests per second per IP. Give a production agent its own key with only the `read` scope for higher limits and the Free or paid endpoints.

**Is there an OpenAPI spec for the Crius API?**

Yes, at `https://api.crius.sh/openapi.json`. It lists every endpoint and parameter, so you can generate tool or function definitions from it. The docs are available to models as `llms.txt`, `llms-full.txt` and a Markdown version of every page.

**How should an agent handle rate limits and plan errors?**

Read `error.code`. On `rate_limited` wait `retry_after_ms` and retry; on `quota_exceeded` stop; on `plan_required` tell the user which plan the endpoint needs (`required_plan`) instead of retrying. Messages are written to be shown to people as they are.

**How can an agent show where its numbers come from?**

Every response has `meta.block` and `meta.block_ts`. Have the agent quote the block (for example "as of block 100406772") and link the token's address on an explorer, so a user can check the answer.

## Related

[Guide **AI agents** Give an AI agent Robinhood Chain data: Crius docs as llms.txt and Markdown, tool definitions from the OpenAPI document, an MCP server, and accuracy tips. Read](https://docs.crius.sh/guides/use-crius-with-ai-agents/) [Docs **For AI agents & LLMs** How AI assistants and agents can read the Crius documentation (llms.txt, llms-full.txt, Markdown pages) and call the Crius API (OpenAPI document, anonymous endpoints). Read](https://docs.crius.sh/ai/) [Guide **Get token data** Get a Robinhood Chain token's name, supply, price, market cap, holders, launchpad, liquidity lock and links in one API call. Real response, no API key needed. Read](https://docs.crius.sh/guides/get-token-data/) [Guide **Token security score** Score any Robinhood Chain token from 0 to 100 with one API call. Honeypot, buy and sell taxes, owner powers, LP locks, v4 hook risk and insider launches, with real examples. Read](https://docs.crius.sh/guides/token-security-score/) [Docs **Errors** Crius API error format, HTTP status codes and every error code with its meaning and what to do about it. Read](https://docs.crius.sh/errors/)