# Elysium data API · Femtos

> Elysium data API: Kinetiq's Orbit L2 on HyperEVM: Ascend launches, PancakeSwap Infinity pools, holders, NFTs. 35 REST calls and WebSocket channels, each with its latency measured live.

- 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` (or `X-API-KEY: $FEMTOS_KEY`). Free key: https://femtos.xyz/accounts/ (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

- Elysium is served from its testnet until mainnet indexing starts; `GET /v1/status` gives the network.

## Launches

### New launches — GET `/v1/launches`

Latest Ascend launches, newest first, with live market figures.

| Param | In | Example or values |
|---|---|---|
| `limit` | query | `20` |
| `launchpad` | query | `ascend` |
| `creator` | query | (optional) |
| `q` | query | (optional) |
| `minMcapUsd` | query | `50000` |
| `minHolders` | query | `20` |

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/launches?limit=20&launchpad=ascend&minMcapUsd=50000&minHolders=20"
```

| Field | Type | Meaning |
|---|---|---|
| `token` | string | launched token |
| `symbol · name` | string \| null | ERC-20 metadata |
| `pair` | string | pool key, the market of candles and trades |
| `creator` | string | dev wallet |
| `launchedAt · block · tx` | int · string | launch event |
| `supply · supplySeeded` | decimal | total supply, tokens seeded in the pool |
| `devBuyTokens` | decimal \| null | tokens the creator bought at launch |
| `priceUsd · mcapUsd` | decimal \| null | last swap price, supply × price |
| `volume24hUsd · trades24h` | decimal · int | rolling 24 h |
| `holders` | int | positive balances, system addresses excluded |
| `top10Share · devHoldsShare` | number \| null | share of supply, 0–1 |
| `devSold` | boolean | creator sold at least once |
| `spam · spamReason` | boolean · string \| null | spam token: left out unless includeSpam=true |
| `volumeSinceLaunchUsd · tradesSinceLaunch` | decimal · int | the pool since the launch |
| `ascend.status` | ascended \| launched \| null | derived: every criterion with a threshold met; null without thresholds |
| `ascend.criteria` | object | mcapUsd · holders · volumeUsd · top10Share: {value, threshold, met, progress} |
| `minMcapUsd · minHolders · minVolumeUsd · maxTop10Share` | query | your thresholds (Ascend publishes none) |
| `creator · quote · q · since · until` | query | filters: dev wallet, quote token, symbol / name, launch time (ms) |
| `before` | query | next page: the X-Next-Cursor header (block:logIndex) |

### Launches stream — WS `elysium.launches`

One message per new launch, the moment its block is indexed.

| Param | In | Example or values |
|---|---|---|
| `launchpad` | filter | (optional) |

```json
{"op":"subscribe","channel":"elysium.launches","filter":{}}
```

| Field | Type | Meaning |
|---|---|---|
| `snapshot: true` | LaunchRow[] | last 50 launches at subscribe |
| `data` | LaunchRow | one new launch (same shape as GET /api/launches) |
| `ts.source` | int | block time of the launch (ms) |

### Ascend swaps stream — WS `ascend.swaps`

Every swap of every Ascend pool, one message per block.

| Param | In | Example or values |
|---|---|---|
| `token` | filter | (optional) |
| `side` | filter | `(empty)`, `buy`, `sell` |
| `min_usd` | filter | (optional) |

```json
{"op":"subscribe","channel":"ascend.swaps","filter":{}}
```

| Field | Type | Meaning |
|---|---|---|
| `snapshot: true` | AscendSwap[] | last 50 matching swaps |
| `data` | AscendSwap[] | the matching swaps of one block, all pools |
| `token · symbol · pair` | string | the launch the swap trades |
| `side · tokens · quoteAmount · usd` | string | of the launched token; USDC; USD |
| `priceUsd · mcapUsd` | decimal \| null | after the swap |
| `trader · id` | string | tx.from; <tx>:<log>, as /api/trades |
| `block · tx · logIndex` | int · string · int | source: the Swap log |
| `trader · launchpad` | filter | more filters |

