femtos

HyperCore data API

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, key in Authorization: Bearer. Markdown: HyperCore endpoints as Markdown.

Endpoints

Market data

  • Markets GET /v1/markets
    Every tradable perp, spot, HIP-3 and outcome market with 24 h stats.
  • Candles GET /v1/candles
    OHLCV of any HyperCore market down to 1 s, ascending, UTC-aligned.
  • Forming candle WS hc.candles
    The forming candle, pushed once per block where it changes.
  • Trades GET /v1/trades
    Latest fills of one market, newest first.
  • 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.
  • 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).
  • Order book GET /v1/book
    L2 book of one market with order counts, from our node.
  • Book stream WS hc.book
    Full-depth book, then the levels each block changes.
  • Order updates WS hc.orders
    Every order status change, filterable by coin, user and status.
  • HYPE price WS prices.hype
    HYPE from the Hyperliquid oracle, perp mark and exchanges.

Liquidations & positions

  • Liquidations GET /v1/liquidations
    Perp liquidations, newest first, one row per account, coin and block.
  • Liquidation stats GET /v1/liquidations/stats
    Totals, per coin, per time bucket and the largest, over a window.
  • Liquidations stream WS hc.liquidations
    Each liquidation fill, the block it happens.
  • Positions GET /v1/positions
    Open positions of one perp with leverage and liquidation price.
  • Open interest GET /v1/positions/overview
    Open interest, accounts and unrealized PnL per perp.
  • Liquidation map GET /v1/positions/liqmap
    Notional that would be liquidated at each price around the mark.
  • Position changes WS hc.positions
    Each perp position change, one per block, account and coin.

Holders

  • Token holders GET /v1/holders
    Spot balances of a HyperCore token, largest first.
  • Perp holders GET /v1/holders
    Largest open positions of a perp, long and short.
  • Token registry GET /v1/coins
    HyperCore tokens with their HyperEVM contract and price.
  • Coin detail GET /v1/coins/{layer}/{id}
    One token: its links across layers, the markets it trades on, its 5 largest holders.

Named wallets

  • KOL leaderboard GET /v1/kols/leaderboard
    KOLs, traders and funds ranked by their HyperCore PnL, volume and open positions.
  • KOL trades GET /v1/kols/activity
    The latest fills of the named wallets, newest first, with who traded.
  • KOL stream WS kol.activity
    Every fill, liquidation, EVM swap, transfer and bridge leg of a named wallet, live.
  • Named wallets GET /v1/entities
    Every named entity, its X account, kinds, sources and wallets.
  • One entity GET /v1/entities/{id}
    One named entity: its wallets on the three layers and 30 days of HyperCore trading.

Bridge & wallet

  • Bridge transfers GET /v1/bridges
    Matched HyperCore ↔ HyperEVM transfers with 24 h stats.
  • 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.
  • Bridge stream WS bridge.transfers
    Each HyperCore ↔ HyperEVM transfer, initiated then completed.
  • Cross-layer wallet GET /v1/wallet/{address}
    One address (or a named wallet's handle) on HyperCore, HyperEVM and Elysium, plus its latest events.
  • Wallet stream WS wallet
    Every event of the three layers touching one address.
  • Ledger stream WS hc.ledger
    Deposits, withdrawals, transfers and other non-trade balance moves.

Hyperliquid-compatible

  • POST /info POST /info
    Hyperliquid’s /info request bodies, answered from our node.
  • Hyperliquid WS WS /ws
    Hyperliquid’s WebSocket subscriptions, served from our node.

Reference

  • Freshness GET /v1/status
    Head and lag of each layer, measured now.
  • Stream stats WS stats
    Our HyperCore stream health, once a second.
  • Check your key GET /v1/whoami
    Answers the name your key is registered under, its tier, billing state and the limits in force.
  • OpenAPI document GET /v1/openapi.json
    The OpenAPI 3.1 contract of every REST call, public.

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

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

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)

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'));