ZORVU
DEVELOPER API · PREVIEW

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.

A 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)

TierPer minutePer day
free10100
beta301,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

StatusCodeMeaning
400invalid_addressAddress is not 0x plus 40 hex characters.
401missing_keyNo Bearer key was sent.
401invalid_keyKey is unknown or revoked.
429rate_limited_minute / _dayLimit reached. See retry-after.
503unavailableTemporary 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

FieldMeaning
gradeOverall 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_checkstrue 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_dataWhether Zorvu holds a measurement of the token from the last 7 days. If false, most checks return no_data.
token_dataarchived 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_atSet when the check rests on an archived reading: when that reading was taken.
ticker_sourceWhere 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[].statuspass, warn, fail, inconclusive (the test ran but could not reach a result) or no_data (not checked).
checks[].detailPlain-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_pctShare held by the top 10 real wallets. Pools, lockers, vesting contracts, burn addresses and the token contract are excluded.
stats.*_tax_bpsSimulated buy and sell tax in basis points.
drainer_checkResult of the drainer code check, when available.
disclaimerMust 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

FieldMeaning
reference_pricePer-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_pctFill against the reference price, in percent. Negative is below: -0.9 means 0.9% below.
ladder[].readingok, 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_sizeFrom 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_secondsWhen the ladder was measured, and how long before checked_at. A reading older than 30 minutes is not served.
noteThe depth engine's own note on the reading.

Errors

StatusCode
400invalid_request, invalid_symbol, invalid_address
404not_official_stock_token, no_reading
429rate_limited_minute
503unavailable

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

FieldMeaning
chain_idRequired. 4663 (Robinhood Chain). Anything else gets 400 unsupported_chain. Solana and Base are planned.
tx.toRequired. 0x followed by 40 hex characters.
tx.dataHex calldata. Defaults to 0x.
tx.from, tx.valueShape-checked only. from is never stored, logged or echoed.
modedefault or fast. fast answers from stored data only, with no chain lookup. See below.
intent.tokenA token to check as well as the one in the calldata, and the token whose depth is read.
intent.sidebuy or sell.
intent.usdIntended size in USD, used for the depth and policy.max_usd checks.
policy.max_usdBlock when intent.usd is over this.
policy.allow_toUp to 200 addresses. Block when tx.to is not in the list.
policy.allow_tokensUp to 200 addresses. Block when a checked token is not in the list.
policy.block_unlimited_approvalstrue 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

FieldMeaning
verdictThe worst severity among the reasons: any block gives block, else any warn gives warn, else pass. info reasons never change the verdict.
modeThe mode that ran, default or fast.
reasonsOrdered block, warn, info. Each has a fixed code, a severity, the subject address or null, and plain-language detail.
checks_runThe 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.methodOne 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_checkconfirmed, review, clean, no_code, unavailable, or not_checked (fast mode, nothing stored).
depthZorvu'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_atISO 8601 UTC time the reply was produced. Every reading also carries its own age.
disclaimerMust be shown alongside results in any product that displays them.

Reason codes

CodeSeverityWhen
drainer_contractblockto, 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_recipientblockThe recipient of a transfer or transferFrom is on Zorvu's drainer address list.
lookalike_stock_tokenblockA 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_failedblockZorvu'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_usdblockintent.usd is over policy.max_usd.
policy_to_not_allowedblocktx.to is not in policy.allow_to.
policy_token_not_allowedblockA checked token is not in policy.allow_tokens.
drainer_reviewwarnto, the spender or a checked token has a drainer-like code pattern under review. Weaker signal; it can be legitimate.
high_risk_tokenwarnZorvu grades a checked token High risk.
token_not_gradedinfoA 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_approvalwarnApproval 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_walletwarnThe spender has no contract code: a plain wallet, not a contract.
size_over_depth_5pctwarnintent.usd is more than depth.max_usd_5pct.
check_unavailablewarnA 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_2pctinfointent.usd is more than depth.max_usd_2pct and not more than the 5% figure.
not_decodedinfoThe calldata is not one of the methods below. The checks on to still run.
depth_unavailableinfoNo 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_fastinfoWarn 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

MethodSelector
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

ModeWhat runs
defaultEverything: 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.
fastNo 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

StatusCode
400invalid_json, invalid_request, unsupported_chain
401missing_key, invalid_key
413body_too_large
429rate_limited_minute, rate_limited_day
503unavailable

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.

ToolWhat it answersKey
precheck_transactionThe pre-sign check: pass, warn or block for a transaction before it is signed.Yes
stock_sell_depthThe sell-depth reading for one official Stock Token, by ticker or address.No
check_tokenThe automated checks on one token, as /api/v1/check returns them.No
find_stock_tokenThe 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.