### Ascended transitions — WS `ascend.status`

A message when a launch crosses your thresholds, in the block where it happens.

| Param | In | Example or values |
|---|---|---|
| `min_mcap_usd` | filter | `50000` |
| `min_holders` | filter | `20` |
| `token` | filter | (optional) |

```json
{"op":"subscribe","channel":"ascend.status","filter":{"min_mcap_usd":"50000","min_holders":"20"}}
```

| Field | Type | Meaning |
|---|---|---|
| `snapshot: true` | object[] | {token, symbol, pair, status, ascend} of the last 50 launches |
| `data.kind` | ascended \| lost \| criterion | status became ascended, left it, or one criterion flipped |
| `data.crossed[]` | object | {criterion, met} |
| `data.ascend` | object | progress after the block |
| `min_volume_usd · max_top10_share` | filter | more thresholds; none at all: refused |

## Market data

### Candles — GET `/v1/candles`

OHLCV of one pool in pair price, USD and market cap, ascending, UTC-aligned.

| Param | In | Example or values |
|---|---|---|
| `layer` | query | `elysium` |
| `market` | query | `<pair>` |
| `tf` | query | `1s`, `15s`, `1m`, `5m`, `15m`, `1h`, `4h`, `1d` |
| `limit` | query | `288` |

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/candles?layer=elysium&market=<pair>&tf=5m&limit=288"
```

| Field | Type | Meaning |
|---|---|---|
| `t` | int | unit start (ms) |
| `o · h · l · c` | decimal | price in the quote token |
| `usd {o,h,l,c}` | decimal | same candle in USD |
| `mcap {o,h,l,c}` | decimal | same candle as market cap, USD |
| `v · vq` | decimal | volume in token, in quote |
| `n` | int | swaps in the unit |
| `vUsd` | decimal \| null | volume in USD |
| `mcUsd` | decimal | market cap at close; absent on filled candles |
| `from · to · fill` | query | window (ms) and flat candles for empty units (fill=1, default) |
| `asOf · height` | int | head the answer is cut at: every trade up to that block counted |

### Forming candle — WS `elysium.candles`

The forming candle, pushed once per block where it changes.

| Param | In | Example or values |
|---|---|---|
| `pair` | filter | `<pair>` |
| `tf` | filter | `1s`, `15s`, `1m`, `5m`, `15m`, `1h`, `4h`, `1d` |

```json
{"op":"subscribe","channel":"elysium.candles","filter":{"pair":"<pair>","tf":"1m"}}
```

| Field | Type | Meaning |
|---|---|---|
| `snapshot: true` | Candle[] | last 300 candles at subscribe |
| `data` | Candle | the forming candle, same shape as REST |

### Trades — GET `/v1/trades`

Latest swaps of one pool, newest first.

| Param | In | Example or values |
|---|---|---|
| `layer` | query | `elysium` |
| `market` | query | `<pair>` |
| `limit` | query | `50` |

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/trades?layer=elysium&market=<pair>&limit=50"
```

| Field | Type | Meaning |
|---|---|---|
| `t · block` | int | block time (ms), block |
| `px · pxUsd` | decimal | price in quote, in USD |
| `sz · vq · usd` | decimal | size in token, quote, USD |
| `side` | B \| A | buy or sell of the token |
| `mcapUsd` | decimal \| null | market cap after the swap |
| `trader` | string | tx.from (the wallet, not the router) |
| `id` | string | <tx>:<log index>, dedupe REST + WS on it |
| `tx · logIndex` | string · int | source: the Swap log, with block |

### Trades stream — WS `elysium.trades`

The swaps of one pool, one message per block that has some.

| Param | In | Example or values |
|---|---|---|
| `pair` | filter | `<pair>` |

```json
{"op":"subscribe","channel":"elysium.trades","filter":{"pair":"<pair>"}}
```

| Field | Type | Meaning |
|---|---|---|
| `snapshot: true` | Trade[] | last 50 swaps at subscribe |
| `data` | Trade[] | the swaps of one block |
| `latency_ms.source_to_sent` | int | block → sent by the server |

