RBB Gateway API Documentation

Read-only REST API for holders, liquidity, staking, trades and live market data on the Supra ecosystem.

The RBB Gateway API is a read-only HTTPS API. Authenticate with an API key on every route except the public holder-token catalog, /health, and the Help form. Standard keys cover the REST surface; Premium keys unlock SSE streams and bypass the per-key quota.

What you can query today:

Holders (Supra) — verified complete lists, coin/FA merge, wallet breakdown (wallet / staked / LP / locks)
Liquidity pools — DEX reserves by token, and LP converted back to underlying token per wallet
Distribution — where the whole supply of a token sits: wallets, liquidity, staking, locks, lending, perps, burn addresses
Staking — Spikey, Pecky and SupraVault (SVLT) ledgers and per-pool / per-wallet views
Atmos farms — farm ledger and farms by token
Trades & volume — 24h and 7d windows
Market & tokens — summary, activity, trending and graduations
Premium streams — SSE events and prices, and the REST events history

Base URL

https://api.robbiesuprameme.xyz

Authentication

All endpoints except /health, /api/v1/holders/tokens, and the Help form submission require an API key. Pass it via one of:

X-Api-Key: <your-api-key>

# or
Authorization: Bearer <your-api-key>

Keys are SHA-256 hashed server-side and compared using constant-time equality. Your raw key is never stored.

Rate Limits

Standard API keys share one application-level quota across all authenticated routes. Premium-only routes are excluded:

Default Limit	Scope	Config
100 requests in a rolling 60-second window	Per standard API key, all authenticated routes combined	`ROBBIE_GATEWAY_API_RATE_LIMIT_MAX_REQUESTS` / `ROBBIE_GATEWAY_API_RATE_LIMIT_WINDOW_MS`

The HTTPS gateway also applies these limits per client IP:

Route	Per-IP limit
API requests, including public routes (except streams)	5 requests/second, with `burst=5 nodelay` (up to 5 excess requests immediately), and 20 concurrent connections
`/api/v1/stream/`	5 concurrent connections; streams require a Premium API Key

Exceeding either nginx limit returns 429. The application-level per-key limit also returns 429, with a retryAfterSec field and a retry-after header. Public routes have no API-key quota but remain subject to the nginx per-IP limit. The static /api/docs pages are outside these API limits. The legacy rateLimitMs response field gives the average spacing for 100 requests/minute (600 ms), not a mandatory pause between calls.

Premium API Key Premium API Keys bypass the application-level per-key quota and unlock premium-only routes. Nginx per-IP limits remain separate.

API Key Types

Type	Access	Rate Limit	Use Case
Standard Key	Standard API key	100/min per key, across authenticated routes	External integrations, scripts, bots
Premium API Key	Premium plan	No application-level quota; nginx per-IP limits still apply	Premium integrations and real-time streams

Security Best Practices

Store API keys in environment variables or a secrets manager — never in source code
Use HTTPS exclusively; all HTTP requests are redirected
Rotate keys periodically and after any suspected compromise
Use a standard key unless your integration needs a premium-only feature
Keep .env out of version control (.gitignore)

Don't

Never embed API keys in client-side JavaScript, mobile apps, or public repos
Never share your Premium API Key or paste it in Discord/Slack/chat
Never commit .env files or API keys to Git — even in private repos
Never use API keys to perform write operations (this API is read-only)
Never proxy API keys through untrusted servers or CORS proxies
Never reuse the same key across multiple unrelated projects

Prohibited Usage

The following will result in immediate key revocation without notice:

Scraping / bulk extraction — Automated mass downloading beyond legitimate integration needs
Resale / redistribution — Selling, sublicensing, or redistributing API data without written permission
Circumventing rate limits — Using multiple keys, rotating keys, or any bypass technique
Key sharing — Sharing your API key with unauthorized parties or embedding in public code
Abuse / harassment — Using the API to facilitate spam or harassment
Reverse engineering — Attempting to decompile or extract proprietary logic
Competitive intelligence — Using the API to build a competing product

Terms of Use

By accessing or using the RBB Gateway API, you agree to the following terms.

1. Access & Authorization

API access is a revocable privilege, not a right. We may revoke any key at any time, with or without cause, without prior notice.
Your API key is personal and non-transferable. You may not share, sell, or lease your key to any third party.
You are responsible for all activity under your API key.
If you believe your key is compromised, notify us immediately.

2. Data Usage

Data is provided "as is" for informational purposes only.
You may not use API data for any unlawful purpose.
We do not guarantee data accuracy, completeness, or timeliness.
Data may be cached, delayed, or incomplete during maintenance.

3. Availability

The API is provided on a best-effort basis. No guarantee of uptime, latency, or availability.
We may suspend or modify the API at any time.
We are not liable for damages arising from unavailability or data inaccuracies.

Key Revocation Policy

Important: Revocation is immediate and irreversible. There is no grace period. Revoked keys cannot be restored — a new key must be issued.

We may revoke your API key without prior notice if:

You violate any term of this agreement
Suspicious or abusive usage patterns are detected (abnormal volume, scraping, etc.)
Your key is found in a public repository, paste, or leak
You share your key with unauthorized third parties
We receive a legal request or court order requiring revocation
We discontinue the API or a specific endpoint

After revocation

All requests with the revoked key return 401 Unauthorized
Cached data may be purged
You must contact the API team for a new key (revocation is final)

Premium API Key

Premium API Keys are subject to stricter monitoring. Any abuse results in immediate revocation and potential permanent ban.

Limitation of Liability

Provided "as is" and "as available" without warranties.
No liability for indirect, incidental, special, consequential, or punitive damages.
Total liability shall not exceed $0.
You are solely responsible for decisions made based on API data.
No responsibility for financial losses, trading decisions, or investment outcomes.

Holders (Supra)

Current holder balances of Supra tokens, served from our own on-chain holder index. It follows every block in real time (a few seconds behind the chain tip) and every account is verified against on-chain balances.

Only verified complete tokens A token is served only once its holder list is proven complete: for fungible assets, the sum of all balances equals the on-chain supply exactly; for coins, the list was checked holder by holder and the paired FA side matches its supply. New fungible assets launched through Atmos Token Studio or Hoglet are indexed from their creation and can be listed automatically after 48 hours if the supply and health checks pass (listing: "auto"). See New Tokens.

Every account, like SupraScan: by default the list includes burn addresses and contract-held balances (DEX pool reserves, Spikey staking, vaults, resource accounts). Each row carries a classification; use include=holder to keep real wallets only. holderCount counts every account holding the token, contracts included (the figure explorers show); walletHolderCount counts regular wallets only.
Exact amounts: balanceRaw is an integer string in base units; balance is the same value as an exact decimal string.
Addresses are returned as full 64-hex strings.

Coin & FA aliases (automatic)

On Supra, most coins also exist as a paired fungible asset (FA): the same token, held either as a legacy Coin<T> or in FA stores after conversion. Explorers list the two sides on separate pages. The holder API merges them for you, automatically:

The coin ↔ FA pairing is resolved on-chain and applied to every coin; you never have to query both sides or pass the FA address.
Each wallet appears once, with its total balance and the split: coinRaw (the Coin<T> part) + faRaw (its paired FA stores) = balanceRaw.
Wallets that converted everything to FA are included, even though they are absent from the coin’s holder page on an explorer.
You can use either the coin type or the FA metadata address as :tokenId: both return the same merged list.

Example: ROBBIE 719 wallets hold ROBBIE as a coin (the figure shown on the coin’s explorer page), 72 hold it as FA, 6 hold both. The API returns 785 wallets: 719 + the 66 that hold FA only.

Token identifier (`:tokenId`)

Any of: the coin type (0x…::ROBBIE::ROBBIE, any case, padded or not), the FA metadata address, or the paired FA metadata address of a coin. A token that is not in the available list returns 404 token_not_available.

Available Tokens

GET /api/v1/holders/tokens no API key

Tokens whose holder list is available. Public, not rate limited. ready: false means the token is temporarily paused (see blockers) and its holder routes answer 503 holders_not_ready. A new wallet is included as soon as its first transfer is indexed; reconciling: true only means its on-chain cross-check is still running.

