# HyperEVM data API · Femtos

> HyperEVM data API: the Hyperliquid EVM chain: DEX pools, swaps, tokens, holders, NFTs, LiquidLaunch launches. 31 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/hyperevm

## Launches

### LiquidLaunch launches — GET `/v1/launches`

Latest LiquidLaunch bonding-curve launches, newest first.

| Param | In | Example or values |
|---|---|---|
| `launchpad` | query | `liquidlaunch` |
| `limit` | query | `20` |
| `includeSpam` | query | `(empty)`, `true` |

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/launches?launchpad=liquidlaunch&limit=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 |
| `bondedAt` | int \| null | curve completed, liquidity moved to the DEX |
| `bondingProgress` | number | share of the curve sold, 0–1 |

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

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

| Param | In | Example or values |
|---|---|---|
| `include_spam` | filter | `(empty)`, `true` |

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

| Field | Type | Meaning |
|---|---|---|
| `snapshot: true` | LaunchRow[] | last 50 launches at subscribe |
| `data` | LaunchRow | one new launch (same shape as GET /api/launches) |
| `include_spam` | filter | true: launches of spam tokens too, flagged spam |

### 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 | `<llToken>` |
| `earlyWindowSec` | query | `60` |

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

| Field | Type | Meaning |
|---|---|---|
| `launch` | LaunchRow | with bondedAt, bondingProgress |
| `metrics · dev · holders` | object | as on Elysium |
| `signals[]` | object | {rule, severity, addresses, detail}, high first |

### 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 | `<llToken>` |

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

| Field | Type | Meaning |
|---|---|---|
| `launch · events[] · current` | object | as on Elysium |
| `bondedAt` | int \| null | curve completed |
| `truncated` | boolean | over 5,000 swaps: replay stops there |

## Market data

### Markets — GET `/v1/markets`

Active HyperEVM pools with 24 h stats.

| Param | In | Example or values |
|---|---|---|
| `layer` | query | `hyperevm` |
| `includeSpam` | query | `(empty)`, `true` |

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/markets?layer=hyperevm"
```

| Field | Type | Meaning |
|---|---|---|
| `id · symbol · base · quote` | string | pool key and tokens |
| `kind · protocol · feeTier` | string | pool, DEX protocol |
| `price · change24h` | decimal · number | last swap, 24 h change in % |
| `volume24hUsd · trades24h · mcapUsd` | decimal · int | rolling 24 h, market cap |
| `spam · spamReason` | boolean · string \| null | base or quote is a spam token; hidden unless includeSpam=true |

### 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 | `hyperevm` |
| `market` | query | `<evmPair>` |
| `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=hyperevm&market=<evmPair>&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 `hyperevm.candles`

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

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

```json
{"op":"subscribe","channel":"hyperevm.candles","filter":{"pair":"<evmPair>","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 | `hyperevm` |
| `market` | query | `<evmPair>` |
| `limit` | query | `50` |

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/trades?layer=hyperevm&market=<evmPair>&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 `hyperevm.trades`

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

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

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

| Field | Type | Meaning |
|---|---|---|
| `snapshot: true` | Trade[] | last 50 swaps at subscribe |
| `data` | Trade[] | the swaps of one block |

## Holders & tokens

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

Current balances of an ERC-20, largest first, with concentration.

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

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/holders?layer=hyperevm&token=<evmToken>&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 |
| `spam · spamReason` | boolean · string \| null | the token is flagged spam; its holders still answer |

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

HyperEVM tokens with their HyperCore spot link and price.

| Param | In | Example or values |
|---|---|---|
| `layer` | query | `hyperevm` |
| `q` | query | (optional) |
| `limit` | query | `50` |
| `includeSpam` | query | `(empty)`, `true` |

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

| Field | Type | Meaning |
|---|---|---|
| `id · symbol · decimals` | string · int | contract address, ERC-20 metadata |
| `priceUsd · totalSupply` | decimal \| null | last price, supply |
| `links.core` | object | the HyperCore spot token |
| `spam · spamReason` | boolean · string \| null | flagged by the indexer; hidden unless includeSpam=true |

### 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 | `hyperevm` |
| `id` | path | `<evmToken>` |
| `includeSpam` | query | `(empty)`, `true` |

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

| 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} |

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

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

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

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/volume?layer=hyperevm&token=<evmToken>&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 families — GET `/v1/token-families`

Tokens whose balance moves without Transfer logs: Aave aTokens and debt tokens, stHYPE, xStocks.

| Param | In | Example or values |
|---|---|---|
| `layer` | query | `hyperevm` |
| `family` | query | `(empty)`, `aave_atoken`, `aave_vtoken`, `sthype`, `wrapped_shares`, `backed`, `scaling_factor` |
| `includeSpam` | query | `(empty)`, `true` |

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/token-families?layer=hyperevm"
```