### Daily token volume — GET `/v1/volume`

USD swap volume of a token per UTC day, both sides of every priced swap. Testnet pool prices.

| Param | In | Example or values |
|---|---|---|
| `layer` | query | `elysium` |
| `token` | query | `<token>` |
| `days` | query | `30` |

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

| Field | Type | Meaning |
|---|---|---|
| `days[]` | object | {day (UTC ms), volumeUsd, partial?}, oldest first, days with volume |
| `partial` | boolean | the indexed head day, still filling |
| `totalUsd` | decimal | sum over the days |
| `asOf · height` | int | indexed head: every swap up to that block counted |

### Token transfers — GET `/v1/transfers`

ERC-20 Transfer events of one token, newest first.

| Param | In | Example or values |
|---|---|---|
| `layer` | query | `elysium` |
| `token` | query | `<token>` |
| `limit` | query | `20` |

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

| Field | Type | Meaning |
|---|---|---|
| `rows[]` | object | {block, t, tx, logIndex, from, to, amount, amountRaw} |
| `amount` | decimal \| null | in token units; null when decimals are unknown |
| `next · before` | string · query | block:logIndex cursor of the next page |

### Liquidity events — GET `/v1/liquidity`

Liquidity added to and removed from one pool, newest first.

| Param | In | Example or values |
|---|---|---|
| `layer` | query | `elysium` |
| `pair` | query | `0x889a96eedb1df35a012d7e48baf7f9c780f1243b:0xfd93e1ba852feba3f05d7089513049c168a87fd058f64f4eb15f1c0bd3534467` |
| `limit` | query | `20` |

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/liquidity?layer=elysium&pair=0x889a96eedb1df35a012d7e48baf7f9c780f1243b%3A0xfd93e1ba852feba3f05d7089513049c168a87fd058f64f4eb15f1c0bd3534467&limit=20"
```

| Field | Type | Meaning |
|---|---|---|
| `rows[]` | object | {block, t, tx, kind: add \| remove, provider, amount0, amount1, usd} |
| `liquidityDelta · tickLower · tickUpper` | string · int | V4: the event carries a liquidity delta, no token amounts |
| `token0 · token1` | object | {address, symbol, decimals} |

## Holders & signals

### Holders — GET `/v1/holders`

Current balances of a token, largest first, with concentration.

| Param | In | Example or values |
|---|---|---|
| `layer` | query | `elysium` |
| `token` | query | `<token>` |
| `limit` | query | `20` |

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

| Field | Type | Meaning |
|---|---|---|
| `totalHolders` | int | positive balances, system excluded |
| `top10Share` | number \| null | 10 largest shares, 0–1 |
| `holders[]` | object | {address, amount, share, usd?, side?, label?} |
| `system[]` | object | bridge, pools, fee collector… (excludeSystem=0 to count them) |
| `asOf · height` | int | time and block of the balances |

### Launch detail & signals — GET `/v1/launches/{token}`

Metrics, dev wallet, early buyers and risk signals of one launch.

| Param | In | Example or values |
|---|---|---|
| `token` | path | `<token>` |
| `earlyWindowSec` | query | `60` |

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/launches/<token>?earlyWindowSec=60"
```

| Field | Type | Meaning |
|---|---|---|
| `launch` | LaunchRow | same row as GET /api/launches |
| `metrics` | object | price, mcap, ATH mcap, holders, volume, traders, buyers, sellers |
| `dev` | object | creator balance, buys, sells, transfers out |
| `holders.top[]` | object | 20 largest, tagged dev \| early |
| `earlyBuyers` | object | wallets that bought in the first window |
| `signals[]` | object | {rule, severity, addresses, detail}, high first |
| `fees` | object | estimate: 1 % of volume |
| `ascend` | object | progress toward Ascended + coordination evidence (flagged wallets, their share) |

### Launch holders — GET `/v1/launches/{token}/holders`

Every holder of a launched token, tagged dev or early buyer, with concentration.