{
  "ok": true,
  "tipBlockHeight": 54787872,
  "count": 83,
  "data": [
    {
      "tokenId": "0x635f…a9007::ROBBIE::ROBBIE",
      "symbol": "ROBBIE",
      "name": "RobbieTheRobot",
      "kind": "coin",                  // "coin" or "fa"
      "coinType": "0x635f…a9007::ROBBIE::ROBBIE",   // null for a pure FA
      "faMetadata": "0xf4fc…6b61d",    // FA metadata (paired FA for a coin)
      "decimals": 6,
      "holderCount": 785,              // every account, contracts included (like explorers)
      "walletHolderCount": 760,        // regular wallets only
      "blockHeight": 54787842,         // last block applied to this token
      "listing": "verified",           // "verified" (curated) or "auto" (exact supply match for 48 h)
      "ready": true,
      "reconciling": false,            // true for ~1 min after a new wallet appears (still served)
      "blockers": []
    }
  ]
}

Holder List

GET /api/v1/holders/:tokenId

All holders of a token, largest balance first. The whole list is returned in one call (up to 20,000 rows); pagination is also available if you need smaller responses.

Param		Description
`:tokenId`	required	Coin type or FA metadata address
`include`	optional	`all` (default), or a comma list of `holder` (regular wallets), `custody` (DEX pools, staking, vaults), `contract`, `burn`
`limit`	optional	Max rows (default and max 20000)
`offset`	optional	Rows to skip (default 0)

{
  "ok": true,
  "data": {
    "tokenId": "0x635f…a9007::ROBBIE::ROBBIE",
    "symbol": "ROBBIE",
    "kind": "coin",
    "coinType": "0x635f…a9007::ROBBIE::ROBBIE",
    "faMetadata": "0xf4fc…6b61d",
    "decimals": 6,
    "blockHeight": 54787842,
    "holderCount": 785,
    "walletHolderCount": 760,
    "supplyRaw": "990024620933260",
    "include": ["holder", "custody", "contract", "burn"],
    "total": 785,                      // rows matching include (before limit/offset)
    "limit": 20000,
    "offset": 0,
    "count": 785,
    "holders": [
      {
        "rank": 1,
        "address": "0x844a46eb…6efcdad",
        "balance": "89900941.146184",
        "balanceRaw": "89900941146184",
        "coinRaw": "89900941146184",   // Coin<T> part
        "faRaw": "0",                  // fungible-asset stores part
        "percentOfSupply": 9.080677,
        "classification": "holder"     // holder | custody | contract | burn
      }
    ]
  }
}

Wallet Balance

GET /api/v1/holders/:tokenId/:wallet

Balance of one wallet for a token, plus a breakdown of everything it holds elsewhere: staking, farms, liquidity, token locks and DAO NFT locks. A wallet that never held the token returns a zero balance (not an error).

The breakdown is computed from our indexes only (no live chain scan), so it answers in milliseconds:

staked: the token staked directly (Spikey, Atmos farms, Pecky nodes).
liquidity: LP positions converted to the token amount they represent (LP amount × token reserve ÷ LP supply, from the latest indexed pool reserves): LP held in the wallet, staked in Spikey, farmed in Atmos, staked in a Dexlyn gauge or LP staking slot (dexlynStaked), or locked, plus Dexlyn concentrated-liquidity positions held in the wallet (dexlynClmm) or staked in a Dexlyn gauge (dexlynClmmGauge). positions lists each pool.
locked: the token itself in active token locks, including Atmos Token Studio locks (read on-chain every 30 minutes, and right after a lock or unlock).
lent: the token supplied to Supralend (supralend), valued at the pool’s current exchange rate (interest included). Borrowed amounts are not subtracted: borrowed tokens are already in the wallet.
perps: the token in the wallet’s Dexlyn perps one-click trading vault (dexlyn1ct). The margin of open perps positions is not counted.
daoLocks: active DAO NFT lock positions, when indexed for this token. Includes total, totalRaw and positions with the NFT, DAO, owner and end epoch.
total = wallet + staked + liquidity + locked + lent + perps + DAO locks (when present). burned is informational and not included.
LP held in the wallet comes from our holder index of the LP tokens (Atmos, Spikey, Dexlyn and LeoEx LPs, see DEX coverage). inWalletCoverage tells how many of the token’s LP tokens are indexed and how many are still being cross-checked on-chain; an LP token not indexed yet counts as 0 (never too high).

Param		Description
`:tokenId`	required	Coin type or FA metadata address
`:wallet`	required	Supra address (short or full 64-hex)

{
  "ok": true,
  "data": {
    "tokenId": "0x635f…a9007::ROBBIE::ROBBIE",
    "symbol": "ROBBIE",
    "decimals": 6,
    "blockHeight": 54787842,
    "address": "0xfdf7e354…3c32ab6f40",
    "balance": "52515050.829721",
    "balanceRaw": "52515050829721",
    "coinRaw": "52515050829721",
    "faRaw": "0",
    "percentOfSupply": 5.304418,
    "classification": "holder",        // holder | custody | contract | burn | null
    "isHolder": true,
    "breakdown": {
      "wallet": "52515050.829721",
      "staked": { "spikey": "0", "atmosFarm": "0", "pecky": "0", "total": "0" },
      "liquidity": {
        "inWallet": "0",
        "inWalletCoverage": { "lpTokens": 11, "indexed": 5, "reconciling": 0 },
        "spikeyStaked": "0",
        "atmosFarm": "2161139.546531",
        "dexlynStaked": "0",
        "locked": "0",
        "dexlynClmm": "0",
        "dexlynClmmGauge": "0",
        "total": "2161139.546531",
        "positions": [
          { "dex": "ATMOS", "pool": "0x1641…54da", "name": "JOSHKU/ROBBIE LP",
            "lpRaw": "1574011050772", "tokenRaw": "2161139546531", "token": "2161139.546531",
            "reservesAt": "2026-09-29T20:29:24.179Z" }
        ]
      },
      "locked": "0",
      "lent": { "supralend": "0", "total": "0" },
      "perps": { "dexlyn1ct": "0", "total": "0" },
      "total": "54676190.376252",
      "totalRaw": "54676190376252",
      "burned": "0"
    }
  }
}

How a token reaches the holder API

Indexing balances and publishing a holder list are separate steps. A token can have activity in the other API endpoints before it is available through the holder endpoints.

Automatic indexing at launch

New Atmos Token Studio and Hoglet launchpad fungible assets are detected through their on-chain launch events. The holder index starts from the block before creation, records the creator and bonding curve as initial account candidates, replays indexed balance events, and checks balances on-chain. New Atmos, Dexlyn and LeoEx pool LP tokens are indexed too (from their creation), but are excluded from the public holder-token list.

Hoglet launch indexing applies to launches captured since the Hoglet update on 30 Sep 2026; earlier launches are not backfilled automatically. The index runs behind the chain tip by a safety margin, so a launch is not visible instantly.

Manual reconstruction for older or missed tokens

An operator can import an existing holder snapshot or a set of candidate addresses, including a SupraScan export. Candidate addresses are starting points, not trusted balances: the materializer reads their actual balances on-chain, replays indexed events, and reconciles the result. For an already indexed asset, adding candidates preserves existing accounts. A fungible asset still needs an exact supply match; an older coin needs a holder-by-holder check and verification of its paired FA side.

This is an operator workflow, not a public API request. A missing token does not become available merely by querying /api/v1/holders/:tokenId.

Publication and availability

Path	When it appears	Listing value
Automatic FA listing	After at least 48 hours in the index, with an exact supply match and no recent reconciliation drift; LP tokens are excluded.	`auto`
Manual verification	After an operator verifies completeness and adds the token to the curated holder API list.	`verified`

Check /api/v1/holders/tokens for ready, reconciling, blockers, and blockHeight. An unlisted token returns 404 token_not_available. A listed token with a blocking index problem returns 503 holders_not_ready until the check passes again. A pending on-chain check for a newly seen account may set reconciling: true without pausing an otherwise verified token.

Liquidity Pools

List LP pools by DEX and token, with locked, burned, and staked data per pool.

GET /api/v1/lp/:dex/:tokenId

All LP pools on a given DEX that contain the specified token.

Param		Description
`:dex`	required	DEX name: `ATMOS`, `SPIKEY`, `DEXLYN`, `LEOEX`
`:tokenId`	required	Token address, coin type, or LP token address

