Token Supply API

Public REST endpoints that serve CLAIM token supply data for indexers such as CoinGecko, CoinMarketCap, DeFiLlama, and any third-party aggregator.

Endpoints

All endpoints are unauthenticated, return JSON, and are safe to poll at any frequency. Responses are cached for 5 minutes (max supply: 24 hours).

GET /api/supply/total

Returns the current total supply of CLAIM (all minted tokens minus any burned).

GET https://claimru.sh/api/supply/total

Response:

{ "result": "14349000.00" }

GET /api/supply/circulating

Returns the circulating supply: total supply minus CLAIM locked in veCLAIM.

GET https://claimru.sh/api/supply/circulating

Response:

{ "result": "12000000.00" }

GET /api/supply/max

Returns null — CLAIM has no hard-coded max supply. Supply starts at 0 and is minted continuously by MineCore with a decaying emission schedule.

GET https://claimru.sh/api/supply/max

Response:

{ "result": null }

Error responses

On failure (RPC unreachable, contracts not deployed), all endpoints return HTTP 502:

{ "result": null, "error": "SUPPLY_NO_RPC_URL" }

Supply methodology

Formula

totalSupply       = ClaimToken.totalSupply()
lockedSupply      = VeClaimNFT.totalLockedClaim()
circulatingSupply = totalSupply - lockedSupply

Both values are read from Base mainnet via eth_call against the latest block.

On-chain sources

Contract addresses are loaded from deployments/<network>.json.

Why exclude locked tokens?

CoinGecko’s official supply methodology  states:

Locked Tokens: Tokens that are locked via smart contracts or other time-based lockups are excluded.

This matches the Aerodrome (AERO) precedent on Base: CoinGecko shows AERO circulating supply as totalSupply - veAERO locked balance. As of April 2026, AERO total supply is ~1.875B with ~954M locked in the Voting Escrow contract, producing a circulating supply of ~921M — which matches the CoinGecko listing exactly.

CLAIM follows the same ve-tokenomics model, so the same formula applies.

Extending circulating supply exclusions

If additional wallets need to be excluded in the future (team treasury, foundation, vesting contracts), add their addresses to deployments/<network>.json > analytics.addressExclusions and update the circulating supply calculation in frontend/src/app/api/supply/_lib/onchain.ts.

Indexer listing guide

CoinGecko

1. Ensure CLAIM is listed on CoinGecko (submit via their listing form).
2. Submit a supply update request at CoinGecko Supply Updates  (requires CoinGecko account).
3. Provide:
   • Circulating supply endpoint: https://claimru.sh/api/supply/circulating
   • Total supply endpoint: https://claimru.sh/api/supply/total
4. CoinGecko polls approximately every 30 minutes.

CoinMarketCap

1. Submit a listing request via the CMC listing form.
2. Fill out the token data sheet with:
   • Total supply endpoint: https://claimru.sh/api/supply/total
   • Circulating supply endpoint: https://claimru.sh/api/supply/circulating
   • Top 20 holder wallets (from Basescan)
3. CMC requires a single number in JSON format — these endpoints satisfy that requirement.

Other indexers

The same endpoints work for DeFiLlama, Dexscreener, Mobula, and any aggregator that accepts a JSON REST endpoint returning a supply number.

Cloudflare WAF configuration

CoinGecko’s crawler sends these headers when polling supply endpoints:

User-Agent: CoinGecko + https://coingecko.com/
X-Requested-With: com.coingecko

If Cloudflare WAF or Bot Management is active on claimru.sh, create a WAF rule to allow requests matching:

• User-Agent contains CoinGecko
• X-Requested-With equals com.coingecko

Without this rule, CoinGecko’s automated requests may be blocked by Cloudflare’s bot detection, preventing supply data from updating.

Implementation details