| Param | In | Example or values |
|---|---|---|
| `token` | path | `<token>` |
| `limit` | query | `20` |
| `offset` | query | (optional) |

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/launches/<token>/holders?limit=20"
```

| Field | Type | Meaning |
|---|---|---|
| `totalHolders` | int | positive balances, system excluded |
| `concentration` | object | top 1 / 10 / 20 / 50 shares, HHI, dev, flagged early buyers, held share |
| `system` | object | PancakeSwap Infinity vault and PoolManager, Ascend treasuries: count, share |
| `holders[]` | object | {rank, address, amount, shareOfSupply, firstSeenAt, lastActiveAt, tag?, flags?} |
| `next` | int \| null | offset of the next page |

## NFTs

### Active NFT collections — GET `/v1/nfts/collections`

Collections with the most transfers over the last 1 h or 24 h.

| Param | In | Example or values |
|---|---|---|
| `layer` | query | `elysium` |
| `window` | query | `24h`, `1h` |
| `limit` | query | `20` |

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/nfts/collections?layer=elysium&window=24h&limit=20"
```

| Field | Type | Meaning |
|---|---|---|
| `collections[]` | object | {address, standard, name, symbol, transfers, mints, burns, lastBlock} |
| `from · to` | int | window (ms), ends at the indexed head |
| `fromBlock · toBlock` | int | blocks read |

### NFT collection — GET `/v1/nfts/collections/{address}`

Metadata, tokens seen and 24 h activity of one collection.

| Param | In | Example or values |
|---|---|---|
| `address` | path | `<collection>` |
| `layer` | query | `elysium` |

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/nfts/collections/<collection>?layer=elysium"
```

| Field | Type | Meaning |
|---|---|---|
| `collection` | object | {address, standard, name, symbol, firstSeenBlock, firstSeenAt} |
| `tokens` | object | {count, capped}: counted up to 1,000 |
| `activity24h` | object | {transfers, mints, burns, lastBlock, fromBlock, toBlock} |

### Collection tokens — GET `/v1/nfts/tokens`

Tokens of a collection by id, with their owner and metadata URI.

| Param | In | Example or values |
|---|---|---|
| `layer` | query | `elysium` |
| `collection` | query | `<collection>` |
| `limit` | query | `20` |

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

| Field | Type | Meaning |
|---|---|---|
| `tokens[]` | object | {tokenId, standard, owner, uri, firstSeenBlock, lastTransferBlock} |
| `owner` | string \| null | ERC-721 owner, 0x0 once burnt; null for ERC-1155 |
| `uri · uriLength` | string \| null · int | URI as returned; over 2,048 characters: null + its length |
| `next · after` | string · query | last token id, pass as after for the next page |

### NFTs of a wallet — GET `/v1/nfts/owned`

ERC-721 tokens owned and ERC-1155 balances of one address.

| Param | In | Example or values |
|---|---|---|
| `layer` | query | `elysium` |
| `owner` | query | `<owner>` |
| `limit` | query | `20` |

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/nfts/owned?layer=elysium&owner=<owner>&limit=20"
```

| Field | Type | Meaning |
|---|---|---|
| `erc721 · erc1155` | int | tokens owned, token ids held (counted up to 10,000) |
| `collections[]` | object | {address, name, symbol, erc721, erc1155} |
| `tokens[]` | object | {collection, tokenId, standard, amount, uri} |
| `asOf · height` | int | indexed head the holdings include |

### NFT transfers — GET `/v1/nfts/transfers`

Transfers of a collection or one token, newest first.