{
  "ok": true,
  "dex": "ATMOS",
  "token": "0xfec11647...",
  "count": 1,
  "data": [
    {
      "lpToken": "0x...",
      "pool": "0x...",
      "dex": "ATMOS",
      "tokenA": "0x...",
      "tokenB": "0x...",
      "totalLpSupply": "1000000000",
      "lastReservesRaw": { "x": "500000", "y": "1200000" },
      "locked": {
        "totalRaw": "250000000",
        "rows": [
          { "wallet": "0xabc...", "amountRaw": "150000000", "unlockTimeSec": 1790618913 },
          { "wallet": "0xdef...", "amountRaw": "100000000", "unlockTimeSec": 1815475716 }
        ]
      },
      "burned": {
        "totalRaw": "100000000",
        "wallets": [
          { "wallet": "0xabc...", "amountRaw": "100000000" }
        ]
      },
      "staked": {
        "spikey": [
          { "wallet": "0xdef...", "amountRaw": "50000000", "source": "spikey" }
        ],
        "atmos": [
          { "wallet": "0x123...", "amountRaw": "75000000", "source": "atmos_farm" }
        ]
      }
    }
  ]
}

locked.totalRaw — Total LP tokens locked in the locker contract
locked.rows — Per-wallet lock positions with amounts and unlock times
burned.totalRaw — Total LP tokens permanently burned
burned.wallets — Per-wallet burn amounts
staked.spikey — Wallets with LP tokens staked in Spikey
staked.atmos — Wallets with LP tokens staked in Atmos farms

LP Held in Wallets

Wallets holding LP tokens of the pools that contain a given token (Atmos, Spikey, Dexlyn and LeoEx pools), for a coin or an FA. Each LP amount is converted to the amount of the token it represents (LP amount × token reserve ÷ LP supply, from the latest indexed pool reserves), so wallets can be ranked by the token they hold through liquidity. Pass the same :tokenId as the other holder routes (coin type or FA metadata address).

By default only wallets are returned. LP staked in a farm or locked is held by the farm or locker contract, so it is not counted for the wallet that staked it: use include=custody,contract to see those contract accounts, or the breakdown of Wallet Balance for a wallet’s full liquidity position.

DEX coverage

DEX	LP token	Pool reserves
`ATMOS`	Pool FA	Latest indexed reserves
`SPIKEY`	Pool FA	Latest indexed reserves
`DEXLYN`	Coin `lp_coin::LP<X, Y, Curve>`	Live pool reserves
`LEOEX`	Pool FA	Live pool reserves
`DEXLYN_CLMM`	Position NFT (no LP token)	Live pool price and position range

Wrapped tokens: some DEXes pair an FA wrapper instead of the token itself (Hoglet and LeoEx). Wrappers are discovered automatically from those DEXes’ on-chain registries and checked on-chain (same decimals, backing balance compared with the wrapper supply); a wrapper counts as its origin token, so its pools and stakes appear under the origin token. The LeoEx SUPRA wrapper is only partly backed: it counts as SUPRA, and every position whose leg is that wrapper carries wrappedBacking (backingPct, supplyRaw, backingRaw, at), the share of its supply actually held in SUPRA by the wrapper, read on-chain every 15 minutes.
Dexlyn concentrated liquidity: each position is an NFT holding liquidity in a price range. Its token amount is computed from the position liquidity, its range and the current pool price (uncollected fees and rewards excluded). These entries have dex: "DEXLYN_CLMM", lpToken: null and the position NFTs in nfts. A position staked in a Dexlyn gauge is held by the gauge: here it is listed under the gauge (custody) with the wallets that staked it in stakedBy, and in the Wallet Balance breakdown it counts for the staking wallet (dexlynClmmGauge). Positions and owners are refreshed every 15 minutes (coverage.dexlynClmm.refreshedAt).
Not covered: DEXes other than the ones above.
Staked Dexlyn LP: classic Dexlyn LP staked in a DXLYN gauge or a Dexlyn LP staking slot is held by that contract (custody); its position lists the wallets that staked it in stakedBy, and the Wallet Balance breakdown counts it for them (dexlynStaked).
LP tokens of new Dexlyn and LeoEx pools are indexed automatically from their creation.

An LP token is counted only once its holder index is verified complete. The others are listed in coverage.details with their blockers (not_materialized means the LP token is not indexed yet), never silently dropped: when coverage.ready is lower than coverage.lpTokens, the ranking is incomplete.

GET /api/v1/holders/lp/:tokenId

Wallets holding LP of this token’s pools, largest token equivalent first.

Param		Description
`:tokenId`	required	Coin type or FA metadata address (see Available Tokens)
`include`	optional	`holder` (default), `custody`, `contract`, `burn`, comma-separated, or `all`
`limit`	optional	Page size (default and max 20 000)
`offset`	optional	Rows to skip

{
  "ok": true,
  "data": {
    "tokenId": "0x635f…a9007::ROBBIE::ROBBIE",
    "symbol": "ROBBIE",
    "decimals": 6,
    "include": ["holder"],
    "total": 41,
    "limit": 20000, "offset": 0, "count": 41,
    "coverage": {
      "lpTokens": 11,                 // LP tokens of this token's pools
      "indexed": 6,                   // of which tracked by the holder index
      "ready": 5,                     // of which counted (holder index verified complete)
      "dexlynClmm": { "pools": 0, "positions": 0, "refreshedAt": "2026-10-04T12:00:00.000Z" },  // Dexlyn CLMM position NFTs
      "details": [
        { "lpToken": "0x1641…54da", "dex": "ATMOS", "pool": "0x1641…54da", "name": "JOSHKU/ROBBIE LP",
          "indexed": true, "ready": true, "blockers": [], "reservesAt": "2026-09-29T20:29:24.179Z" }
      ]
    },
    "holders": [
      {
        "rank": 1,
        "address": "0xfdf7e354…3c32ab6f40",
        "classification": "holder",
        "tokenRaw": "2161139546531",   // token amount represented by all its LP
        "token": "2161139.546531",
        "lpPositions": [
          { "lpToken": "0x1641…54da", "dex": "ATMOS", "pool": "0x1641…54da", "name": "JOSHKU/ROBBIE LP",
            "lpRaw": "1574011050772", "tokenRaw": "2161139546531", "token": "2161139.546531" }
        ]
      }
    ]
  }
}

GET /api/v1/holders/lp/:tokenId/:wallet

LP of this token’s pools held by one wallet, same fields as one row above plus coverage. A wallet that holds none returns tokenRaw: "0" and an empty lpPositions (not an error).

Supply Distribution

Where the whole supply of a token sits, for the tokens of the holder list. Every figure comes from our own indexes, refreshed in the background and checked against the chain; no external call is made when you query it.

The categories add up to the on-chain supply. pct is the share of the supply. For a coin whose supply is not tracked on-chain (e.g. PECKY), supply is null, pctBase is "observed" (shares of the observed total) and otherContracts is null.
wallets: regular wallets (from the holder index). burnAddresses: tokens sent to burn addresses (still counted in the supply).
liquidity: the token in DEX pools (Atmos, Spikey, Dexlyn classic and concentrated liquidity, LeoEx), byDex. ownership splits the same amount by who owns the LP: inWallets, stakedInFarms (farms, gauges, LP staking slots: exactly the viaLp block of Staking), locked (LP lockers), lockedAtGraduation (LP minted when an Atmos Token Studio token graduates, kept by the Atmos contract: no function withdraws it, only an upgrade of the Atmos package could), otherContracts (LP held by any other contract), burned (burned LP: liquidity nobody can remove), unattributed (LP not indexed, uncollected concentrated-liquidity fees). LP amounts are converted at the current pool reserves (reservesAt: the oldest pool read).
staked: the token staked directly (Spikey, Atmos farms, Pecky, other staking contracts), byProtocol. Staked LP is in liquidity.ownership.stakedInFarms, never counted twice.
rewards: rewards not paid out yet, held by the farms and staking pools that pay in the token (Atmos farms, Spikey staking pools), byProtocol. They are out of circulation until they are claimed.
locked: Atmos Token Studio locks, active and expiredNotWithdrawn.
lent: the token held by Supralend (supplied and not borrowed out; borrowed tokens are in the borrowers’ wallets).
perps: Dexlyn perps one-click trading vaults and perps vaults. fees: DEX DAO fees and the Atmos fee collector.
otherContracts: every other contract account (vesting, treasuries, wrappers, bots). checks.consistent is false when the sources add up to more than the supply (e.g. reserves read at different times); overCountRaw tells by how much.

GET /api/v1/distribution/:tokenId

Supply distribution of one token.

Param		Description
`:tokenId`	required	Coin type or FA metadata address (see Available Tokens)

