# HyperCore data API · Femtos

> HyperCore data API: the Hyperliquid exchange: order book, perps, spot, HIP-3 markets, liquidations, positions. 38 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/hypercore

## Market data

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

Every tradable perp, spot, HIP-3 and outcome market with 24 h stats.

| Param | In | Example or values |
|---|---|---|
| `layer` | query | `hypercore` |
| `includeOutcomes` | query | `(empty)`, `1` |

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

| Field | Type | Meaning |
|---|---|---|
| `id · symbol · base · quote` | string | market id (BTC, @107, xyz:SP500, #1230) |
| `kind` | perp \| spot \| hip3 \| outcome | market type |
| `price · change24h` | decimal · number | last trade, 24 h change in % |
| `volume24hUsd · trades24h` | decimal · int | rolling 24 h from our fills |
| `szDecimals · maxLeverage · dex` | int · string | contract specs |

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

OHLCV of any HyperCore market down to 1 s, ascending, UTC-aligned.

| Param | In | Example or values |
|---|---|---|
| `layer` | query | `hypercore` |
| `market` | query | `BTC` |
| `tf` | query | `1s`, `15s`, `1m`, `5m`, `15m`, `1h`, `4h`, `1d` |
| `limit` | query | `180` |

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/candles?layer=hypercore&market=BTC&tf=1m&limit=180"
```

| Field | Type | Meaning |
|---|---|---|
| `t` | int | unit start (ms) |
| `o · h · l · c` | decimal | price; backstop liquidations excluded |
| `v · vq` | decimal | volume in base, in quote |
| `n` | int | trades in the unit |
| `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 `hc.candles`

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

| Param | In | Example or values |
|---|---|---|
| `coin` | filter | `BTC` |
| `tf` | filter | `1s`, `15s`, `1m`, `5m`, `15m`, `1h`, `4h`, `1d` |

```json
{"op":"subscribe","channel":"hc.candles","filter":{"coin":"BTC","tf":"1s"}}
```

| Field | Type | Meaning |
|---|---|---|
| `snapshot: true` | Candle[] | last 300 candles at subscribe |
| `data` | Candle | {t,o,h,l,c,v,vq,n,block}, the forming candle |

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

Latest fills of one market, newest first.

| Param | In | Example or values |
|---|---|---|
| `layer` | query | `hypercore` |
| `market` | query | `BTC` |
| `limit` | query | `50` |

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

| Field | Type | Meaning |
|---|---|---|
| `t · block` | int | block time (ms), block |
| `px · sz` | decimal | price, size in base |
| `side` | B \| A | aggressor side |
| `id` | string | trade id (tid) |
| `tx` | string \| null | source: hash of the transaction whose fills made the trade |

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

All trades of one market as they happen: raced between our node and Hyperliquid's public feed, first copy sent, the other dropped.

| Param | In | Example or values |
|---|---|---|
| `coin` | filter | `BTC` |

```json
{"op":"subscribe","channel":"hc.trades","filter":{"coin":"BTC"}}
```

| Field | Type | Meaning |
|---|---|---|
| `snapshot: true` | Trade[] | last 50 trades at subscribe |
| `data` | Trade[] | the new trades: {t, px, sz, side, tid, hash, users, block} |
| `tid` | int | trade id, unique: dedupe on it |
| `users` | [buyer, seller] | both sides, lowercase 0x |
| `hash` | string | transaction hash (all zeros when the public feed gives none) |
| `block` | int \| null | null when the public feed was first; our node fills it in the snapshots |
| `latency_ms.source_to_sent` | int | trade time → sent by the server |

### Best bid / offer — WS `hc.bbo`

Top of book of one market each block: raced between Hyperliquid's public feed and our node (newest block wins, our node corrects the same block).

| Param | In | Example or values |
|---|---|---|
| `coin` | filter | `BTC` |

```json
{"op":"subscribe","channel":"hc.bbo","filter":{"coin":"BTC"}}
```

| Field | Type | Meaning |
|---|---|---|
| `data.bbo` | [[px, sz, n], [px, sz, n]] | best bid, best ask: price, size, order count |
| `data.time` | int | block time (ms) |
| `data.block` | int \| null | null when the public feed was first |
| `latency_ms.source_to_sent` | int | block → sent by the server |

### Order book — GET `/v1/book`

L2 book of one market with order counts, from our node.

| Param | In | Example or values |
|---|---|---|
| `coin` | query | `BTC` |
| `depth` | query | `20` |

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/book?coin=BTC&depth=20"
```

| Field | Type | Meaning |
|---|---|---|
| `bids · asks` | [px, sz, n][] | levels best first: price, size, order count |
| `height` | int | block of the book |

### Book stream — WS `hc.book`

Full-depth book, then the levels each block changes.

| Param | In | Example or values |
|---|---|---|
| `coin` | filter | `HYPE` |

```json
{"op":"subscribe","channel":"hc.book","filter":{"coin":"HYPE"}}
```

| Field | Type | Meaning |
|---|---|---|
| `snapshot: true` | {height, bids, asks} | full depth (a partial top-100 first) |
| `data` | {height, prevHeight, bids, asks} | changed levels; sz "0" = level removed |
| `prevHeight` | int | must equal your height, else resubscribe |

### Order updates — WS `hc.orders`

Every order status change, filterable by coin, user and status.

| Param | In | Example or values |
|---|---|---|
| `coin` | filter | `HYPE` |
| `user` | filter | (optional) |
| `status` | filter | `(empty)`, `open`, `filled`, `canceled`, `triggered`, `rejected` |

```json
{"op":"subscribe","channel":"hc.orders","filter":{"coin":"HYPE","status":"filled"}}
```

| Field | Type | Meaning |
|---|---|---|
| `data` | object | {coin, side, px, sz, orig_sz, status, order_type, tif, oid, user, block, time} |
| `status` | string | open, filled, canceled, triggered, *Rejected… |

### HYPE price — WS `prices.hype`

HYPE from the Hyperliquid oracle, perp mark and exchanges.

```json
{"op":"subscribe","channel":"prices.hype","filter":{}}
```

| Field | Type | Meaning |
|---|---|---|
| `data` | object | {token, source, price, quote, ts} |

## Liquidations & positions

### Liquidations — GET `/v1/liquidations`

Perp liquidations, newest first, one row per account, coin and block.

| Param | In | Example or values |
|---|---|---|
| `coin` | query | (optional) |
| `minNotional` | query | (optional) |
| `limit` | query | `50` |

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

| Field | Type | Meaning |
|---|---|---|
| `events[]` | object | {block, time, coin, user, side, method, trades, sz, notional, avgPx, markPx} |
| `side` | long \| short | side of the liquidated position |
| `method` | market \| backstop | liquidation path |
| `user · from · to` | query | account, window (ms): the last 7 days, 30 with coin |
| `from` | ms | start of the window read (an older from is clamped to it) |

### Liquidation stats — GET `/v1/liquidations/stats`

Totals, per coin, per time bucket and the largest, over a window.

| Param | In | Example or values |
|---|---|---|
| `window` | query | `1h`, `24h`, `7d`, `30d` |
| `coin` | query | (optional) |

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/liquidations/stats?window=24h"
```

| Field | Type | Meaning |
|---|---|---|
| `total` | object | {notional, count, accounts, longNotional, shortNotional, market, backstop} |
| `byCoin[]` | object | per coin, largest first |
| `buckets[]` | object | {t, longNotional, shortNotional, count}, bucketMs apart |
| `largest[] · topAccounts[]` | object | 10 largest liquidations, 20 most liquidated accounts |

### Liquidations stream — WS `hc.liquidations`

Each liquidation fill, the block it happens.

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

```json
{"op":"subscribe","channel":"hc.liquidations","filter":{}}
```

| Field | Type | Meaning |
|---|---|---|
| `snapshot: true` | object[] | last 50 liquidation fills |
| `data` | object | {coin, liquidated_user, liquidated_side, method, px, sz, notional, mark_px, time, block} |

### Positions — GET `/v1/positions`

Open positions of one perp with leverage and liquidation price.

| Param | In | Example or values |
|---|---|---|
| `coin` | query | `BTC` |
| `side` | query | `(empty)`, `long`, `short` |
| `sort` | query | `notional`, `upnl`, `liqDistance` |
| `limit` | query | `50` |

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/positions?coin=BTC&sort=notional&limit=50"
```

| Field | Type | Meaning |
|---|---|---|
| `positions[]` | object | {address, szi, side, entryPx, notional, upnl, leverage, marginMode, liqPx, liqDistancePct} |
| `markPx · asOf · height` | decimal · int | mark used, snapshot time and block |
| `sort · order` | string | applied sort |

### Open interest — GET `/v1/positions/overview`

Open interest, accounts and unrealized PnL per perp.

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

| Field | Type | Meaning |
|---|---|---|
| `coins[]` | object | {coin, markPx, longOi, shortOi, longAccounts, shortAccounts, upnlLong, upnlShort, biggest} |
| `longOi = shortOi` | decimal | every perp is zero-sum: the split is in accounts and PnL |

### Liquidation map — GET `/v1/positions/liqmap`

Notional that would be liquidated at each price around the mark.

| Param | In | Example or values |
|---|---|---|
| `coin` | query | `BTC` |
| `range` | query | `0.3` |
| `buckets` | query | `60` |

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/positions/liqmap?coin=BTC&range=0.3&buckets=60"
```

| Field | Type | Meaning |
|---|---|---|
| `buckets[]` | object | {px, longNotional, shortNotional, accounts}, px = bucket centre |
| `markPx · range` | decimal · number | centre and half-width (0.3 = ±30 %) |

### Position changes — WS `hc.positions`

Each perp position change, one per block, account and coin.

| Param | In | Example or values |
|---|---|---|
| `coin` | filter | `BTC` |
| `min_notional` | filter | `100000` |

```json
{"op":"subscribe","channel":"hc.positions","filter":{"coin":"BTC","min_notional":"100000"}}
```

| Field | Type | Meaning |
|---|---|---|
| `data` | object | {coin, user, kind, dir, start_position, end_position, sz, px, notional, liquidation} |
| `kind` | string | open, increase, reduce, close, flip |
| `min_notional` | filter | default 100000, "0" for all |

## Holders

### Token holders — GET `/v1/holders`

Spot balances of a HyperCore token, largest first.

| Param | In | Example or values |
|---|---|---|
| `layer` | query | `hypercore` |
| `token` | query | `HYPE` |
| `limit` | query | `20` |

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

### Perp holders — GET `/v1/holders`

Largest open positions of a perp, long and short.

| Param | In | Example or values |
|---|---|---|
| `layer` | query | `hypercore` |
| `token` | query | `BTC` |
| `kind` | query | `positions`, `balances` |
| `limit` | query | `20` |

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/holders?layer=hypercore&token=BTC&kind=positions&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 |

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

HyperCore tokens with their HyperEVM contract and price.

| Param | In | Example or values |
|---|---|---|
| `layer` | query | `hypercore` |
| `q` | query | (optional) |
| `limit` | query | `50` |

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

| Field | Type | Meaning |
|---|---|---|
| `id · symbol · decimals` | string · int | token name on HyperCore |
| `priceUsd · totalSupply` | decimal \| null | last price, supply |
| `links.core · links.evm` | object | spot index, HyperEVM contract |
| `coverage` | object | bridge link kind and verification |

### 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 | `hypercore` |
| `id` | path | `HYPE` |

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

| Field | Type | Meaning |
|---|---|---|
| `coin` | object | {id, symbol, name, decimals, totalSupply, priceUsd, links} |
| `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 HyperCore PnL, volume and open positions.

| Param | In | Example or values |
|---|---|---|
| `window` | query | `24h`, `7d`, `30d` |
| `sort` | query | `netPnl`, `realizedPnl`, `volume`, `fills`, `winRate`, `openNotional` |
| `limit` | query | `50` |

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/kols/leaderboard?window=7d&sort=netPnl&limit=50"
```

| Field | Type | Meaning |
|---|---|---|
| `rows[].entity` | {id, name, x, kinds} | who public lists name the wallets |
| `netPnl · realizedPnl · fees` | decimal | closed PnL of the fills minus USDC fees |
| `volume · fills · winRate` | decimal · int · 0–1 | quote volume, fills, closing fills in profit |
| `open` | object | open perps now: positions, notional, upnl, top 3 |

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

The latest fills of the named wallets, newest first, with who traded.

| Param | In | Example or values |
|---|---|---|
| `minNotional` | query | `10000` |
| `entity` | query | (optional) |
| `limit` | query | `50` |

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

| Field | Type | Meaning |
|---|---|---|
| `rows[]` | KolItem | {t, wallet, entity, coin, side, px, sz, notional, dir, closedPnl, tid} |
| `hash · block` | string · int | source: the fill’s transaction and block |
| `next · before` | string | cursor <time ms>:<block>:<event> of the next page |

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

Every fill, liquidation, EVM swap, transfer and bridge leg of a named wallet, live.

| Param | In | Example or values |
|---|---|---|
| `min_notional` | filter | `1000` |

```json
{"op":"subscribe","channel":"kol.activity","filter":{"min_notional":"1000"}}
```

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

### Named wallets — GET `/v1/entities`

Every named entity, its X account, kinds, sources and wallets.

| Param | In | Example or values |
|---|---|---|
| `q` | query | (optional) |
| `kind` | query | (optional) |

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

| Field | Type | Meaning |
|---|---|---|
| `entities[]` | Entity | {id, name, x, kinds, aliases, sources, wallets[]} |
| `wallets[].address` | handle | <entityId>.<hex>: a named wallet's address is never served, its handle stands for it in every answer and is accepted wherever an address is |
| `entity · <field>Entity` | {id, name, x, kinds} | next to named addresses in every answer |

### One entity — GET `/v1/entities/{id}`

One named entity: its wallets on the three layers and 30 days of HyperCore trading.

| Param | In | Example or values |
|---|---|---|
| `id` | path | `abraxascapital` |

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

| Field | Type | Meaning |
|---|---|---|
| `totals` | object | account value, open perps, spot and HyperEVM balances |
| `hypercore30d` | object | {fills, volume, realizedPnl, fees, netPnl, winRate} |
| `wallets[]` | object | each wallet: HyperCore account, HyperEVM / Elysium balances, recent moves |

## Bridge & wallet

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

Matched HyperCore ↔ HyperEVM transfers with 24 h stats.

| Param | In | Example or values |
|---|---|---|
| `route` | query | `core_evm` |
| `direction` | query | `(empty)`, `evm_to_core`, `core_to_evm` |
| `token` | query | (optional) |
| `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 | status, direction, token, account, amount, core{block,time,hash}, evm{block,time,tx} |
| `rows[].bridge_latency_ms` | int \| null | first leg → credited on the other layer |
| `stats` | object | 24 h: count, completed, stuck, latency p50 / p99 per direction, byToken |
| `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 (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 | `<address>` |

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

| Field | Type | Meaning |
|---|---|---|
| `hypercore.perp` | object | account value, margin, positions with liquidation price |
| `hypercore.spot` | object | balances with USD value |
| `hyperevm · elysium` | object | balances, NFTs, swaps / transfers and bridges on the other layers |
| `bridges` | object | legs in flight and journeys across the three layers |
| `*.freshness` | object | each section: head, headTime, lagMs, behindMs (as /api/status) |
| `recent[]` | object | {layer, kind: fill \| ledger \| bridge \| swap \| transfer, t, data} |

### Wallet stream — WS `wallet`

Every event of the three layers touching one address.

| Param | In | Example or values |
|---|---|---|
| `address` | filter | `<address>` |
| `channel` | filter | (optional) |

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

| Field | Type | Meaning |
|---|---|---|
| `snapshot: true` | object[] | last 50 events |
| `data` | {channel, data} | one event: hc.trades, hc.orders, hc.ledger, bridge.transfers… |
| `channel` | filter | kinds to keep, comma list |

### Ledger stream — WS `hc.ledger`

Deposits, withdrawals, transfers and other non-trade balance moves.

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

```json
{"op":"subscribe","channel":"hc.ledger","filter":{}}
```

| Field | Type | Meaning |
|---|---|---|
| `data` | object | {kind, user, token, amount, usdc_value, destination, hash, block, time} |
| `kind` | string | spotTransfer, send, deposit, withdraw, borrowLend… |

## Hyperliquid-compatible

### POST /info — POST `/info`

Hyperliquid’s /info request bodies, answered from our node.

Same request bodies as `https://api.hyperliquid.xyz/info`, on `https://api.femtos.xyz/info` with `Authorization: Bearer $FEMTOS_KEY`.

| Field | Type | Meaning |
|---|---|---|
| `allMids · l2Book · metaAndAssetCtxs` | type | market state |
| `candleSnapshot · fundingHistory` | type | history by coin and window |
| `userFills · userFillsByTime · historicalOrders` | type | one account |
| `body · answer` | JSON | same as api.hyperliquid.xyz/info |

### Hyperliquid WS — WS `/ws`

Hyperliquid’s WebSocket subscriptions, served from our node.

Same frames as `wss://api.hyperliquid.xyz/ws`, on `wss://api.femtos.xyz/ws?token=$FEMTOS_KEY`.

| Field | Type | Meaning |
|---|---|---|
| `{"method":"subscribe","subscription":{…}}` | frame | same frames as api.hyperliquid.xyz/ws |
| `trades · l2Book · candle · allMids · bbo` | type | market subscriptions |
| `userFills · orderUpdates` | type | one account |

## 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) |

### Stream stats — WS `stats`

Our HyperCore stream health, once a second.

```json
{"op":"subscribe","channel":"stats","filter":{}}
```

| Field | Type | Meaning |
|---|---|---|
| `data` | object | {msgsPerSec, p50, p99 (block → stream, ms), height, books, clients} |

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

## Hyperliquid SDKs, drop-in

`POST https://api.femtos.xyz/info` and `wss://api.femtos.xyz/ws` answer like `api.hyperliquid.xyz`: an existing Hyperliquid client only changes its base URL and sends the key.

TypeScript, @nktkas/hyperliquid:

```ts
import { HttpTransport, InfoClient, SubscriptionClient, WebSocketTransport } from '@nktkas/hyperliquid';

const KEY = process.env.FEMTOS_KEY!;
const info = new InfoClient({
  transport: new HttpTransport({ apiUrl: 'https://api.femtos.xyz', fetchOptions: { headers: { Authorization: `Bearer ${KEY}` } } }),
});
console.log(await info.l2Book({ coin: 'BTC' }));
// the WebSocket transport takes no headers: the key goes in the URL
const subs = new SubscriptionClient({ transport: new WebSocketTransport({ url: `wss://api.femtos.xyz/ws?token=${KEY}` }) });
await subs.allMids((d) => console.log(d));
```

Python, hyperliquid-python-sdk:

```python
import os, requests
from hyperliquid.info import Info
from hyperliquid.websocket_manager import WebsocketManager

KEY = os.environ["FEMTOS_KEY"]; BASE = "https://api.femtos.xyz"; AUTH = {"Authorization": f"Bearer {KEY}"}
# Info() fetches meta / spotMeta in its constructor, before headers can be set: pass them in
post = lambda body: requests.post(f"{BASE}/info", json=body, headers=AUTH, timeout=10).json()
info = Info(BASE, skip_ws=True, meta=post({"type": "meta"}), spot_meta=post({"type": "spotMeta"}))
info.session.headers.update(AUTH)
ws = WebsocketManager(BASE)   # wss://api.femtos.xyz/ws
ws.ws.header = AUTH           # sent on the upgrade
info.ws_manager = ws; ws.start()
print(info.all_mids())
info.subscribe({"type": "allMids"}, print)
```

ccxt (JavaScript; Python takes the same options):

```js
import ccxt from 'ccxt';

const KEY = process.env.FEMTOS_KEY;
// read-only: hostname moves every REST URL to api.femtos.xyz (/info); never send these headers to api.hyperliquid.xyz
const ex = new ccxt.pro.hyperliquid({
  hostname: 'femtos.xyz',
  headers: { Authorization: `Bearer ${KEY}` },
  urls: { api: { ws: { public: `wss://api.femtos.xyz/ws?token=${KEY}` } } },
});
await ex.loadMarkets();
console.log(await ex.fetchOrderBook('BTC/USDC:USDC'));
console.log(await ex.watchTrades('BTC/USDC:USDC'));
```