| Param | In | Example or values |
|---|---|---|
| `layer` | query | `elysium` |
| `collection` | query | `<collection>` |
| `tokenId` | query | (optional) |
| `limit` | query | `20` |

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/nfts/transfers?layer=elysium&collection=<collection>&limit=20"
```

| Field | Type | Meaning |
|---|---|---|
| `rows[]` | object | {block, t, tx, kind, tokenId, amount, from, to, operator} |
| `kind` | mint \| burn \| transfer | from 0x0, to 0x0, else transfer |
| `scope` | all \| 24h \| 7d | whole history, or the block window read |
| `next · before` | string · query | block:log:batch cursor of the next page |

## Lifecycle

### Lifecycle stage changes — WS `ascend.lifecycle`

A message when a launched token reaches its next stage: listing desk, HyperEVM mirror, HyperCore spot, perp.

| Param | In | Example or values |
|---|---|---|
| `token` | filter | (optional) |

```json
{"op":"subscribe","channel":"ascend.lifecycle","filter":{}}
```

| Field | Type | Meaning |
|---|---|---|
| `snapshot: true` | object[] | {kind: snapshot, stages: {token: [stages]}}, or the lifecycle of `token` |
| `data.kind` | stage | a launched token reached or lost a stage |
| `data.reached · data.lost` | string[] | stages since the previous poll |
| `data.stage · data.previous` | string | current and previous last stage |
| `data.lifecycle` | object | as GET /api/tokens/{token}/lifecycle |

### Launch timeline — GET `/v1/launches/{token}/timeline`

The whole life of a launch as ordered events with running state.

| Param | In | Example or values |
|---|---|---|
| `token` | path | `<token>` |

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/launches/<token>/timeline"
```

| Field | Type | Meaning |
|---|---|---|
| `launch` | object | {t, block, tx, creator, supplySeeded, devBuyTokens} |
| `events[]` | object | launch \| swap \| transfer, chain order |
| `events[].holders · top10Share` | int · number | running state after the event |
| `events[].mcapUsd · volumeUsd` | decimal | running market cap, cumulated volume |
| `current` | object | figures right now |
| `graduation` | object | {mirror: HyperEVM token \| null, core: HyperCore spot \| null} |
| `truncated` | boolean | over 5,000 swaps: replay stops there |

### Token across layers — GET `/v1/tokens/{token}/lifecycle`

One token from its Elysium launch to its HyperEVM mirror, HyperCore spot and perps, each link proven or marked inferred.

| Param | In | Example or values |
|---|---|---|
| `token` | path | `<token>` |

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/tokens/<token>/lifecycle"
```

| Field | Type | Meaning |
|---|---|---|
| `stage` | string \| null | last stage reached: launched · registered · enrolled · committed · bridged · listed · perp |
| `stages[]` | object | {stage, reached, exact, basis, at {layer, block, time, tx}, observedAt, source, detail} |
| `addresses` | object | elysium · hyperevm · hypercore {index, spot} · perps[] |
| `links[]` | object | {from, to, relation, exact, basis: event \| registry \| attestation \| metadata \| name} |
| `conflicts · unavailable` | string[] | sources that disagree · that could not answer |
| `fees` | object \| null | exact fees of the pool from its events (Ascend) |
| `token` | path | also a HyperEVM address, core:<index>, a HyperCore name or perp coin |

## Bridge & wallet

### Bridge movements — GET `/v1/bridges`

HyperEVM ↔ Elysium movements with 24 h stats.

| Param | In | Example or values |
|---|---|---|
| `route` | query | `evm_elysium` |
| `limit` | query | `50` |

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/bridges?route=evm_elysium&limit=50"
```

| Field | Type | Meaning |
|---|---|---|
| `rows[]` | object | one movement: status, direction, value, token, both chains’ blocks and txs |
| `rows[].bridge_latency_ms` | int \| null | sent → credited |
| `stats` | object | 24 h: count, completed, pending, latency p50 / p99 |
| `direction · token · account · system` | query | filters (system: exclude \| include \| only) |
| `tokens` | object | {address: {symbol, decimals}} |
| `labels` | object | {address: name}: Kinetiq's system senders and contracts |

### Bridge stream — WS `elysium.bridge`

Each state change of a HyperEVM ↔ Elysium movement, live.

| Param | In | Example or values |
|---|---|---|
| `token` | filter | (optional) |
| `direction` | filter | `(empty)`, `to_child`, `to_parent` |

```json
{"op":"subscribe","channel":"elysium.bridge","filter":{}}
```

