API Reference

v1 · REST + SSE

Overview

Exchange-grade market data for every token on Hood Chain, served from our own indexer: every pool, every swap, first-party candles and volumes. Base URL: https://hoodmarketcap.com. All endpoints return JSON with a top-level data field (list endpoints add pagination).

Conventions

Addresses are lowercase 0x… strings; prices and values are USD floats.
Timestamps are Unix seconds; candle timestamps are bucket start times.
change_1h/change_24h are fractions (0.05 = +5%).
Market caps are circulating (verified tokens) or liquidity-credible FDV (on-chain priced).
Typical data freshness is seconds; responses carry short cache-control hints.
Every response carries as_of (Unix seconds when it was produced) and indexed_block (the newest block the swap index had reached). Compare the latter against the chain head to detect a stale index instead of guessing.
icon_url is null when we hold no artwork for a token. The site renders a generated badge in that case; the API does not pretend it is a picture.
Holder counts appear as both holders and holder_count on every object that has one; read whichever you prefer. A missing count is null, never 0.
Optional fields such as category, price_source and graduated_pool are present with an explicit null when unknown.

Status

GET/api/v1/status

Public, no key required. Whether the index is alive and how fresh it is: the newest swap and its age, swaps and trader-attribution share over the last ten minutes, the age of the last price snapshot, and holder-count coverage across the top 100 tokens by volume. ok is true when the newest swap is under ten minutes old.

Chain stats

GET/api/v1/stats

Chain-wide aggregates: token, pool, and stock counts, total credible market cap, 24h DEX volume, transactions today, active addresses, average gas, ETH price.

Tokens list

GET/api/v1/tokens

Param	Type	Description
`tab`	string	all (default), stocks, or crypto
`page`	int	1-based page number
`per_page`	int	1-250, default 100
`q`	string	search mode: matches name, symbol, or exact address (ignores paging)

Each row carries price, 1h/24h change, 24h volume, market cap, liquidity, holders, supply, stock flag, and a 7-day hourly close series (spark). Tokens created on a known launchpad also carry launchpad and graduation_status (bonding while not yet graduated, graduated once its curve completes); graduated tokens carry graduated_at when the graduation event was captured (and graduated_pool when known). Each field is omitted when absent.

Bonding tokens carry no market_cap, so they do not appear on this list or on /trending (both rank on market cap / swap volume). A bonding token is reachable today via token detail (GET /tokens/{address}), search (GET /tokens?q=), or the dedicated new launches feed.

Token detail

GET/api/v1/tokens/{address}

Everything the list returns plus the token's pools, CEX markets, and project info (description, links, claim status), including the same graduation fields when present.

Param	Type	Description
`window`	string	1h (default) or 24h
`limit`	int	1-50, default 25

Tokens ranked by swap-derived USD volume inside the window, the same ranking as the site's Trending page. Each row is a standard token row plus vol, the window volume. Tokens created on a known launchpad also carry launchpad and graduation_status (bonding while not yet graduated, graduated once its curve completes); graduated tokens carry graduated_at when the graduation event was captured (and graduated_pool when known). Each field is omitted when absent.

New listings

GET/api/v1/new

Param	Type	Description
`window`	string	1h, 24h (default), or 7d
`limit`	int	1-100, default 50
`min_liquidity`	float	minimum USD liquidity, default 500

Tokens whose first indexed swap falls inside the window, newest first. Standard token rows plus listed_at (Unix seconds of the first trade). Filtered to priced, non-scam tokens with real liquidity; raise or lower min_liquidity to taste.

Graduated tokens

GET/api/v1/graduated

Param	Type	Description
`window`	string	24h (default), 72h, or 7d
`limit`	int	1-200, default 100

Tokens whose bonding curve or LBP completed and migrated to a real DEX pool, most recently graduated first. Each row carries graduated_at (Unix seconds of the graduation), launchpad (a stable lowercase id, e.g. pons.family), and graduated_pool (the v4 pool id, best-effort and sometimes absent), plus the standard price, liquidity, market cap, and holder fields. No liquidity floor is applied.

New launches

GET/api/v1/launches

Param	Type	Description
`window`	string	24h (default), 72h, or 7d
`limit`	int	1-200, default 100
`status`	string	all (default), bonding, or graduated

Newest launchpad tokens by creation time (bonding and graduated). HMC catalogs launchpad tokens at creation, before they have a DEX pool, so this surfaces them earlier than /new (which is first-trade based). Each row carries the standard price, liquidity, market cap, and holder fields, plus created_at (Unix seconds of creation), graduation_status (bonding or graduated), and launchpad, plus graduated_at and graduated_pool once the token graduates (those two omitted while bonding).

Bonding tokens have no pool yet, so price, market_cap, and liquidity_usd are typically null until they trade or graduate. No dust filter is applied; apply your own floor. Coverage is bounded by the launchpads HMC detects at creation (pons.family and pools.trade today) and grows as more are added.

OHLCV candles

GET/api/v1/ohlcv/{address}

Param	Type	Description
`res`	string	1m, 5m, 1h (default), or 1d
`from`	int	start time, Unix seconds
`to`	int	end time, Unix seconds
`limit`	int	1-5000, default 1000

Built from every on-chain swap. Retention: 1m for 7 days, 5m for 90 days, 1h and 1d for the chain's full history.

Trades

GET/api/v1/trades/{address}

Param	Type	Description
`limit`	int	1-500, default 100

Most recent individual DEX trades (side, token amount, USD value, price, tx hash) from a rolling ~48 hour window.

Pools

GET/api/v1/pools/{address}

All AMM pools containing the token, with pool version and fee tier.

Live stream (SSE)

GET/api/stream

GET/api/stream?token={address}

GET/api/stream?since={id}

Server-Sent Events. Event types: swaps (each DEX trade as it lands), prices (rolling price/mcap/volume updates), newtokens (newly indexed tokens). Connect with any EventSource client; reconnection is automatic.

Param	Type	Description
`token`	string	Restrict swaps to a single token address.
`since`	number	Resume from a swap cursor instead of the current head. Replays every swap after that id, so a server consumer loses nothing across a reconnect.

Each swap carries i, its row id. To reconnect losslessly, store the highest i you have processed and pass it back as ?since=; the stream returns only swaps after it. Without ?since= the stream starts at the head, which is the right default for a live ticker in a browser tab. A consumer that must not drop swaps should persist each batch and advance its stored cursor in one atomic step, so a crash mid-batch cannot skip rows.

Embeddable widget

GET/embed/{address}

Param	Type	Description
`theme`	string	dark (default) or light

A self-contained live price card for any token: drop it on your site with an iframe. It links back to the token page and refreshes itself every minute.

<iframe src="https://hoodmarketcap.com/embed/0x…" width="340" height="110" frameborder="0"></iframe>

An embeddable swap panel (0% fee swaps, limit orders, DCA) is also available at /embed/swap/{address}. Live previews and snippets for both are on the widgets page.

Fair use & keys

The v1 API is open for light, non-commercial use while in preview; limits are enforced by IP and may change. Attribution ("data by Hoodmarketcap") is appreciated. Commercial use, higher limits, and API keys: [email protected]. See our Terms of Service.