VENUM Supply & Market Data

Public endpoints for the VENUM token's supply and market figures. No authentication required. Supply responses follow the CoinGecko / CoinMarketCap submission format (a single-field JSON object with a decimal-applied, human-readable number).

All values are computed live from on-chain state. Supply is cached 60s in-process; price (for market cap / FDV) is cached 30s. CG/CMC poll hourly, so these caches only smooth bursts.

Supply model

Figure	Source	Notes
Max supply	Constant 1,000,000,000	Genesis ceiling. The mint authority is revoked, so no new VENUM can ever be created. Supply can only shrink.
Total supply	Live on-chain mint supply (getTokenSupply)	Equals 1B − cumulative burned. Buyback burns (SPL Token Burn) decrement the mint, so this number drops for real — see the buyback policy.
Circulating supply	total − Σ(locked balances)	Locked = 7 Squads multisig vaults + 2 Jupiter Lock vest escrows. Permanent-locked LP is not subtracted (CG convention treats it as circulating liquidity).

Market cap and FDV use the canonical VENUM price (the same /v1/prices source the dApp uses):

• marketCapUsd = priceUsd × circulatingSupply
• fdvUsd = priceUsd × totalSupply

GET /v1/venum/circulating-supply

GET /v1/venum/circulating-supply

{ "circulatingSupply": 1200005.894164 }

Field	Type	Description
circulatingSupply	number	Live total minus locked balances, decimal-applied.

This is the URL to put in the CoinGecko / CoinMarketCap "circulating supply API" field:

https://api.venum.dev/v1/venum/circulating-supply

GET /v1/venum/total-supply

GET /v1/venum/total-supply

{ "totalSupply": 1000000000 }

Field	Type	Description
totalSupply	number	Live on-chain mint supply (1B − cumulative burned).

If the on-chain read fails, this falls back to the genesis 1,000,000,000 so the endpoint never errors.

GET /v1/venum/max-supply

GET /v1/venum/max-supply

{ "maxSupply": 1000000000 }

Field	Type	Description
maxSupply	number	Constant genesis ceiling. Mint authority revoked.

GET /v1/venum/market-cap

GET /v1/venum/market-cap

{
  "marketCapUsd": 14640.07,
  "priceUsd": 0.0122,
  "circulatingSupply": 1200005.894164
}

Field	Type	Description
marketCapUsd	number | null	priceUsd × circulatingSupply. null if price is unavailable.
priceUsd	number | null	Canonical VENUM price.
circulatingSupply	number	Same value as /v1/venum/circulating-supply.

GET /v1/venum/fdv

GET /v1/venum/fdv

{
  "fdvUsd": 12200000,
  "priceUsd": 0.0122,
  "totalSupply": 1000000000
}

Field	Type	Description
fdvUsd	number | null	priceUsd × totalSupply. null if price is unavailable.
priceUsd	number | null	Canonical VENUM price.
totalSupply	number	Same value as /v1/venum/total-supply.

Caching & availability

These endpoints are computed from on-chain state but designed to answer instantly and never stall a poller:

• Stale-while-revalidate. A value newer than ~60s returns immediately. A stale value is also returned immediately while a single background refresh runs. Only a cold cache (right after a restart) waits on a live read, and that wait is bounded by a 6s internal timeout. So once warm, the endpoint always answers from cache — a slow upstream can't make it hang.
• Always answers. total-supply falls back to the genesis 1,000,000,000 if a live read fails; circulating serves its last-known value. market-cap / fdv return null for the USD figure if the price feed is briefly unavailable rather than erroring.
• CORS. Access-Control-Allow-Origin: * on GET, so browsers and third-party dashboards can read these directly.
• Cache-Control. A 60s Cache-Control is set so a CDN (e.g. CoinGecko's) can hold the response too.

total (a single getTokenSupply) and circulating (which additionally sums the locked-address balances) are cached independently, so reading total-supply / fdv never pays for the heavier circulating fan-out.

Errors

Supply endpoints return 500 with { "error": "...", "details": "..." } only if the on-chain fan-out itself throws (rare; total-supply additionally has the 1B fallback). Market-cap / FDV never fail on a missing price — they return null for the USD figure instead.