| Field | Type | Meaning |
|---|---|---|
| `snapshot: true` | object[] | last 50 movements |
| `data` | object | one movement in its new state (REST row shape) |

### Cross-layer wallet — GET `/v1/wallet/{address}`

One address (or a named wallet's handle) on HyperCore, HyperEVM and Elysium, plus its latest events.

| Param | In | Example or values |
|---|---|---|
| `address` | path | `<creator>` |

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/wallet/<creator>"
```

| Field | Type | Meaning |
|---|---|---|
| `hypercore` | object | perp account, positions, spot balances (mainnet) |
| `hyperevm` | object | balances, NFTs, swaps / transfers scope, HyperCore ↔ HyperEVM bridges |
| `elysium` | object | token balances and NFTs (testnet), Orbit bridges |
| `bridges` | object | legs in flight and journeys Core → HyperEVM → Elysium (and back) |
| `*.freshness` | object | each section: head, headTime, lagMs, behindMs (as /api/status) |
| `recent[]` | object | {layer, kind: fill \| ledger \| bridge \| swap \| transfer, t, data} |
| `labels` | object | known addresses → label |

### Wallet stream — WS `wallet`

Every event of the three layers touching one address.

| Param | In | Example or values |
|---|---|---|
| `address` | filter | `<creator>` |

```json
{"op":"subscribe","channel":"wallet","filter":{"address":"<creator>"}}
```

| Field | Type | Meaning |
|---|---|---|
| `snapshot: true` | object[] | last 50 events |
| `data` | {channel, data} | one event: hc.trades, hc.ledger, elysium.trades, elysium.bridge… |

### Token registry — GET `/v1/coins`

Links one token across Elysium, HyperEVM and HyperCore.

| Param | In | Example or values |
|---|---|---|
| `layer` | query | `elysium` |
| `q` | query | `<token>` |

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

| Field | Type | Meaning |
|---|---|---|
| `id · symbol · decimals` | string · int | token on this layer |
| `priceUsd` | decimal \| null | last price |
| `links.evm · links.core` | object | the same asset on the other layers |
| `coverage` | object | whether we index it |

### Coin detail — GET `/v1/coins/{layer}/{id}`

One token: its links across layers, the markets it trades on, its 5 largest holders.

| Param | In | Example or values |
|---|---|---|
| `layer` | path | `elysium` |
| `id` | path | `<token>` |
| `includeSpam` | query | `(empty)`, `true` |

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/coins/elysium/<token>"
```

| Field | Type | Meaning |
|---|---|---|
| `coin` | object | {id, symbol, name, decimals, totalSupply, priceUsd, links, spam, spamReason} |
| `markets[]` | Market | markets where it is base or quote, most traded first |
| `holders` | object | 5 largest holders, or {unavailable} |

## Named wallets

### KOL leaderboard — GET `/v1/kols/leaderboard`

KOLs, traders and funds ranked by their Elysium swaps, transfers, bridge legs and holdings.

| Param | In | Example or values |
|---|---|---|
| `layer` | query | `elysium` |
| `window` | query | `24h`, `7d`, `30d` |
| `sort` | query | `volume`, `swaps`, `transfers`, `netBuy`, `holdings`, `bridges`, `lastActivity` |
| `limit` | query | `50` |
| `includeSpam` | query | `(empty)`, `true` |

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/kols/leaderboard?layer=elysium&window=24h&sort=volume&limit=50"
```

| Field | Type | Meaning |
|---|---|---|
| `rows[].entity` | {id, name, x, kinds} | who public lists name the wallets |
| `swaps · volumeUsd · netBuyUsd` | int · decimal | DEX swaps sent by its wallets, USD volume, buys − sells |
| `transfersIn · transfersOut · bridges` | int | ERC-20 transfers, bridge legs |
| `holdingsUsd` | decimal \| null | HyperEVM: USD held at the indexed head |
| `scope` | object | blocks read per kind: 24 h without the address indexes (7d / 30d: 503) |

### KOL moves — GET `/v1/kols/activity`

The latest Elysium swaps and transfers of the named wallets, with who moved.

| Param | In | Example or values |
|---|---|---|
| `layer` | query | `elysium` |
| `entity` | query | (optional) |
| `minNotional` | query | (optional) |
| `limit` | query | `50` |
| `includeSpam` | query | `(empty)`, `true` |

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/kols/activity?layer=elysium&limit=50"
```

| Field | Type | Meaning |
|---|---|---|
| `rows[]` | KolItem | {kind: swap \| transfer, t, wallet, entity, pair, base, side, notional, token, amount} |
| `hash · block · logIndex` | string · int · int | source: the swap / Transfer log |
| `bridges[]` | KolItem | first page: their latest bridge legs (kind bridge) |
| `scope` | object | blocks read per kind |
| `spam · spamReason` | boolean · string | spam tokens hidden unless includeSpam=true |
| `next · before` | string | cursor <block>:<logIndex> of the next page |

### KOL stream — WS `kol.activity`

Every Elysium swap, transfer and bridge leg of a named wallet, on each indexed block.

| Param | In | Example or values |
|---|---|---|
| `layer` | filter | `elysium` |
| `kind` | filter | `(empty)`, `swap`, `transfer`, `bridge` |

```json
{"op":"subscribe","channel":"kol.activity","filter":{"layer":"elysium"}}
```

| Field | Type | Meaning |
|---|---|---|
| `snapshot: true` | KolItem[] | last 50 moves seen |
| `data` | KolItem | {layer, kind: swap \| transfer \| bridge, wallet, entity, side, notional} |

## Reference

### Blocks stream — WS `elysium.blocks`

Each new Elysium block header, from our node.

```json
{"op":"subscribe","channel":"elysium.blocks","filter":{}}
```

| Field | Type | Meaning |
|---|---|---|
| `data` | object | {number, hash, parent_hash, timestamp, tx_count, gas_used, base_fee, l1_block_number} |
| `timestamp` | int | block time (s) |

### Freshness — GET `/v1/status`

Head and lag of each layer, measured now.

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/status"
```

| Field | Type | Meaning |
|---|---|---|
| `layers.hypercore` | object | {state, head, headTime, lagMs} |
| `layers.hyperevm` | object | {state: syncing \| live, head?, headTime?, lagMs?, chainHead?, blocksBehind?, behindMs?, clock?, reason?} |
| `layers.elysium` | object | {state, network, head, headTime, lagMs, chainHead?, blocksBehind?, behindMs?, clock?} |
| `chainHead · blocksBehind · behindMs` | int · int · ms | EVM layers: the node’s own head (pushed), how far our indexed head is behind it; behindMs = how long the next block has waited, on our receive clock (0 = in sync) |
| `stream · flows` | object | our two live feeds: {connected, lagMs} |
| `bridges` | object | HyperCore ↔ HyperEVM matching: {evm_to_core, core_to_evm: {legs, matched, coverage, p50Ms, p99Ms}} |
| `serverTime` | int | server clock (ms) |

### Check your key — GET `/v1/whoami`

Answers the name your key is registered under, its tier, billing state and the limits in force.

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/whoami"
```

| Field | Type | Meaning |
|---|---|---|
| `key` | string | name of your key |
| `tier` | string \| null | free · builder · pro · scale · enterprise · partner (null: internal key) |
| `billing` | string | ok · exhausted · capped (the last two run at the free row's limits) |
| `limits` | object \| null | {rps, burst, maxConns} in force: REST rate and burst, open WebSockets (null: no limit) |

### OpenAPI document — GET `/v1/openapi.json`

The OpenAPI 3.1 contract of every REST call, public.

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/openapi.json"
```

| Field | Type | Meaning |
|---|---|---|
| `paths` | object | every operation |
| `components.schemas` | object | response shapes |
| `x-websocket.channels` | object[] | WebSocket channels |

## Pages

- [Launch story](https://femtos.xyz/elysium/lifecycle.md): One Ascend launch on Elysium told event by event from the Femtos API: launch, dev wallet, early buyers, swaps, holders, market cap over time.