{
  "ok": true,
  "data": {
    "tokenId": "0x635f…a9007::ROBBIE::ROBBIE",
    "symbol": "ROBBIE",
    "decimals": 6,
    "supply": "990024620.93326",
    "distribution": {
      "wallets":       { "amount": "464853…", "raw": "…", "pct": 46.9543 },
      "liquidity":     { "amount": "184858…", "raw": "…", "pct": 18.672,
                         "byDex": { "ATMOS": "146495418.99", "DEXLYN": "30739931.99", "LEOEX": "7622808.31" },
                         "ownership": { "inWallets": "46918865.55", "stakedInFarms": "79647269.17", "locked": "30550954.47",
                                        "lockedAtGraduation": "0", "otherContracts": "0",
                                        "burned": "27741070.10", "unattributed": "0.000041" },
                         "reservesAt": "2026-10-05T09:40:00.000Z" },
      "staked":        { "amount": "105691672.99", "pct": 10.6756, "byProtocol": { "spikey": "105691672.99", "atmosFarm": "0", "pecky": "0" } },
      "rewards":       { "amount": "25271888.94", "pct": 2.5527, "byProtocol": { "atmosFarm": "2899989.09", "spikey": "22374688.94" } },
      "locked":        { "amount": "0", "pct": 0, "active": "0", "expiredNotWithdrawn": "0", "byProtocol": { "atmosTokenStudio": "0" } },
      "lent":          { "amount": "0", "pct": 0, "byProtocol": { "supralend": "0" } },
      "perps":         { "amount": "0", "pct": 0, "dexlyn1ct": "0", "dexlynVaults": "0" },
      "fees":          { "amount": "3772…", "pct": 0.381, "dexDaoFees": "…", "atmosFeeCollector": "…" },
      "burnAddresses": { "amount": "187448…", "pct": 18.9338 },
      "otherContracts":{ "amount": "43393…", "pct": 4.383 }
    },
    "checks": { "consistent": true, "overCountRaw": "0", "lpAttributedPct": 99.99 }
  }
}

Locks by Token

Every current lock of a token: Atmos Token Studio locks of the token, and Atmos LP locker locks of the pools it is in (converted to the token at the current reserves, lpRaw keeps the LP amount). status is active, or expired when the unlock date passed but the owner has not withdrawn yet.

GET /api/v1/distribution/:tokenId/locks

Locks of one token, soonest unlock first.

{
  "ok": true,
  "data": {
    "tokenId": "0xe8e4…7148", "symbol": "BEYOND8", "decimals": 6,
    "active": { "raw": "…", "amount": "25000000" },
    "expiredNotWithdrawn": { "raw": "0", "amount": "0" },
    "count": 1,
    "locks": [
      { "kind": "token", "protocol": "atmos_token_studio", "wallet": "0x915f…", "unlockTimeSec": 1812604555,
        "status": "active", "unlockAt": "2027-06-10T…", "raw": "25000000000000", "amount": "25000000" }
    ]
  }
}

Burns by Token

Everything burned of a token, in two kinds: destroyed (Atmos Token Studio burns: the tokens no longer exist and are out of the supply; per burner, verified against the on-chain total) and sentToBurnAddresses (tokens sent to burn addresses: still counted in the supply, shown as burnAddresses in the distribution; per address, read on-chain, and per sender from the burn events history). sentToBurnAddresses.history tells how much of the burn address balances that history explains: complete when it explains all of it (coins: history since February 2025; fungible assets: since August 2026, so an older FA burn shows a coveredPct below 100). burnedPctOfOriginal = total ÷ (current supply + destroyed). Supply Distribution also returns destroyed.

GET /api/v1/distribution/:tokenId/burns

Burns of one token.

{
  "ok": true,
  "data": {
    "tokenId": "0x…", "symbol": "…", "decimals": 6,
    "total": { "raw": "…", "amount": "…" },
    "burnedPctOfOriginal": 4.21,
    "destroyed": { "raw": "…", "amount": "…", "protocol": "atmos_token_studio", "verified": true, "at": "…",
                   "burners": [ { "wallet": "0x…", "raw": "…", "amount": "…" } ] },
    "sentToBurnAddresses": { "raw": "…", "amount": "…",
                             "addresses": [ { "wallet": "0x…dead", "raw": "…", "amount": "…" } ],
                             "senders": [ { "wallet": "0x…", "raw": "…", "amount": "…" } ],
                             "history": { "raw": "…", "amount": "…", "coveredPct": 100, "complete": true } }
  }
}

Unlock Calendar

Every lock that ends within a time window, for all tokens: Atmos Token Studio token locks and Atmos LP locker locks. An LP unlock also gives the amounts of the pool’s tokens it represents at the current reserves (legs). totals adds up, per token, what unlocks in the window, LP legs included.

GET /api/v1/unlocks

Upcoming unlocks, soonest first.

Param		Description
`within`	optional	Window from now: `30d` (default), `12h`, up to `365d`
`token`	optional	Coin type or FA address: its own locks and the LP locks of pools it is in
`kind`	optional	`token` or `lp`
`limit` / `offset`	optional	Page size (default 500, max 5000) and rows to skip

{
  "ok": true,
  "data": {
    "from": "2026-10-05T10:30:00.000Z", "to": "2026-11-04T10:30:00.000Z",
    "total": 45, "limit": 500, "offset": 0, "count": 45,
    "totals": [
      { "token": "0x1::supra_coin::SupraCoin", "symbol": "SUPRA", "raw": "395253896401168", "amount": "3952538.96401168" }
    ],
    "unlocks": [
      { "unlockAt": "2026-10-07T13:51:00.000Z", "unlockTimeSec": 1791380000, "kind": "token", "protocol": "atmos_token_studio",
        "wallet": "0x…", "token": "0x…", "symbol": "ROACH", "raw": "314085924233348", "amount": "314085924.233348" },
      { "unlockAt": "2026-10-09T00:16:00.000Z", "unlockTimeSec": 1791504960, "kind": "lp", "protocol": "atmos_lp_locker",
        "wallet": "0x…", "lpToken": "0x33db…", "dex": "ATMOS", "pool": null, "lpRaw": "…",
        "legs": [ { "token": "0x1::supra_coin::SupraCoin", "symbol": "SUPRA", "raw": "…", "amount": "105298.15" },
                  { "token": "0x927e…", "symbol": "SUPD", "raw": "…", "amount": "55856234.33" } ] }
    ]
  }
}

Staking by Token

Every place a token is staked, pool by pool, in two blocks that never overlap: direct (the token itself: Spikey meme pools, Atmos single-token farms, Pecky nodes, staking contracts such as the SUPD global staking) and viaLp (LP of the token’s pools: Spikey LP pools, Atmos LP farms, Dexlyn gauges and LP staking slots, Dexlyn concentrated-liquidity gauges), converted to the token at the current reserves. For the tokens of the holder list.

GET /api/v1/staking/:tokenId

Staking of one token.

Param		Description
`:tokenId`	required	Coin type or FA metadata address
`include`	optional	`stakers`: add each pool’s stakers with their token amount

{
  "ok": true,
  "data": {
    "tokenId": "0x635f…a9007::ROBBIE::ROBBIE", "symbol": "ROBBIE", "decimals": 6,
    "direct": { "raw": "…", "amount": "105691672.99", "pools": [
      { "protocol": "spikey", "pool": "0x…|0x…|0x…", "label": "ROBBIE", "raw": "…", "amount": "66884915.72", "stakerCount": 32 } ] },
    "viaLp": { "raw": "…", "amount": "91647348.18", "pools": [
      { "protocol": "atmos_farm", "pool": "0x…", "label": "JOSHKU/ROBBIE LP", "lpToken": "0x1641…", "raw": "…", "amount": "60551429.17", "stakerCount": 10 } ] }
  }
}

protocol: spikey, atmos_farm, pecky, contract (a staking contract without per-wallet data, stakerCount: null), dexlyn_gauge, dexlyn_lp_staking, dexlyn_clmm_gauge.

Lending

Lending markets, one row per protocol and token (Supralend today). supplied is the value of all lend shares (interest included), borrowed the borrowed amount with interest, available the cash left in the pool, reserve the protocol reserve. borrowed can exceed supplied while interest and reserve accrue. verified: the lenders’ shares add up to the pool’s total shares. Refreshed every 30 minutes.

GET /api/v1/lending

Lending markets.

Param		Description
`token`	optional	Coin type or FA address
`protocol`	optional	`supralend`
`include`	optional	`lenders`: add every lender with its supplied amount, largest first

