---
title: "Robinhood Chain token bundle (BASIC+)"
method: GET
path: "/rhc/tokens/{address}"
tags: ["Robinhood Chain"]
---

# Robinhood Chain token bundle (BASIC+)

`GET /rhc/tokens/{address}`

## Request

- Base URL: `https://madeonsol.com/api/v1`
- URL: `https://madeonsol.com/api/v1/rhc/tokens/{address}`
- Auth: HTTP bearer

Full snapshot for one token: metadata, live price/MC/FDV, peak MC + drawdown, graduation status, deployer reputation block (+ other tokens by the same deployer), KOL activity summary, and pool inventory with reserves. Tier: **BASIC**.

## Path parameters

- `address` string, required

## Response `200`

OK.

- object
  - `chain` 'robinhood'
  - `token_address` string
  - `symbol` string, nullable
  - `name` string, nullable
  - `decimals` integer, nullable
  - `launchpad` string, nullable
  - `is_graduated` boolean, nullable
  - `graduated_pool` string, nullable
  - `graduated_at` string, date-time, nullable
  - `deployer_address` string, nullable
  - `deployer_identity_status` 'known' | 'unresolved' | 'unavailable': known = the token row names its creator (identity does not depend on reputation); unresolved = no creator recorded; unavailable = the token lookup failed
  - `first_seen_at` string, date-time, nullable
  - `token_age_minutes` integer, nullable
  - `price_usd` number, nullable
  - `price_native` number, nullable
  - `price_observed_at` string, date-time, nullable: The last trade that set the native price — the price's own age anchor (same stale-price contract as GET /token/{mint})
  - `price_age_seconds` integer, nullable
  - `price_is_stale` boolean: true when price_age_seconds > 900
  - `price_updated_at` string, date-time, nullable: Row write time — can move without a trade (USD re-derivation); not a price-age anchor
  - `market_cap_usd` number, nullable
  - `fdv_usd` number, nullable
  - `peak_mc_usd` number, nullable
  - `peak_mc_at` string, date-time, nullable
  - `drawdown_from_peak_pct` integer, nullable
  - `total_supply_raw` string, nullable
  - `liquidity_usd` number, nullable
  - `liquidity_basis` 'v4_virtual_ceiling' | 'measured': How liquidity_usd was derived. uniswap-v4 has no per-pool balances, so its figure is virtual reserves clamped to the PoolManager's total holdings — a provable CEILING, not measured per-pool TVL.
  - `liquidity_note` string: Human-readable statement of the uniswap-v4 ceiling semantics; constant.
  - `liquidity_source` 'pool_balances' | 'v4_virtual_ceiling' | 'bonding_curve_reserve' | 'unknown_venue': Where liquidity_usd comes from: pool_balances = uniswap-v2/v3 pool token balances; v4_virtual_ceiling = uniswap-v4 virtual reserves clamped to the PoolManager (a ceiling); bonding_curve_reserve = 2x a launchpad curve quote reserve from contract state (pons-v2, flap, hood.fun, bags); unknown_venue = no recognised primary venue.
  - `liquidity_status` 'available' | 'verified_zero' | 'unavailable': available = positive figure; verified_zero = explicit 0 from chain state; unavailable = liquidity_usd is null (unknown, not yet measured, unresolved quote asset, or graduated curve awaiting its pool figure). Null never means zero.
  - `primary_dex` string, nullable
  - `primary_pool` string, nullable
  - `last_trade_time` string, date-time, nullable
  - `deployer` object, nullable: Deployer identity + reputation. Non-null whenever the creator address is known, even before the reputation view has it (history_status pending).
    - `identity_status` 'known'
    - `history_status` 'computed' | 'pending' | 'unavailable': computed = in the reputation view · pending = known creator, reputation not computed yet (NOT "new") · unavailable = the reputation lookup failed
    - `address` string
    - `tier` 'elite' | 'good' | 'neutral' | 'spammer'
    - `tokens_deployed` integer
    - `graduation_rate` number, nullable
    - `runner_rate` number, nullable
    - `runners` integer
    - `best_peak_mc_usd` number, nullable
    - `launchpads` string[]
  - `deployer_other_tokens` string[]: Up to 10 other tokens by the same deployer (symbol or address).
  - `kol_activity` object: Complete aggregate over the token's whole KOL history (rhc_token_kol_activity), keyed on the stable KOL id — two KOLs sharing a display name no longer collapse. If the aggregate is unavailable it falls back to a LABELLED newest-200 sample (basis latest_200_trades, complete=false when truncated, sample_size).
    - `distinct_kols` integer: Distinct KOL ids (not display names)
    - `names` string[]
    - `buys` integer
    - `sells` integer
    - `net_eth` number
    - `distinct_wallets` integer
    - `buy_eth` number
    - `sell_eth` number
    - `participants` object[]: Up to 20 KOLs, most recent first
      - `kol_id` string
      - `name` string, nullable
      - `twitter_url` string, nullable
      - `buys` integer
      - `sells` integer
      - `last_trade_at` string, date-time
    - `identity` 'kol_wallet_id'
    - `window` object
      - `kind` 'all_time' | 'latest_trades'
      - `first_trade_at` string, date-time, nullable
      - `last_trade_at` string, date-time, nullable
    - `basis` string: all_trades (complete aggregate) or latest_N_trades (fallback sample)
    - `complete` boolean
    - `sample_size` integer: Fallback sample only
  - `degraded_fields` string[]: Blocks whose lookup failed (e.g. deployer_other_tokens) — their values are unknown, not empty
  - `pools` object[]: Up to 20 pools with reserves/liquidity/sqrt_price. Each entry carries `liquidity_basis` (`v4_virtual_ceiling` | `measured`) for its own `liquidity_usd`.

## Other responses

- `401`: Missing or invalid API key, or an expired free-tier key. Authentication-stage error: no `X-RateLimit-*` headers, no `_rid`.
- `403`: Forbidden. One of: the key's tier is below this endpoint's or parameter's gate (`tier_required` with an `upgrade` block); the public demo key used outside its allow-list (`demo_key_endpoint_not_allowed`); an invalid or revoked key; an origin-restricted key called from a disallowed origin (`code` `origin_not_allowed` / `origin_required`). `X-RateLimit-*` headers are present only on `tier_required`.
- `404`: Token not found on Robinhood Chain.
- `429`: Too many requests. Every 429 carries `Retry-After`. A quota 429 (`rate_limit_exceeded`, with `X-RateLimit-*`), a heavy-query concurrency 429 (`error_kind` `concurrency`/`capacity`), or the per-IP authentication-failure block (30 failed auths/min; plain `error` + `retry_after_seconds`, no `X-RateLimit-*`).
- `500`: Unexpected server error from the route (`Internal server error`, with `_rid`). Safe to retry with backoff. A failed API-key lookup is a 503 `auth_backend_unavailable`, never a 500.
- `503`: Temporarily unavailable — a Postgres statement timeout while the dataset is under load or maintenance (`statement_timeout`, with `X-RateLimit-*` and `_rid`), or the API-key lookup itself unavailable (`auth_backend_unavailable`, authentication stage: no `X-RateLimit-*`, no `_rid`, not counted as a failed authentication). Always carries `Retry-After`; honour it.

---

[API](https://skmtc.dev/madeonsol/apis/madeonsol-robinhood-chain-api.md) · [All operations](https://skmtc.dev/madeonsol/apis/madeonsol-robinhood-chain-api/llms.txt) · [OpenAPI document](https://skmtc.dev/madeonsol/apis/madeonsol-robinhood-chain-api/revisions/9ea9a35ee2bf?raw)