| Field | Type | Meaning |
|---|---|---|
| `families` | object | tokens per family |
| `tokens[]` | object | {token, family, description, symbol, decimals, params, spam, spamReason} |
| `description` | string | how balanceOf follows from the base the contract keeps |

### Family token holders — GET `/v1/token-families/{token}`

Holders of one family token with balanceOf at the indexed head.

| Param | In | Example or values |
|---|---|---|
| `token` | path | `0xffaa4a3d97fe9107cef8a3f48c069f577ff76cc1` |
| `layer` | query | `hyperevm` |
| `limit` | query | `20` |

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/token-families/0xffaa4a3d97fe9107cef8a3f48c069f577ff76cc1?layer=hyperevm&limit=20"
```

| Field | Type | Meaning |
|---|---|---|
| `holders` | int | holders with a positive base |
| `top[]` | object | {address, base, balance, lastBlock} |
| `base · balance` | decimal | what the contract keeps (raw), balanceOf in token units |
| `state · stateBlock` | object · int | token state the formula reads |

### Spam tokens — GET `/v1/tokens/spam`

Tokens the indexer flags as spam, left out of every list, and the latest flag changes.

| Param | In | Example or values |
|---|---|---|
| `layer` | query | `hyperevm` |
| `limit` | query | `50` |

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

| Field | Type | Meaning |
|---|---|---|
| `tokens[]` | object | {address, symbol, name, spamReason, spamSince}, newest flag first |
| `spamReason` | string | strongest first: homoglyph:<T>, impostor:<T>, phishing_name, fake_transfers, unreadable_balance, verifier_ignore |
| `changes[]` | object | {token, spam, spamReason, previousReason, changedAt}: flags set, changed or cleared |
| `available` | boolean | false: no spam flags on this layer yet, nothing hidden |

## 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 | `hyperevm` |
| `window` | query | `24h`, `1h` |
| `limit` | query | `20` |

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/nfts/collections?layer=hyperevm&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 | `hyperevm` |

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

| 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 | `hyperevm` |
| `collection` | query | `<collection>` |
| `limit` | query | `20` |

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/nfts/tokens?layer=hyperevm&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 | `hyperevm` |
| `owner` | query | `<owner>` |
| `limit` | query | `20` |

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/nfts/owned?layer=hyperevm&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. While HyperEVM syncs: the last 24 h or 7 d of indexed blocks.

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

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/nfts/transfers?layer=hyperevm&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 |

## Bridge & wallet

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

HyperCore ↔ HyperEVM transfers (core_evm) or HyperEVM ↔ Elysium movements (evm_elysium), with 24 h stats.

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

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

| Field | Type | Meaning |
|---|---|---|
| `rows[]` | object | core_evm: status, direction, token, amount, core{…}, evm{…}; evm_elysium: Orbit movement |
| `rows[].bridge_latency_ms` | int \| null | first leg → credited on the other layer |
| `stats` | object | 24 h: count, completed, pending, stuck, latency p50 / p99 per direction |
| `coverageFrom` | object \| null | core_evm: first time each direction is scanned on HyperEVM |
| `tokens · includeSpam · spamHidden` | object · query · int | evm_elysium: parent tokens with spam / spamReason; rows of spam tokens hidden unless includeSpam=true |
| `rows[].matched_by` | nonce \| order \| null | how both legs were paired: nonce = exact (coreReceiveWithData), order = same system address, account and amount, in order; null while unmatched |
| `rows[].final_latency_ms` | int \| null | evm_to_core: HyperEVM leg → the beneficiary credited on HyperCore |
| `rows[].forwarding` | {amount, dex} \| null | a deposit wallet (Circle CoreDepositWallet) forwarded the deposit with CoreWriter sendAsset; dex 0 = main perp dex |
| `rows[].beneficiary` | string \| null | who is finally credited: the account, or a forwarded deposit's recipient; null for a CCTP withdrawal or until resolved |
| `rows[].depositor` | string \| null | who paid on the first layer: the account, or who funded the deposit wallet |
| `rows[].origin · rows[].final` | object \| null | origin: CCTP mint {domain, sender}; final: the HyperCore leg that credits the beneficiary |
| `labels` | object | {address: name} of known addresses in the rows (Circle CctpForwarder: the depositor of every CCTP mint) |
| `cctpDomains` | object | CCTP source domain → chain (0 Ethereum, 1 Avalanche, 2 OP Mainnet, 3 Arbitrum, 5 Solana, 6 Base, 7 Polygon PoS), for origin.domain |

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

Every HyperCore ↔ HyperEVM leg since our data starts, paired with its other leg: matched share per direction and token, why the others are not, latency.

| Param | In | Example or values |
|---|---|---|
| `window` | query | `all`, `30d`, `7d`, `24h` |

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/bridges/coverage?window=all"
```