{
  "ok": true,
  "data": {
    "updatedAt": "2026-10-05T11:00:00.000Z",
    "count": 7,
    "markets": [
      { "protocol": "supralend", "token": "0x80f0…3a3d", "symbol": "iSUPRA", "decimals": 8,
        "supplied": "49039570.93", "borrowed": "51588003.00", "available": "4118.84", "reserve": "2845690.70",
        "utilizationPct": 105.2, "lenderCount": 41, "verified": true, "paused": false }
    ]
  }
}

Spikey Staking

Spikey staking ledger and pool lookups (meme & LP).

Ledger

GET /api/v1/stakes/spikey/ledger

Full staking ledger snapshot with all pools, staker details, and totals.

{
  "ok": true,
  "rateLimitMs": 600,
  "data": {
    "version": 1,
    "generatedAt": "2026-09-02T20:45:04.587Z",
    "poolCount": 49,
    "stakerCount": 212,
    "pools": {
      "0x...": {
        "creatorAddress": "0x...",
        "stakeTokenAddress": "0x...",
        "rewardTokenAddress": "0x...",
        "poolType": "MEME",
        "tokenLabel": "SPIKE",
        "rows": [
          { "wallet": "0x...", "amountRaw": "...", "lastTxHash": "0x..." }
        ],
        "rowCount": 11,
        "indexedTotalRaw": "325203911955000",
        "poolTotalRaw": "325203911955000"
      }
    }
  }
}

Meme Pools

GET /api/v1/stakes/spikey/memes/:tokenId

Staking pools for a specific meme token (filtered by coin type, display ID, or label).

Param		Description
`:tokenId`	required	Token address, coin type, or label (e.g. `SPIKE`)

{
  "ok": true,
  "token": "0xfec11647...",
  "poolType": "MEME",
  "count": 1,
  "data": [ { ... } ]
}

LP Pools

GET /api/v1/stakes/spikey/lp/:tokenId

LP staking pools for a specific token.

Param		Description
`:tokenId`	required	LP token address or identifier

{
  "ok": true,
  "token": "0x...",
  "poolType": "LP",
  "count": 2,
  "data": [ { ... } ]
}

Pecky Staking

Pecky node staking and Meridian SUPRA staking data.

Ledger

GET /api/v1/stakes/pecky/ledger

Full Pecky staking snapshot with all node pools, Meridian pool, and staker details.

{
  "ok": true,
  "rateLimitMs": 600,
  "data": {
    "version": 1,
    "generatedAt": "2026-09-02T...",
    "poolCount": 19,
    "stakerCount": 106,
    "pools": {
      "pecky_node:TOKEN_3": {
        "poolType": "NODE",
        "nodeId": "TOKEN_3",
        "rows": [
          { "wallet": "0x...", "amountRaw": "...", "lastTxHash": "0x..." }
        ],
        "rowCount": 6,
        "indexedTotalRaw": "..."
      },
      "pecky_meridian:supra": {
        "poolType": "MERIDIAN",
        "tokenLabel": "SUPRA",
        "rows": [ ... ],
        "rowCount": 19
      }
    }
  }
}

Pools by Token

GET /api/v1/stakes/pecky/:tokenId

Pecky staking pools for a specific token or node.

Param		Description
`:tokenId`	required	Token address, node ID, or label (e.g. `TOKEN_3`, `SUPRA`)

{
  "ok": true,
  "token": "TOKEN_3",
  "count": 1,
  "data": [ { ... } ]
}

SVLT (SupraVault) Staking

SupraVault token holder data from on-chain snapshots.

Ledger

GET /api/v1/stakes/svlt/ledger

SupraVault protocol info and contract addresses.

{
  "ok": true,
  "rateLimitMs": 600,
  "data": {
    "version": 1,
    "protocol": "SupraVault",
    "svltMeta": "0x2a0f3e6fb5d0f25c0d75cc4ffb93ace26757939fd4aa497c7f1dbaff7e3c6358",
    "v1Package": "0x81ca29bb...",
    "v2Module": "0xd1c64ad5...::staking_v24"
  }
}

Staking by Wallet

GET /api/v1/stakes/svlt/:wallet

SupraVault staking breakdown for a specific wallet (V1 + V2). Queries the chain live.

Param		Description
`:wallet`	required	Wallet address (0x...)

{
  "ok": true,
  "data": {
    "wallet": "0x5bf50161...",
    "svltMeta": "0x2a0f3e6f...",
    "totalStakedRaw": "261695499296216",
    "v1": {
      "stakedRaw": "100000000",
      "pendingWithdrawRaw": "0",
      "claimableWithdrawRaw": "50000000"
    },
    "v2": {
      "stakedRaw": "261695399296216",
      "pendingWithdrawRaw": "0",
      "pendingClaimRaw": "0",
      "earnedRaw": "1234567890"
    }
  }
}

totalStakedRaw — Total staked across V1 + V2
v1.stakedRaw — V1 staked amount (stSvlt)
v1.pendingWithdrawRaw — V1 pending withdrawal requests
v1.claimableWithdrawRaw — V1 claimable withdrawn tokens
v2.stakedRaw — V2 staked amount
v2.pendingWithdrawRaw — V2 pending withdrawal
v2.pendingClaimRaw — V2 pending claim
v2.earnedRaw — V2 earned rewards preview

Atmos Farms

Atmos liquidity farm staking data — pool totals, user stakes, and reward info.

Ledger

GET /api/v1/atmos/farms/ledger

Full Atmos farm staking snapshot with all pools, staker details, and totals.

{
  "ok": true,
  "rateLimitMs": 600,
  "data": {
    "version": 1,
    "generatedAt": "2026-09-02T...",
    "poolCount": 12,
    "stakerCount": 85,
    "refs": {
      "atfs_xxx": {
        "poolAddress": "0x...",
        "stakeMetadataAddress": "0x...",
        "rewardMetadataAddress": "0x..."
      }
    },
    "pools": {
      "0x...": {
        "poolAddress": "0x...",
        "tokenLabel": "ROBBIE",
        "poolType": "LP",
        "tokenA": "0x...",
        "tokenB": "0x...",
        "rewardTokenLabel": "SUPRA",
        "decimals": 8,
        "rewardDecimals": 8,
        "rows": [
          { "wallet": "0x...", "amountRaw": "...", "lastTxHash": "0x..." }
        ],
        "rowCount": 11,
        "indexedTotalRaw": "50000000000",
        "poolTotalRaw": "50000000000"
      }
    }
  }
}

Farms by Token

GET /api/v1/atmos/farms/:tokenId

Atmos farm pools for a specific token (filtered by coin type, label, or address).

Param		Description
`:tokenId`	required	Token address, coin type, or label (e.g. `ROBBIE`)

{
  "ok": true,
  "token": "0xfec11647...",
  "count": 1,
  "data": [ { ... } ]
}

Wallet Positions

Everything one wallet holds in a protocol: tokens in the wallet, liquidity, stakes, locks and protocol positions, with their value in USD.

Amounts come as raw (base units, digit string) and amount (decimal string). usd is null when the token price or decimals are unknown; such positions are left out of totals and counted in totals.unpricedPositions. LP tokens are converted to the pool's tokens with the latest indexed reserves (reservesAt). Rewards not claimed yet are not included: they are not held by the wallet yet.

A part that cannot be read is listed in errors with partial: true; it is never reported as zero.

Solido Money

GET /api/v1/wallets/:wallet/solido

Wallet balances of CASH, bCASH, SOLID, stSOLID and stSUPRA (holder index; a token the index cannot serve yet is flagged available: false with its blockers), CDP troves (collateral and debt), pending withdrawals of the bCASH, stSUPRA and SOLID staking vaults, vote-escrow (veSOLID) locks, airdrop vesting and ecoSUPRA. Protocol positions are read on chain; USD values use the Solido Money prices.

Param		Description
`:wallet`	required	Supra address (padded or not)

