Zorvu Developer API
Programmatic access to the same automated risk checks that power zorvu.app/check for Robinhood Chain tokens. The API is in private preview. Keys are issued by invitation only; sell depth needs no key.
For tools and agents: /openapi.json (OpenAPI 3.1), /llms.txt and the MCP server at https://zorvu.app/mcp.
grade says what Zorvu's automated checks measured at the time of the data shown. It is not a recommendation and does not mean a token is safe to buy. Results are automated, may be incomplete or out of date, and are not financial advice. Low risk is not one of the grades this endpoint returns today, so passed_zorvu_safety_checks is always false here — see grade below.Endpoint
GET https://zorvu.app/api/v1/check?address=0x<40 hex characters> Authorization: Bearer <your API key>
Example request
curl -s "https://zorvu.app/api/v1/check?address=0xabc…" \ -H "Authorization: Bearer zv_live_…"
Limits (preview)
| Tier | Per minute | Per day |
|---|---|---|
| free | 10 | 100 |
| beta | 30 | 1,000 |
Daily limits reset at 00:00 UTC. Remaining quota is returned in x-ratelimit-remaining-minute and x-ratelimit-remaining-day. Limits may differ per key.
Errors
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_address | Address is not 0x plus 40 hex characters. |
| 401 | missing_key | No Bearer key was sent. |
| 401 | invalid_key | Key is unknown or revoked. |
| 429 | rate_limited_minute / _day | Limit reached. See retry-after. |
| 503 | unavailable | Temporary outage. Retry later. |
Example response (abridged)
{
"api_version": "v1",
"address": "0x…",
"chain": "Robinhood Chain",
"symbol": "TICKER",
"in_zorvu_data": true,
"grade": "Elevated risk",
"passed_zorvu_safety_checks": false,
"checked_factors": 4,
"checks": [
{"id": "liquidity", "status": "pass",
"result": "Pass", "detail": "…"},
{"id": "sell_check", "status": "inconclusive",
"result": "Not checked", "detail": "…"}
],
"freshness": {
"as_of": "2026-10-26T19:40:00.000Z",
"liquidity_at": "…", "sell_sim_at": "…"
},
"stats": {"liquidity_usd": 12345, "…": "…"},
"disclaimer": "…"
}Illustrative structure only; values are placeholders.
Fields
| Field | Meaning |
|---|---|
| grade | Overall result: Not yet checked, Limited data, Elevated risk, High risk or Not applicable. A base asset (WETH, USDG, cbBTC) is graded Not applicable: Zorvu runs no project safety checks on those, so the answer carries no checks. Not returned today: Low risk needs at least 3 of the 4 core checks (liquidity, holders, sell test, deployer history) to have a result and fewer than 2 warnings overall; those four readings are archived, an archived reading never counts as a pass, so a core check can only reach that 3 by having warned or failed — which grades the token Elevated risk or High risk instead. Insufficient data is not returned by this endpoint either. |
| passed_zorvu_safety_checks | true only when the grade is Low risk, so on this endpoint it is always false while the token measurements are an archive (grade above). An archived reading never counts toward it. Shield's passed_zorvu_safety_checks, on each entry of its tokens[], is a different field with its own rule and does become true — see Shield. |
| in_zorvu_data | Whether Zorvu holds a measurement of the token from the last 7 days. If false, most checks return no_data. |
| token_data | archived or none. Zorvu's token measurements stopped being updated on 2026-11-14: they are archived readings. An archived reading never counts as a pass; it can support a warn or fail for 7 days, and is not used after that. archive.last_reading_at is Zorvu's last measurement of the token. |
| checks[].reading_at | Set when the check rests on an archived reading: when that reading was taken. |
| ticker_source | Where the lookalike check got the token's ticker: registry, live (its own symbol() and name(), read from the chain), archived (from the last 7 days), or unavailable. |
| checks[].status | pass, warn, fail, inconclusive (the test ran but could not reach a result) or no_data (not checked). |
| checks[].detail | Plain-language explanation of the result and the thresholds applied. |
| freshness.* | ISO 8601 UTC timestamps for the dataset and each underlying reading. Stale readings cannot pass. |
| stats.top10_real_wallet_pct | Share held by the top 10 real wallets. Pools, lockers, vesting contracts, burn addresses and the token contract are excluded. |
| stats.*_tax_bps | Simulated buy and sell tax in basis points. |
| drainer_check | Result of the drainer code check, when available. |
| disclaimer | Must be shown alongside results in any product that displays them. |
Sell depth — GET /api/v1/depth
The current sell-depth reading for one official Stock Token: what the on-chain pools filled a sale of $1,000, $10,000 and $100,000 at, against the reference price, and the largest sale they took within 2% and within 5% of it. Every figure carries the time it was measured and its age. No key needed.
GET https://zorvu.app/api/v1/depth?symbol=<ticker> GET https://zorvu.app/api/v1/depth?address=0x<40 hex characters>
Give one of symbol or address. A ticker resolves only to the official Stock Token in Zorvu's registry, never to a lookalike contract. Limit: 30 requests a minute per IP. Current reading only. Higher limits and reading history are available on request: request access.
Example response (abridged)
{
"api_version": "v1",
"symbol": "TICKER",
"address": "0x…",
"official_stock_token": true,
"reference_price": 100.0,
"reference_source": "official",
"read_at": "2026-11-13T21:48:00.000Z",
"reading_age_seconds": 420,
"ladder": [
{"usd": 1000, "fill_price": 99.8,
"impact_pct": -0.2, "reading": "ok"},
{"usd": 10000, "fill_price": 99.1,
"impact_pct": -0.9, "reading": "ok"},
{"usd": 100000, "fill_price": null,
"impact_pct": null, "reading": "no_route"}
],
"max_size": {
"within_2pct_usd": 25000,
"within_5pct_usd": 60000,
"capped": false,
"read_at": "2026-11-13T21:02:00.000Z",
"reading_age_seconds": 3180,
"reading": "ok"
},
"route_fee_bps": 30,
"hops_at_100k": null,
"note": "no route at 100k",
"freshness": {"reading_max_age_seconds": 1800,
"max_size_max_age_seconds": 7200},
"checked_at": "2026-11-13T21:55:00.000Z",
"disclaimer": "…"
}Illustrative structure only; values are placeholders.
Fields
| Field | Meaning |
|---|---|
| reference_price | Per-token price the fills are measured against. reference_source is official (the official quote) or pool (the pool price, when the official quote is older than 30 minutes). |
| ladder[].impact_pct | Fill against the reference price, in percent. Negative is below: -0.9 means 0.9% below. |
| ladder[].reading | ok, no_route (the pools could not take the sale), rate_limited or error (the quote failed), or not_measured (not quoted in that run). Anything but ok has null figures, never zero. |
| max_size | From a search run hourly. Older than 2 hours, it is "reading": "no_reading" with both figures null. capped: true: the search stopped at its ceiling, so the real size is at least the figure shown. |
| read_at, reading_age_seconds | When the ladder was measured, and how long before checked_at. A reading older than 30 minutes is not served. |
| note | The depth engine's own note on the reading. |
Errors
| Status | Code |
|---|---|
| 400 | invalid_request, invalid_symbol, invalid_address |
| 404 | not_official_stock_token, no_reading |
| 429 | rate_limited_minute |
| 503 | unavailable |
no_reading still names the token and gives the time of the last reading, if there is one. Zorvu does not total liquidity across tokens: a pool pairing two Stock Tokens counts toward both. These are measurements, not a quote, and not financial advice.
Shield — POST /api/v1/precheck
Send a transaction your agent, bot or wallet is about to sign on Robinhood Chain and get pass, warn or block with reasons. Shield checks a transaction someone else built: it never builds, routes, signs or sends one, holds no keys and charges no fee. pass means the transaction passed the checks listed in checks_run at the time shown, nothing broader; it is not a promise about what the transaction will do. See zorvu.app/shield.
POST https://zorvu.app/api/v1/precheck Authorization: Bearer <your API key> Content-Type: application/json
Same API keys, per-minute and per-day limits and usage count as GET /api/v1/check: a call to either endpoint counts against the same limits. Request bodies, tx.from and policies are not stored or logged. Bodies over 64 KB get 413 body_too_large.
Request
{
"chain_id": 4663,
"mode": "fast",
"tx": {
"from": "0x…", "to": "0x…",
"data": "0x…", "value": "0x0"
},
"intent": {
"token": "0x…", "side": "sell", "usd": 5000
},
"policy": {
"max_usd": 1000,
"allow_to": ["0x…"],
"allow_tokens": ["0x…"],
"block_unlimited_approvals": true
}
}
Request fields
| Field | Meaning |
|---|---|
| chain_id | Required. 4663 (Robinhood Chain). Anything else gets 400 unsupported_chain. Solana and Base are planned. |
| tx.to | Required. 0x followed by 40 hex characters. |
| tx.data | Hex calldata. Defaults to 0x. |
| tx.from, tx.value | Shape-checked only. from is never stored, logged or echoed. |
| mode | default or fast. fast answers from stored data only, with no chain lookup. See below. |
| intent.token | A token to check as well as the one in the calldata, and the token whose depth is read. |
| intent.side | buy or sell. |
| intent.usd | Intended size in USD, used for the depth and policy.max_usd checks. |
| policy.max_usd | Block when intent.usd is over this. |
| policy.allow_to | Up to 200 addresses. Block when tx.to is not in the list. |
| policy.allow_tokens | Up to 200 addresses. Block when a checked token is not in the list. |
| policy.block_unlimited_approvals | true turns unlimited_approval from warn into block. |
Response
{
"api_version": "v1",
"verdict": "warn",
"mode": "default",
"reasons": [
{"code": "unlimited_approval",
"severity": "warn",
"subject": "0x…",
"detail": "Unlimited approval: lets 0x0000…dbad move
any amount of this token from the sender."}
],
"checks_run": ["calldata_decode", "drainer_address_list",
"drainer_code", "lookalike_stock_token",
"approval_amount", "spender_code"],
"decoded": {
"method": "approve", "selector": "0x095ea7b3",
"args": {"spender": "0x…", "amount": "1157920…",
"unlimited": true}
},
"tokens": [
{"address": "0x…", "symbol": "TICKER",
"grade": "Limited data",
"passed_zorvu_safety_checks": true,
"official_stock_token": true, "lookalike_of": null,
"drainer_check": "clean",
"checks_run": ["drainer_code", "lookalike_stock_token"]}
],
"depth": {"address": "0x…", "max_usd_2pct": 25000,
"max_usd_5pct": 90000,
"read_at": "…", "max_read_at": "…",
"capped": false},
"checked_at": "…",
"disclaimer": "…"
}
Response fields
| Field | Meaning |
|---|---|
| verdict | The worst severity among the reasons: any block gives block, else any warn gives warn, else pass. info reasons never change the verdict. |
| mode | The mode that ran, default or fast. |
| reasons | Ordered block, warn, info. Each has a fixed code, a severity, the subject address or null, and plain-language detail. |
| checks_run | The checks that ran on every address they apply to: calldata_decode, drainer_address_list, drainer_code, lookalike_stock_token, approval_amount, spender_code, sell_depth, policy. pass covers only these. A check that did not run is left out, and a reason says why. Zorvu does not grade the liquidity, holders or sellability of a token that is not an official Stock Token. |
| decoded.method | One of the methods below, or null when the calldata is not decoded. Amounts are decimal strings. |
| tokens[] | Every token checked: the to of an ERC-20 call, the token argument of a Permit2 approve, and intent.token. Grades come from the same grader as /api/v1/check; a grade is not one of the checks a pass covers. passed_zorvu_safety_checks is true when every check in the token's own checks_run ran and passed and no warn or block names it. A field Zorvu could not read is null, never a pass. |
| tokens[].drainer_check | confirmed, review, clean, no_code, unavailable, or not_checked (fast mode, nothing stored). |
| depth | Zorvu's latest sell-depth reading for the token: the largest USD size the pools took within 2% and 5% of the reference price. null when there is no reading, the reading is over 30 minutes old, or its hourly max-size search is over 2 hours old. capped: true means the search hit its ceiling, so the real figure is at least that large and no size reason is raised. |
| checked_at | ISO 8601 UTC time the reply was produced. Every reading also carries its own age. |
| disclaimer | Must be shown alongside results in any product that displays them. |
Reason codes
| Code | Severity | When |
|---|---|---|
| drainer_contract | block | to, the spender or a checked token is a confirmed drainer: on Zorvu's drainer address list, or its contract code matches the drainer blocklist or a known drainer fingerprint. |
| drainer_recipient | block | The recipient of a transfer or transferFrom is on Zorvu's drainer address list. |
| lookalike_stock_token | block | A checked token uses the ticker or name of an official Stock Token but is not the official contract. Its ticker and name are read live from the token, so a lookalike launched after Zorvu's token measurements end is still caught. |
| sell_check_failed | block | Zorvu's archived sell test on a checked token failed, and that reading is from the last 7 days. The detail gives its date. The sell test no longer runs. |
| policy_max_usd | block | intent.usd is over policy.max_usd. |
| policy_to_not_allowed | block | tx.to is not in policy.allow_to. |
| policy_token_not_allowed | block | A checked token is not in policy.allow_tokens. |
| drainer_review | warn | to, the spender or a checked token has a drainer-like code pattern under review. Weaker signal; it can be legitimate. |
| high_risk_token | warn | Zorvu grades a checked token High risk. |
| token_not_graded | info | A checked token that is not an official Stock Token, which Zorvu does not grade: no liquidity, holder or sellability measurement, and archived readings never count. Raised only when its drainer code check ran clean and its ticker check ran and found no lookalike, so the verdict can be pass; the pass covers only the checks in checks_run. |
| unlimited_approval | warn | Approval amount of 2^255 or more, a Permit2 amount of the uint160 maximum, or setApprovalForAll(…, true). Becomes block when policy.block_unlimited_approvals is true. |
| approval_to_wallet | warn | The spender has no contract code: a plain wallet, not a contract. |
| size_over_depth_5pct | warn | intent.usd is more than depth.max_usd_5pct. |
| check_unavailable | warn | A live check timed out or failed (the drainer code read, or a token's live ticker read, so its lookalike check did not run), a checked token has no contract code, an address was over the 4-address limit, or policy.max_usd is set without intent.usd. Never a silent pass. |
| size_over_depth_2pct | info | intent.usd is more than depth.max_usd_2pct and not more than the 5% figure. |
| not_decoded | info | The calldata is not one of the methods below. The checks on to still run. |
| depth_unavailable | info | No depth reading for the token, the reading is over 30 minutes old, or its max-size search is over 2 hours old. Size was not checked against depth. |
| not_checked_fast | info | Warn when the address is a token being checked. Fast mode, and Zorvu's chain watcher has no drainer result for this address from the last 24 hours (or no ticker for this token), so that check did not run. Never reported as clean. |
Calldata decoded
| Method | Selector |
|---|---|
| approve(address,uint256) | 0x095ea7b3 |
| increaseAllowance(address,uint256) | 0x39509351 |
| setApprovalForAll(address,bool) | 0xa22cb465 |
| transfer(address,uint256) | 0xa9059cbb |
| transferFrom(address,address,uint256) | 0x23b872dd |
| Permit2 approve(address,address,uint160,uint48) | 0x87517c45 |
Anything else, including short or malformed calldata and an empty data, gives the info reason not_decoded; the checks on to still run. An approval of 0, or setApprovalForAll(…, false), is a revoke: the spender checks do not run on it, so revoking a drainer's approval is never blocked.
Modes
| Mode | What runs |
|---|---|
| default | Everything: contract code read live from the chain RPC for up to 4 addresses, each token's ticker and name read live for the lookalike check, the grader, and the stored depth reading, inside a 5 second budget. |
| fast | No chain lookup. Zorvu's drainer address list, the chain watcher's stored drainer result and ticker for each address (under 24 hours old), archived drainer findings from the last 7 days, the grader's stored data and the stored depth reading only. |
Use fast when an answer in well under a second matters more than a live read. It still blocks a listed drainer address, and a lookalike or a failed sell test known from an archived reading of the last 7 days, and it still applies your policy. An address with no drainer result from Zorvu's chain watcher in the last 24 hours is reported as not_checked_fast and its drainer_check is not_checked, never clean; a token with no fresh stored ticker gets the same for its lookalike check. For a token that is a warn; for a router or spender it is an info. A token with a fresh clean stored result and a fresh stored ticker that is not a lookalike gets token_not_graded (info), so fast can pass. default stays the mode to use when you can wait for it.
Example request
curl -s https://zorvu.app/api/v1/precheck \
-H "Authorization: Bearer $ZORVU_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"chain_id": 4663,
"tx": {
"to": "0x<token address>",
"data": "0x095ea7b3000000000000000000000000<spender, 40 hex>ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"
},
"policy": { "block_unlimited_approvals": true }
}'Errors
| Status | Code |
|---|---|
| 400 | invalid_json, invalid_request, unsupported_chain |
| 401 | missing_key, invalid_key |
| 413 | body_too_large |
| 429 | rate_limited_minute, rate_limited_day |
| 503 | unavailable |
Same shape as /api/v1/check: {"api_version":"v1","error":{"code":"…","message":"…"}}. The checks are automated, run on public data, and may be incomplete, wrong or out of date. Not financial advice.
MCP server — https://zorvu.app/mcp
The same checks as tools for AI agents, over the Model Context Protocol: Streamable HTTP, one JSON reply per request, no session kept. It speaks protocol 2026-07-28 and the 2025 versions that start with initialize.
| Tool | What it answers | Key |
|---|---|---|
| precheck_transaction | The pre-sign check: pass, warn or block for a transaction before it is signed. | Yes |
| stock_sell_depth | The sell-depth reading for one official Stock Token, by ticker or address. | No |
| check_token | The automated checks on one token, as /api/v1/check returns them. | No |
| find_stock_token | The official Stock Token address for a ticker, with the count of known lookalike contracts. | No |
Client config (the exact format varies by client):
{
"mcpServers": {
"zorvu": {
"type": "http",
"url": "https://zorvu.app/mcp",
"headers": { "Authorization": "Bearer <your API key>" }
}
}
}
The key goes in the client's header config, never in a tool argument, and only precheck_transaction needs it: without one that tool answers with an error saying so, and the other three still work. The keyless tools allow 30 calls a minute per IP between them; check_token also counts against the checker's own 20 a minute. Every tool returns structured content with an output schema, and every reading carries its time. Results are measurements, not advice.
Status: GET https://zorvu.app/api/health needs no key and returns 200 while Zorvu's data jobs are current, 503 with the late check named when any is not.
Questions or disputes: [email protected]. Zorvu is not affiliated with Robinhood Markets, Inc. or its affiliates.