| Field | Type | Meaning |
|---|---|---|
| `directions.evm_to_core · core_to_evm` | object | {legs, matched, coverage, unmatched: {reason: n}, notALeg, latencyMs: {p50, p90, p99, p999, max}, tokens[]} |
| `coverage` | number | matched / (legs − not legs − in flight): 1 = every settled leg has its other leg |
| `unmatched` | object | in_flight · missing_peer · amount_mismatch · late_peer · unknown_token |
| `core_to_evm.matchedBy` | object | {nonce: exact (coreReceiveWithData), order: same key in order} |
| `unpairedCredits` | object \| null | credits on the receiving side no leg took |
| `source · settledUntil` | string · ms | materialized tables (and how far they are settled) or the views |

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

Each HyperCore ↔ HyperEVM transfer, initiated then completed.

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

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

| Field | Type | Meaning |
|---|---|---|
| `snapshot: true` | object[] | last 50 transfers |
| `data` | object | one transfer in its new state (core_evm 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 | `<owner>` |
| `includeSpam` | query | `(empty)`, `true` |

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

| Field | Type | Meaning |
|---|---|---|
| `hyperevm.balances[]` | object | {token, symbol, amount, priceUsd, usd, spam, spamReason, family?} at the indexed head |
| `includeSpam · spamHidden` | query · int | spam tokens out of lists and USD totals unless includeSpam=true |
| `hyperevm.height · asOf` | int | indexed head block and time |
| `hyperevm.nfts` | object | {erc721, erc1155, collections[], tokens[]} held |
| `hyperevm.activity` | object | {scope, swaps, transfers}: its moves are in recent[] |
| `hyperevm.freshness` | object | head, lagMs, blocksBehind, behindMs (as /api/status) |
| `hyperevm.bridges[] · bridges` | object | HyperCore ↔ HyperEVM transfers; legs in flight, journeys |
| `hypercore · elysium` | object | the same address on the other layers |

## Named wallets

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

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

| Param | In | Example or values |
|---|---|---|
| `layer` | query | `hyperevm` |
| `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=hyperevm&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 HyperEVM swaps and transfers of the named wallets, with who moved.

| Param | In | Example or values |
|---|---|---|
| `layer` | query | `hyperevm` |
| `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=hyperevm&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 HyperEVM swap, transfer and bridge leg of a named wallet, on each indexed block.

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

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

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

## Reference

### 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/hyperevm/lifecycle.md): One LiquidLaunch launch on HyperEVM told event by event from the Femtos API: launch, dev wallet, early buyers, swaps, holders, market cap over time.