{
  "ok": true,
  "data": {
    "wallet": "0x0e9d1f33...",
    "walletBalances": [ { "symbol": "stSUPRA", "tokenId": "0x8184...::vault_core::VaultShare", "available": true, "amount": "220161.35323086", "raw": "22016135323086", "usd": 37.25 } ],
    "cdp": {
      "troves": [ { "collateral": "stSUPRA", "collateralMetadata": "0x98e4...", "collateralAmount": { "amount": "512331.83661349", "raw": "...", "usd": 86.69 }, "debt": { "amount": "24.83269563", "raw": "...", "usd": 24.83 }, "active": true } ],
      "totalDebt": { "amount": "46.83270028", "raw": "4683270028", "usd": 46.83 }
    },
    "pendingWithdrawals": {
      "bCash": { "asset": "CASH", "amount": "0", "raw": "0", "usd": 0, "requests": [] },
      "stSupra": { "asset": "SUPRA", "amount": "81007.74385789", "raw": "...", "usd": 12.61, "requests": [ { "requestId": "214", "amount": "30041.6214441", "raw": "...", "usd": 4.68, "requestedAt": "2026-10-05T..." } ] },
      "stSolid": { "asset": "SOLID", "amount": "0", "raw": "0", "usd": 0, "requests": [] }
    },
    "veSolid": {
      "locked": { "amount": "6555.49274308", "raw": "...", "usd": 19.34 },
      "expectedTotal": { "amount": "24095.47822924", "raw": "...", "usd": 71.07 },
      "locks": [ { "lockId": "0x...", "locked": { ... }, "expectedTotal": { ... }, "unlockAt": "2027-11-15T...", "durationDays": 730, "aprPct": 400, "unlocked": false } ]
    },
    "airdropVesting": { "total": { ... }, "released": { ... }, "locked": { ... }, "releasable": { ... }, "startedAt": "2025-11-15T..." },
    "ecoSupra": { "sharesRaw": "189203041089", "supra": { "amount": "574.07729265", "raw": "57407729265", "usd": 0.09 } },
    "totals": { "assetsUsd": 204.11, "debtUsd": 46.83, "netUsd": 157.28, "pricesAvailable": true },
    "rates": { "bCashToCash": "1.20011075", "stSupraToSupra": "1.08671457", "stSolidToSolid": "1.20123208" },
    "prices": { "SUPRA": 0.00015569, "stSUPRA": 0.0001692, "CASH": 1, "bCASH": 1.20011, "SOLID": 0.00295, "stSOLID": 0.00354 },
    "partial": false,
    "errors": []
  }
}

veSolid.expectedTotal is the amount paid out at unlock (lock plus its rewards) and is not counted in totals; totals.assetsUsd counts the locked amount only.

Hoglet

GET /api/v1/wallets/:wallet/hoglet

Hoglet (Spikey) LP tokens in the wallet, staking pools (meme tokens and LP) and SPIKE DAO locks.

Param		Description
`:wallet`	required	Supra address (padded or not)

{
  "ok": true,
  "data": {
    "wallet": "0xdf527ade...",
    "protocol": "hoglet",
    "liquidity": {
      "usd": 0,
      "positions": [ {
        "dex": "SPIKEY", "lpToken": "0x7117...", "pool": "0x7117...", "name": "Spiker SUPRA-SPIKE LP",
        "lpRaw": "1000000000000", "poolSharePct": 0.1478,
        "tokens": [ { "tokenId": "0x...", "symbol": "SUPRA", "raw": "17655584019", "amount": "176.55584019", "usd": 0.03 }, { "tokenId": "0xbcfc...", "symbol": "SPIKE", "raw": "...", "amount": "...", "usd": 0.03, "wrappedOf": "0xfec1...::memecoins::SPIKE" } ],
        "usd": 0.06, "reservesAt": "2026-10-06T..."
      } ],
      "coverage": { "lpTokens": 21, "ready": 20, "notReady": 1 }
    },
    "staking": [
      { "pool": "0x3045...|0xbcfc...|0xbcfc...", "type": "MEME", "label": "SPIKE", "rewardToken": "SPIKE", "token": { ... }, "usd": 49.57 },
      { "pool": "...", "type": "LP", "label": "Spiker SUPRA-SPIKE LP", "rewardToken": "SPIKE", "lp": { ... }, "usd": 0.06 }
    ],
    "daoLocks": [ { "nft": "0x...", "dao": "0x4140...", "locked": { ... }, "endEpoch": 3167, "usd": 0.16 } ],
    "totals": { "usd": 51, "unpricedPositions": 0 },
    "partial": false,
    "errors": []
  }
}

Atmos

GET /api/v1/wallets/:wallet/atmos

Atmos LP tokens in the wallet, farm stakes, LP locked in the Atmos LP locker and Token Studio token locks (with their unlock date).

Param		Description
`:wallet`	required	Supra address (padded or not)

{
  "ok": true,
  "data": {
    "wallet": "0x1a423915...",
    "protocol": "atmos",
    "liquidity": { "usd": 1803.41, "positions": [ { "dex": "ATMOS", "name": "SAIYANS/BEYOND8", "lpRaw": "...", "poolSharePct": 2.1, "tokens": [ ... ], "usd": 253.92 } ], "coverage": { "lpTokens": 798, "ready": 798, "notReady": 0 } },
    "farms": [ { "farm": "0x7a82...", "label": "SUPRA/BEYOND8 LP", "rewardToken": "BEYOND8", "lp": { ... }, "usd": 51.62 } ],
    "lpLocks": [ { "lp": { ... }, "unlockAt": "2027-07-23T00:11:07.000Z", "unlocked": false, "usd": 56.53 } ],
    "tokenStudioLocks": [ { "locked": { "symbol": "SAIYANS", "amount": "250000000", ... }, "unlockAt": "2026-10-20T10:38:37.000Z", "unlocked": false, "usd": 2109.21 } ],
    "totals": { "usd": 5331.38, "unpricedPositions": 0 },
    "partial": false,
    "errors": []
  }
}

Dexlyn

GET /api/v1/wallets/:wallet/dexlyn

Dexlyn LP tokens in the wallet, LP staked in DXLYN gauges or LP staking slots, concentrated liquidity positions (NFTs, with inRange and gauge staking), perps one-click trading vaults and veDXLYN locks (NFTs owned or staked in the veDXLYN gauge; voting power as of readAt).

Param		Description
`:wallet`	required	Supra address (padded or not)

{
  "ok": true,
  "data": {
    "wallet": "0x4443defc...",
    "protocol": "dexlyn",
    "liquidity": { "usd": null, "positions": [], "coverage": { "lpTokens": 52, "ready": 51, "notReady": 1 } },
    "lpStaking": [ { "contract": "0x1a7e...", "kind": "gauge", "lp": { "dex": "DEXLYN", "lpToken": "0x22a2...::lp_coin::LP<...>", "tokens": [ ... ], "usd": 4.33 }, "usd": 4.33 } ],
    "clmmPositions": [ { "nft": "0x...", "pool": "0x...", "name": "Dexlyn Position | SUPRA-CASH_tick(10)", "staked": false, "gauge": null, "liquidity": "...", "tickLower": -100, "tickUpper": 100, "inRange": true, "tokens": [ ... ], "usd": 3.19, "at": "2026-10-06T..." } ],
    "perps1ctVaults": [ { "tokenId": "0x9176...::cdp_multi::cash", "symbol": "CASH", "raw": "1803147717", "amount": "18.03147717", "usd": 14.72 } ],
    "veDxlyn": [ { "nft": "0x4329...", "name": "veDXLYN NFT position #408", "locked": { "symbol": "DXLYN", "amount": "50", ... }, "unlockAt": "2026-12-03T00:00:00.000Z", "perpetual": false, "unlocked": false, "votingPower": "1.970708866524", "staked": true, "gauge": "0x8428...", "readAt": "2026-10-06T...", "usd": 0.27 } ],
    "totals": { "usd": 7.53, "unpricedPositions": 0 },
    "partial": false,
    "errors": []
  }
}

History by Token

GET /api/v1/wallets/:wallet/history/:tokenId

A wallet's activity in one token, newest first, one item per transaction: buy / sell (with the swap route), transfer_in / transfer_out (with the counterparties), lp_add, lp_remove, pool_init, stake, unstake, claim, token_lock, lp_lock, burn. delta is the change of the token's balance in the wallet, incoming fungible asset transfers included. Tokens of Available Tokens.

Param		Description
`:wallet`	required	Supra address (padded or not)
`:tokenId`	required	Coin type or fungible asset address of a listed token
`limit`	optional	Transactions per page, default 50, max 200
`before`	optional	Block height cursor: pass `nextBefore` of the previous page
`types`	optional	Comma-separated groups: `swap`, `transfer`, `lp`, `stake`, `lock`, `burn`

