# Femtos | Elysium token price and OHLCV API

> Token price API for Elysium, Kinetiq's Hyperliquid L2 (chain 99901): USD prices of up to 100 tokens a call, price history, OHLCV candles in USD and market cap, token overview and screener, pushed per block over WebSocket, and MCP tools.

- Base URL: `https://api.femtos.xyz/v1` (REST) · `wss://api.femtos.xyz/v1/ws` (WebSocket) · MCP: `https://api.femtos.xyz/mcp`
- Auth: `Authorization: Bearer $FEMTOS_KEY`. Free key: https://dashboard.femtos.xyz/signup (browser), or with
  no browser: `GET https://femtos.xyz/accounts/agent/challenge`, solve its proof of work, then `POST https://femtos.xyz/accounts/agent/signup`
  (https://femtos.xyz/agents.md#agent-onboarding)
- Decimals are exact strings, times Unix milliseconds, addresses lowercase `0x`
- Whole API in one file: https://femtos.xyz/agents.md · OpenAPI: https://api.femtos.xyz/v1/openapi.json · Index: https://femtos.xyz/llms.txt
- Page with live calls: https://femtos.xyz/elysium/price-api

Elysium is Kinetiq's Hyperliquid L2 (Arbitrum Orbit on HyperEVM, chain 99901). Femtos prices Elysium tokens in USD from their pool swaps: the price now, at a past time or per interval over a window, OHLCV candles of a token through its reference pool (its most liquid one) in USD and market cap, and prices pushed over WebSocket in each block that changes one.

Base URL `https://api.femtos.xyz/v1`, key in `Authorization: Bearer`; WebSocket `wss://api.femtos.xyz/v1/ws`; MCP `https://api.femtos.xyz/mcp`. Decimals are exact strings, times Unix ms.

## Token prices

- [Token prices](https://femtos.xyz/reference/prices.md) `GET /v1/prices`: USD price of up to 100 tokens in one call, each with its source and provenance.
- [Price history](https://femtos.xyz/reference/price-history.md) `GET /v1/prices/history`: USD closes per unit of up to 25 tokens over a window, or the price of 100 tokens at one time (at=).
- [Token overview](https://femtos.xyz/reference/token-overview.md) `GET /v1/tokens/{address}`: One token across all its pools: price, FDV, market cap, liquidity, windows, holders, top pools.
- [Token prices stream](https://femtos.xyz/reference/ws/token-prices.md) `WS elysium.prices`: USD prices of up to 100 Elysium tokens, as GET /v1/prices answers them, pushed in each block that changes one.

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/prices?layer=elysium&tokens=<token>"
```

| Field | Type | Meaning |
|---|---|---|
| `prices[]` | object | {token, symbol, priceUsd, source, t, block, tx, logIndex, pool, market, reason, spam, …} |
| `asOf` | int \| null | Time of `height`: the layer head the answer is cut at (EVM: indexed head; HyperCore: ingested head) (Unix ms) |
| `height` | int \| null | Head block of the layer the answer is cut at |

## OHLCV candles

- [Token candles](https://femtos.xyz/reference/token-candles.md) `GET /v1/candles`: OHLCV of a token in USD through its reference pool, the most liquid one.
- [Candles](https://femtos.xyz/reference/candles.md) `GET /v1/candles`: OHLCV of one pool in pair price, USD and market cap, ascending, UTC-aligned.
- [Token candles stream](https://femtos.xyz/reference/ws/token-candles.md) `WS elysium.token.candles`: A token's candles in USD (GET /v1/candles?token=: its reference pool, volume, buys and sells), pushed on subscribe, then each block where its reference pool trades.
- [Forming candle](https://femtos.xyz/reference/ws/candles.md) `WS elysium.candles`: The forming candle, pushed once per block where it changes.

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/candles?layer=elysium&token=<token>&tf=1h&limit=48"
```

| Field | Type | Meaning |
|---|---|---|
| `reference` | object | token form, EVM: the reference pool (PoolRef) and its rule |
| `unit` | usd \| usdc | token form: what o/h/l/c are in |
| `candles[]` | object | Ascending: {t, o, h, l, c, v, vq, n, vUsd, mcUsd, usd, mcap, …} |
| `candles[].o` | decimal | Open, in the quote (HyperCore: the market's quote token, USDC but on the USDH, USDT0 and USDE spot markets, `usd` with includeUsd; EVM pools: the quote token; token form: USD) |
| `candles[].buys` | int | token form (EVM): swaps buying the token |
| `candles[].mcap` | object | Same candle as market cap in USD {o,h,l,c}, over the circulating supply: burn addresses and bridges out (Elysium, HyperEVM). HyperCore spot markets, with includeUsd: the USD candle × the base token's circulating supply as Hyperliquid publishes it, read and stored each hour (`supply.from`: the first reading): a unit uses the last reading at or before its end; a unit older than the first reading uses that first one, or the supply read now when none is stored yet (the nearest known, `supply.basis` current), never an invented history. No market cap (no `mcap`, no `supply`) on a token whose whole genesis went to its bridge: a token created in full for a bridge that hands it out as deposits arrive (Unit's UBTC, UETH, USOL…) or created on its HyperEVM side (USDT0): what Hyperliquid publishes as its circulating supply is the bridge's reserve, not what circulates. Spot markets only: a perp or an outcome market has none: {o, h, l, c} |

Timeframes (`tf`): `1s`, `15s`, `1m`, `5m`, `15m`, `1h`, `4h`, `1d`.

## Screener and volume

- [Token screener](https://femtos.xyz/reference/tokens-top.md) `GET /v1/tokens/top`: The tokens of Elysium, one row each over all their pools: trending, volume, gainers, losers, new, market cap, liquidity.
- [Token screener stream](https://femtos.xyz/reference/ws/tokens-top.md) `WS elysium.tokens.top`: The GET /v1/tokens/top answer of Elysium (one row per token with activity (a swap in 24 h, or a pool created in the last hour), over all its pools: price, 1 h / 24 h change, volume, liquidity, market cap, holders, trending score), or the rows of a watchlist (`addresses`), pushed on subscribe, then on each indexed block with a swap: the rows of the pools each indexed block traded made again at once (5 m / 1 h windows and traders, price, market cap, FDV, last trade, trend score), in the order of the last rebuild; the order and the other fields at each rebuild (at most every 60 s).
- [Pool screener](https://femtos.xyz/reference/pools-top.md) `GET /v1/pools/top`: The pools of Elysium, one row each: trending, volume, gainers, losers, new, market cap, liquidity.
- [Daily token volume](https://femtos.xyz/reference/volume.md) `GET /v1/volume`: USD swap volume of a token per UTC day, both sides of every priced swap.
- [Trades](https://femtos.xyz/reference/trades.md) `GET /v1/trades`: Latest swaps of one pool, newest first.
- [Trades stream](https://femtos.xyz/reference/ws/trades.md) `WS elysium.trades`: The swaps of one pool, or of up to 100 pools (`pairs`), one message per pool and block that has some.

## MCP

Agents call the same data as tools of the hosted MCP server:

| Tool | What it answers | REST call |
|---|---|---|
| `get_prices` | USD price of up to 100 tokens, each with its source (HL mid, HyperCore spot, pool swap) | `GET /v1/prices` |
| `get_price_history` | USD prices at a time (100 tokens) or per unit over a window (25 tokens) | `GET /v1/prices/history` |
| `get_candles` | OHLCV of a coin, a pool, or a token through its reference pool; pools in USD and market cap too | `GET /v1/candles` |
| `get_token_overview` | A token across all its pools: price, FDV, mcap, liquidity, 5m to 24h windows, holders, top pools | `GET /v1/tokens/{address}` |
| `list_top_tokens` | Token screener: one row per token, trending / volume / gainers / losers / new / mcap / liquidity | `GET /v1/tokens/top` |

## More

- [Elysium launchpad API](https://femtos.xyz/elysium/launchpads.md): Launches of every launchpad, curve progress, graduation.
- [Elysium data API](https://femtos.xyz/elysium.md): Everything served on Elysium, by group.
- [MCP server](https://femtos.xyz/mcp.md): Connect Claude, Cursor or any MCP client.

Every call: https://femtos.xyz/reference.md · the whole API in one file: https://femtos.xyz/agents.md