{
  "ok": true,
  "data": {
    "wallet": "0x1a423915...",
    "token": { "tokenId": "0x838ba9d6...", "symbol": "SAIYANS", "decimals": 6 },
    "count": 8,
    "items": [
      { "txHash": "0x9fe297a6...", "blockHeight": 55285700, "time": "2026-10-05T13:47:44.523Z", "type": "lp_add",
        "delta": { "direction": "out", "raw": "6138494590186", "amount": "6138494.590186" },
        "events": [ { "family": "lp_event", "kind": "lp_add", "protocol": "ATMOS", "pool": "0x..." } ] },
      { "txHash": "0x...", "blockHeight": 55229248, "time": "2026-10-04T21:58:55.107Z", "type": "buy",
        "delta": { "direction": "in", "raw": "272928994", "amount": "2.72928994" },
        "swap": [ { "dex": "ATMOS", "in": { "tokenId": "0x1::supra_coin::SupraCoin", "symbol": "SUPRA", "raw": "...", "amount": "..." }, "out": { ... }, "routeStep": true } ],
        "events": [] },
      { "txHash": "0x...", "blockHeight": 51594946, "time": null, "type": "transfer_in",
        "delta": { "direction": "in", "raw": "62000000", "amount": "0.62" },
        "counterparties": [ "0x4443defc..." ], "events": [] }
    ],
    "nextBefore": 55193648,
    "coverage": { "balanceChangesFromBlock": 51459152, "activityFromBlock": 48173119, "note": "..." }
  }
}

Coverage: balance changes are known from block ~51.46M (August 12, 2026), swaps, liquidity and staking events from block ~48.17M (late June 2026); an older transaction keeps its action with delta: null, and time is null when the index has no timestamp for it. delta: null on a recent swap means the token only passed through an aggregator route without touching the wallet's balance. This is an activity log, not a ledger: no running balance is computed from it.

Trades

Note: Trade data is recorded live as the bot processes transactions. Historical backfill is not available yet.

Trades 24h

GET /api/v1/trades/24h/:tokenId

List of trades for a token in the last 24 hours.

Param		Description
`:tokenId`	required	Token address (Supra FA address)

{
  "ok": true,
  "token": "0x166f64842216...",
  "period": "24h",
  "count": 12,
  "data": [
    {
      "ingestedAt": "2026-09-02T00:00:00.000Z",
      "ts": 1788297600,
      "token": "0x166f64842216...",
      "side": "BUY",
      "valueUsd": 12.5,
      "priceUsd": 0.001,
      "dex": "ATMOS",
      "wallet": "0xa1684...",
      "hash": "0x072600..."
    }
  ]
}

ts — Unix timestamp (seconds)
side — "BUY" or "SELL"
valueUsd — USD value of the trade
priceUsd — Token price in USD at time of trade
dex — ATMOS, ATMOS TOKEN STUDIO, SPIKEY, ATMOS_AGG, DEXLYN, LEOEX
wallet — Trader wallet address
hash — Transaction hash

Trades 7d

GET /api/v1/trades/7d/:tokenId

List of trades for a token in the last 7 days.

Param		Description
`:tokenId`	required	Token address

{
  "ok": true,
  "token": "0x166f64842216...",
  "period": "7d",
  "count": 87,
  "data": [ ... ]
}

Volume

Volume 24h

GET /api/v1/volume/24h/:tokenId

Aggregate volume and trade count for a token in the last 24 hours.

Param		Description
`:tokenId`	required	Token address

{
  "ok": true,
  "token": "0x166f64842216...",
  "period": "24h",
  "tradeCount": 12,
  "volumeUsd": 156.8
}

Volume 7d

GET /api/v1/volume/7d/:tokenId

Aggregate volume and trade count for a token in the last 7 days.

Param		Description
`:tokenId`	required	Token address

{
  "ok": true,
  "token": "0x166f64842216...",
  "period": "7d",
  "tradeCount": 87,
  "volumeUsd": 2340.5
}

Market & Tokens

Read-only token and market data for Solana (Nibble / Meteora) and Supra tokens. Like every other endpoint, these require an API key.

API key required Requests without a valid key are rejected with 401 unauthorized. Standard per-key rate limits apply; Premium API Keys bypass the application-level quota.

Token identifier (`:tokenId`)

The chain is detected automatically from the format of :tokenId:

Chain	Format	Example
Solana	Base58 mint address	`pcBeadR2nw…GtAiWPNiBL`
Supra	Hex address or full coin type, URL-encoded	`0x1234…abcd` or `0x1234…::ROBBIE::ROBBIE`

Any other format returns 400 invalid_tokenId. The response always includes chain, and the fields returned differ by chain (see below).

Token Summary

GET /api/v1/tokens/:tokenId/summary

Snapshot of a token. Solana returns live market data (price, market cap, bonding curve, volume, holders); Supra returns indexed activity counts.

On Solana, market fields (priceUsd, marketCapUsd, priceChange24hPct, bondingCurvePct, isComplete, launchpad) are null if upstream price sources are temporarily unreachable; the rest of the summary is still returned.

Param		Description
`:tokenId`	required	Solana mint or Supra address / coin type

Solana response

{
  "ok": true,
  "data": {
    "tokenId": "pcBead...",
    "chain": "solana",
    "symbol": "FRAN",
    "name": "Fran",
    "dex": "meteora",                 // null while still on the bonding curve
    "priceUsd": 0.00003892,
    "marketCapUsd": 38916,
    "priceChange24hPct": -16.51,
    "bondingCurvePct": 100,           // 0–100; 100 once graduated
    "isComplete": true,               // true = graduated (migrated to Meteora)
    "launchpad": "Nibble",            // e.g. "Nibble", "Raydium LaunchLab"
    "dexPrice": {                     // latest on-chain price observation, or null
      "baseAmountRaw": "297398779162",
      "quoteAmountRaw": "99196818",
      "quoteMint": "So111...112",
      "source": "swap",               // "swap" or "reserves"
      "at": 1790163057
    },
    "volume24hUsd": 15600,
    "tradeCount": 87,
    "holders": 342,
    "totalBurnedRaw": "0",
    "burnerCount": 0
  }
}

Supra response

{
  "ok": true,
  "data": {
    "tokenId": "0x...::ROBBIE::ROBBIE",
    "chain": "supra",
    "symbol": "ROBBIE",
    "name": "Robbie",
    "totalEvents": 5120,
    "swapCount": 3400,
    "lpEventCount": 210,
    "burnCount": 12,
    "transferCount": 1498,
    "tradeCount24h": 87,
    "tradeCountPrev24h": 64,
    "lastSeen": "2026-09-23T12:00:00.000Z",
    "families": { "swap": 3400, "transfer": 1498, "lp_event": 210, "burn": 12 }
  }
}

Token Activity

GET /api/v1/tokens/:tokenId/activity

Event history for a token, newest first, with cursor pagination.

Param		Description
`:tokenId`	required	Solana mint or Supra address / coin type
`type`	optional	Comma-separated event types. Solana: `swap`, `graduation`, `pool_init`, `lp_add`, `lp_remove`, `lp_lock`. Supra: event `kind` values (e.g. `swap`).
`limit`	optional	Events per page (default 50, max 200)
`before`	optional	The `cursor` from the previous page. On Supra it can also be an ISO date (e.g. `2026-09-01T00:00:00Z`).
`chain`	optional	`all` (default), `solana` or `supra`. Returns `400 chain_mismatch` if it doesn't match the token.

{
  "ok": true,
  "data": {
    "tokenId": "pcBead...",
    "chain": "solana",
    "events": [
      {
        "type": "swap", "side": "BUY", "mint": "pcBead...",
        "baseAmountRaw": "...", "quoteAmountRaw": "...", "quoteMint": "So111...112",
        "trader": "8J63...", "pool": "Amwk...", "signature": "31Jx...",
        "blockTime": 1790163057, "chain": "solana"
      }
    ],
    "hasMore": true,
    "cursor": "eyJ..."             // pass as ?before= to get the next page
  }
}

Supra events have this shape: { id, chain, family, kind, blockHeight, blockTimestamp, txHash, sender, function, wallet, assetId, assets, amountRaw, data, indexedAt }.

GET /api/v1/market/trending

Tracked tokens ranked by 24h volume or 24h trade count, across both chains.

Param		Description
`sort`	optional	`volume` (default) or `trades`
`chain`	optional	`all` (default), `solana` or `supra`
`limit`	optional	Max tokens returned (default 20, max 50)

{
  "ok": true,
  "data": {
    "sort": "volume",
    "chain": "all",
    "tokens": [
      { "rank": 1, "tokenId": "pcBead...", "chain": "solana", "symbol": "FRAN",
        "dex": "meteora", "volume24hUsd": 15600, "tradeCount": 87 },
      { "rank": 2, "tokenId": "0x...::ROBBIE::ROBBIE", "chain": "supra", "symbol": "ROBBIE",
        "volume24hUsd": 9800, "tradeCount": 54 }
    ]
  }
}

Graduations

GET /api/v1/market/graduations

Recent bonding-curve graduations, newest first. On Solana, graduated tokens migrate to Meteora.

Param		Description
`chain`	optional	`all` (default), `solana` or `supra`
`limit`	optional	Max results (default 20, max 50)

{
  "ok": true,
  "data": {
    "graduations": [
      { "chain": "solana", "type": "graduation", "mint": "...", "signature": "...", "blockTime": 1790163057 },
      { "chain": "supra", "tokenId": "0x...", "txHash": "0x...", "blockHeight": 51430000,
        "blockTimestamp": "2026-09-08T12:00:00.000Z", "data": { ... } }
    ]
  }
}

Premium API

Real-time SSE streams require a Premium API Key. Standard API keys receive 403 super_key_required (the current API error code).

Premium API Key Required These endpoints are available with premium access and cannot be used with a standard API key.

SSE Events Stream

GET /api/v1/stream/events

Real-time Server-Sent Events stream of swaps, burns, LP events, and graduations.

Param		Description
`mint`	optional	Filter by token mint address
`type`	optional	Comma-separated: `swap`, `burn`, `lp_add`, `lp_remove`, `lp_lock`, `pool_init`

event: swap
data: {"mint":"...","type":"swap","side":"buy","amountUsd":12.5,"wallet":"...",...}

event: heartbeat
data: {"ts":1725782400}

Heartbeat every 30s to keep connection alive
Max 100 concurrent connections
Events are read from local JSONL ledgers in real-time

Events History (REST)

The past side of the events stream: on-chain events of every token, newest first, paged with cursor. Premium key only. Each burn event carries burnKind (destroyed or sent_to_burn_address, the burn address in data.burnAddress), the same split as Burns by Token. Transfers of coins to burn addresses are covered since February 2025; fungible assets since August 2026.

GET /api/v1/events

Events history (Supra).

Param		Description
`type`	optional	Comma-separated: `burn`, `token_lock`, `token_unlock`, `lp_add`, `lp_remove`, `lp_lock`, `lp_unlock`, `pool_init`, `farm_stake`, `farm_unstake`, `farm_init`, `rewards_claim`, `swap`. Default: every type except `swap`
`token`	optional	Coin type or FA address: only that token’s events. Required for `type=swap`
`burnKind`	optional	`destroyed` (Atmos Token Studio burns: the tokens no longer exist) or `sent_to_burn_address` (transfers to `0xff…ff`, `0x0…0ff…ff`, `0x…dead` or `0x0`), comma-separated
`limit`	optional	Page size (default 50, max 500)
`before`	optional	The `cursor` of the previous page, or an ISO date

{
  "ok": true,
  "data": {
    "types": ["burn", "token_lock"],
    "events": [
      { "type": "token_lock", "id": "…", "chain": "supra", "family": "lp_event", "kind": "token_lock",
        "blockHeight": 55241755, "blockTimestamp": "2026-10-04T07:04:00.000Z", "txHash": "0x…",
        "sender": "0x…", "function": "0x707d…::token_studio_locker::lock_tokens", "wallet": "0x…",
        "assetId": "0x…", "assets": ["0x…"], "amountRaw": "…", "data": { … } }
    ],
    "hasMore": true,
    "cursor": "…"
  }
}

SSE Prices Stream

GET /api/v1/stream/prices

Real-time price updates for all tracked tokens. Broadcasts every 5 seconds when prices change.

event: prices
data: {"tokens":{"MINT_ADDRESS":{"priceUsd":0.00042,"marketCapUsd":42000},...}}

Polling interval: 5s (configurable via PUBLIC_API_PRICES_POLL_MS)
Only sends data when at least one price changes

Error Responses

Code	Error	Description
`401`	`unauthorized`	Missing or invalid API key
`403`	`super_key_required`	Endpoint requires a Premium API Key (legacy error code)
`404`	`not_found`	Unknown endpoint
`404`	`token_not_available`	Holder list not available for this token (see `/api/v1/holders/tokens`)
`400`	`invalid_tokenId` / `invalid_filter` / `chain_mismatch` / `invalid_include` / `invalid_wallet`	Bad token identifier or query parameter
`405`	`method_not_allowed`	Wrong HTTP method
`429`	`rate_limited`	Too many requests — check `retryAfterSec`
`500`	`snapshot_failed`	Internal error generating snapshot
`503`	`trade_ledger_unavailable`	Trade ledger not initialized
`503`	`holders_not_ready`	Token temporarily paused while the holder index re-verifies it (`blockers` lists why)
`503`	`data_source_unavailable`	Market/token data source temporarily unavailable

{
  "error": "rate_limited",
  "retryAfterSec": 290,
  "rateLimitMs": 600
}

Changelog

Date	Change
Oct 2026	Added History by Token (`/api/v1/wallets/:wallet/history/:tokenId`): a wallet's activity in one token with the balance change of each transaction, incoming fungible asset transfers included
Oct 2026	Added the Wallet Positions section: everything a wallet holds in Solido Money (`/api/v1/wallets/:wallet/solido`), Hoglet, Atmos and Dexlyn (`/api/v1/wallets/:wallet/{hoglet,atmos,dexlyn}`), valued in USD
Oct 2026	Supply Distribution adds `rewards` (rewards not paid out yet in Atmos farms and Spikey staking pools) and `liquidity.ownership.lockedAtGraduation` (LP kept by Atmos when a Token Studio token graduates); Spikey pools now use live reserves in every LP route
Oct 2026	Added the Distribution section: Supply Distribution (`/api/v1/distribution/:tokenId`), Locks by Token (`/api/v1/distribution/:tokenId/locks`), Burns by Token (`/api/v1/distribution/:tokenId/burns`), the Unlock Calendar (`/api/v1/unlocks`), Staking by Token (`/api/v1/staking/:tokenId`) and Lending (`/api/v1/lending`), and the premium Events History (`/api/v1/events`); the wallet breakdown adds Dexlyn staked LP, Supralend, perps one-click trading vaults and Atmos Token Studio locks
Oct 2026	LP holder routes and the wallet liquidity breakdown now cover Dexlyn (classic and concentrated liquidity) and LeoEx pools, with 1:1 wrapped tokens counted as their origin token; more tokens in the holder list (see Available Tokens)
Sep 2026	Added Supra holder endpoints (available tokens, holder list, wallet balance with staking / liquidity / locks breakdown) for verified complete tokens, new fungible assets listed automatically; the holder list includes every account by default (`include=all`)
Sep 2026	Added Market & Tokens endpoints for Solana and Supra (token summary/activity, trending, graduations) and premium SSE streams
Sep 2026	Added Premium API Key rate-limit bypass, Terms of Use, Security guidelines
Aug 2026	Added trades 7d, volume 7d endpoints
Aug 2026	Initial release: stakers, ledger, meme/LP pools, trades 24h, volume 24h

RBB Gateway API by @robbiesuprameme — See Terms of Use

RBB Gateway API Documentation

Authentication

Rate Limits

API Key Types

Security Best Practices

Prohibited Usage

Terms of Use

1. Access & Authorization

2. Data Usage

3. Availability

Key Revocation Policy

After revocation

Premium API Key

Limitation of Liability

Holders (Supra)

Coin & FA aliases (automatic)

Token identifier (:tokenId)

Available Tokens

Holder List

Wallet Balance

How a token reaches the holder API

Automatic indexing at launch

Manual reconstruction for older or missed tokens

Publication and availability

Liquidity Pools

LP Held in Wallets

DEX coverage

Supply Distribution

Locks by Token

Burns by Token

Unlock Calendar

Staking by Token

Lending

Spikey Staking

Ledger

Meme Pools

LP Pools

Pecky Staking

Ledger

Pools by Token

SVLT (SupraVault) Staking

Ledger

Staking by Wallet

Atmos Farms

Ledger

Farms by Token

Wallet Positions

Solido Money

Hoglet

Atmos

Dexlyn

History by Token

Trades

Trades 24h

Trades 7d

Volume

Volume 24h

Volume 7d

Market & Tokens

Token identifier (:tokenId)

Token Summary

Token Activity

Trending

Graduations

Premium API

SSE Events Stream

Events History (REST)

SSE Prices Stream

Error Responses

Changelog

Token identifier (`:tokenId`)

Token identifier (`:tokenId`)