# Changelog · Femtos > Every change to the Femtos API that a developer sees: REST, WebSocket, MCP, the Hyperliquid-compatible API and keys, with the versioning and deprecation policy. - 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://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: https://femtos.xyz/changelog · Atom feed: https://femtos.xyz/changelog.xml ## Versioning and deprecation policy - The API is versioned in its path (`/v1`). Within a version, additive changes ship without notice: new routes, WebSocket channels, MCP tools, response fields, optional parameters and headers. Ignore fields you do not know. - A breaking change (a field, parameter, header, route or channel removed or renamed, a type or default changed) is announced here first, tagged `deprecated` or `breaking`. - The old form keeps working for at least 3 months after its announcement. - A request that uses a deprecated form answers with `Deprecation` (RFC 9745: since when) and `Sunset` (RFC 8594: the date it may stop working) headers, plus `Link: >; rel="deprecation"` pointing at its entry here. - The Hyperliquid-compatible `POST /info` and `/ws` follow Hyperliquid: their shapes change when Hyperliquid changes them. - Follow the changes: the Atom feed `https://femtos.xyz/changelog.xml` or the Markdown `https://femtos.xyz/changelog.md`. ## Changes ### 2026-10-21 · Unified pagination **changed** · **deprecated** · REST · https://femtos.xyz/changelog#pagination Every list route pages the same way: the answer carries `next_cursor` and a `Link: <…>; rel="next"` header, and the next page is asked with `?cursor=`. Pass the cursor back unchanged. - Deprecated, still working until 2027-01-31: the `before` parameter, the offset `next`, the per-row `cursor` field and the `X-Next-Cursor` header. - A request that still uses one of them answers with `Deprecation` and `Sunset` headers and `Link: ; rel="deprecation"`. - Move to `?cursor=` before 2027-01-31; the rows themselves do not change. Docs: [Versioning and deprecation policy](https://femtos.xyz/changelog#versioning) · [OpenAPI](https://api.femtos.xyz/v1/openapi.json) ### 2026-10-21 · Stable error codes **added** · REST · https://femtos.xyz/changelog#error-codes Every error body carries a stable `code`, a readable `message`, a `docs_url` (`https://femtos.xyz/errors#`) and the `request_id`. Every response, success or error, carries an `X-Request-Id` header: quote it when you report a problem. - The existing `error` field is unchanged: clients that read it keep working. - Branch on `code`; the wording of `message` may improve. Docs: [Error codes](https://femtos.xyz/errors) ### 2026-10-21 · Authorization: Bearer is the one documented key header **changed** · REST, WS, MCP, hl-compat, docs · https://femtos.xyz/changelog#bearer-header The docs, snippets, OpenAPI, `401` bodies and the MCP registry entry (1.1.0) show one header for the key: `Authorization: Bearer `, on REST, the WebSocket ticket, MCP and the Hyperliquid-compatible `/info`. - `X-API-KEY` is still accepted everywhere it was: existing clients change nothing. Docs: [Agent guide](https://femtos.xyz/agents.md) ### 2026-10-21 · MCP: keyless discovery, 27 tools **added** · **changed** · MCP · https://femtos.xyz/changelog#mcp-keyless-discovery `initialize`, `tools/list` and `ping` answer without a key, so clients and MCP directories can list the tools before signing up (limited per IP, never counted). A `tools/call` without a key answers a tool error with the agent signup steps. - 9 new tools: `get_book`, `get_liquidations`, `get_liquidation_stats`, `get_positions`, `list_nft_collections`, `get_nft_collection`, `get_nft_tokens`, `get_nfts_owned`, `get_nft_transfers`: 27 in all. - Every tool has a title and is marked read-only. - Listed in the official MCP registry as `xyz.femtos/mcp`; server card at `https://femtos.xyz/.well-known/mcp.json`. Docs: [MCP server](https://femtos.xyz/mcp) ### 2026-10-21 · 401 answers say how to get a key **changed** · REST, MCP · https://femtos.xyz/changelog#useful-401 A missing or unknown key answers `401` with `WWW-Authenticate: Bearer realm="femtos"` and a body that points at the signup, for agents (proof of work, no browser) and for people. The `error` field stays `"unauthorized"`. Docs: [Agent onboarding](https://femtos.xyz/agents.md#agent-onboarding) ### 2026-10-21 · WebSocket tickets: no key in URLs **added** · **deprecated** · WS · https://femtos.xyz/changelog#ws-tickets `POST /v1/ws-ticket` with your key answers `{ticket, ttlS: 30}`; open `wss://api.femtos.xyz/v1/ws?ticket=` with it (single use, 30 s). The key never travels in a URL, so it stays out of proxy logs. - `/v1/ws?token=` is deprecated and still works; its removal date will be announced here at least 3 months ahead. - Open sockets of a revoked, rotated or expired key are closed with code `4001`. Docs: [WebSocket guide](https://femtos.xyz/agents.md#websocket) ### 2026-10-21 · HyperCore WebSocket channels in the OpenAPI **added** · WS, docs · https://femtos.xyz/changelog#hypercore-ws-channels The OpenAPI `x-websocket` list now covers the HyperCore channels: `hc.trades`, `hc.bbo`, `hc.book`, `hc.candles`, `hc.orders`, `hc.liquidations`, `hc.positions`, `hc.ledger`, plus `prices.hype` and `stats`. Docs: [hc.trades](https://femtos.xyz/hypercore/ws-trades) · [OpenAPI](https://api.femtos.xyz/v1/openapi.json) ### 2026-10-21 · Exact token amounts beyond 18 decimals **fixed** · REST, WS · https://femtos.xyz/changelog#exact-token-amounts Tokens with more than 18 decimals (55 on HyperEVM, 9 on Elysium) had their amounts rounded to 18 decimals in swaps, trades, candle volumes and liquidity. They are now served exact; prices and USD values keep 18 decimals. Docs: [HyperEVM trades](https://femtos.xyz/hyperevm/trades) ### 2026-10-21 · Named wallets: handles in place of addresses **changed** · REST, WS, MCP · https://femtos.xyz/changelog#named-wallet-handles A named wallet (the KOLs, traders and funds of `/v1/entities`) appears as its stable handle `.` in every field, string and WebSocket frame. A handle is accepted anywhere an address is: path, query, WebSocket filters and MCP tool inputs. - A raw address you already know can still be asked about (`/v1/wallet/0x…`): the answer says whether it is named. Docs: [Named wallets](https://femtos.xyz/hypercore/entities) ### 2026-10-21 · Account area and key management **added** · accounts/keys · https://femtos.xyz/changelog#account-area Continue with email at `https://femtos.xyz/accounts/`: a new mailbox gets a key, a known one a sign-in link. `/accounts/signin` reveals your key from a single-use emailed link; `/accounts/dashboard` shows the account. - Rotating or deleting a key is confirmed by an emailed link for people, by the management secret (`X-Management-Secret`) for agents. - Emergency freeze: `POST /accounts/me/freeze` with the key stops it at once; rotate it afterwards. Docs: [Agent onboarding](https://femtos.xyz/agents.md#agent-onboarding) ### 2026-10-21 · Bounded liquidation scans and WebSocket limits **changed** · REST, WS, hl-compat · https://femtos.xyz/changelog#bounded-scans `/v1/liquidations` reaches back 7 days (30 with `coin`): an older `from` is clamped and the answer’s `from` says so. - `/v1/ws`: inbound messages per connection and new-subscription snapshots per key follow the key’s rate and burst. - Hyperliquid-compatible `/ws`: subscriptions per key are capped. Docs: [Liquidations](https://femtos.xyz/hypercore/liquidations) ### 2026-10-21 · Docs readable by crawlers and agents **added** · docs, MCP · https://femtos.xyz/changelog#docs-for-agents Every femtos.xyz page is prerendered (readable with no JavaScript) and has a Markdown mirror: `/index.md`, `/.md`, `//.md`, `/mcp.md`. - `llms.txt` in the llmstxt.org format, `llms-full.txt`, `sitemap.xml`. - MCP discovery: `/.well-known/ai-catalog.json` and `/.well-known/mcp.json` (SEP-2127 server card). - `https://api.femtos.xyz/` answers a JSON index of the API: docs, OpenAPI, MCP, signup. Docs: [llms.txt](https://femtos.xyz/llms.txt) ### 2026-10-20 · Hosted MCP server **added** · MCP · https://femtos.xyz/changelog#mcp-server `https://api.femtos.xyz/mcp` (Streamable HTTP, stateless): Claude, Cursor, OpenAI agents and any MCP client query HyperCore, HyperEVM and Elysium with no code. 18 read-only tools at launch, each one GET of the REST API with the same key, rate limit and usage. - Answers are paged (50 rows by default) and cut at 48,000 characters. Docs: [MCP server](https://femtos.xyz/mcp) ### 2026-10-20 · Agent self-signup by proof of work **added** · accounts/keys · https://femtos.xyz/changelog#agent-signup `GET https://femtos.xyz/accounts/agent/challenge`, solve its SHA-256 proof of work, then `POST https://femtos.xyz/accounts/agent/signup {agent_name, salt, nonce}`: a key and a management secret (both shown once) on the free tier at once, with no browser and no email. - `GET /accounts/agent/me` with the key: the account, its tier and quotas. Docs: [Agent onboarding](https://femtos.xyz/agents.md#agent-onboarding) ### 2026-10-20 · Provenance on every row and aggregate **added** · REST, WS · https://femtos.xyz/changelog#provenance Every row cites its chain event and every aggregate the block it is cut at, so any value can be checked on-chain. Additive: no field changed. - Rows: `block`, `tx`, and `logIndex` on HyperEVM and Elysium (trades, `elysium.trades`, `hyperevm.trades`, `ascend.swaps`, wallet swaps, named-wallet moves). HyperCore trades: `tx` is the fill’s hash. - Aggregates: `height` and its time `asOf` on candles, volume, holders and owned NFTs. Docs: [Elysium trades](https://femtos.xyz/elysium/trades) ### 2026-10-20 · Spam tokens flagged and left out of lists **added** · **changed** · REST, WS · https://femtos.xyz/changelog#spam-tokens EVM token answers carry `spam` and `spamReason`. Lists leave spam tokens out by default: markets (and `X-Total-Count`), coins, launches, token families, wallet balances and USD totals, named-wallet moves. `includeSpam=true` (WebSocket: `include_spam`) shows them, flagged. - `GET /v1/tokens/spam?layer=hyperevm|elysium`: the flagged tokens, why and since when. - A spam token’s own detail still answers, flagged. Docs: [Spam tokens](https://femtos.xyz/hyperevm/spam-tokens) ### 2026-10-20 · One token across the three layers **added** · REST, WS · https://femtos.xyz/changelog#token-lifecycle `GET /v1/tokens/{address}/lifecycle`: a token from any layer’s id to its whole path (launched, registered, bridged, listed, perp), each stage with its chain evidence. `ascend.lifecycle` streams the stage changes. - `/v1/launches/{token}`: `fees.exact`, the fees by conservation from the Ascend ledger, next to the 1 % estimate. Docs: [Token lifecycle](https://femtos.xyz/elysium/token-lifecycle) · [ascend.lifecycle](https://femtos.xyz/elysium/ws-ascend-lifecycle) ### 2026-10-20 · Ascend launches: filters, holders, live streams **added** · REST, WS · https://femtos.xyz/changelog#ascend-api `/v1/launches` filters by `creator`, `quote`, `q`, `since` and `until`, and gives each Ascend launch its derived `ascend` progress (market cap, holders, volume, top-10 share). - `GET /v1/launches/{token}/holders`: concentration (top N, HHI, dev, flagged), dev and early tags. - `ascend.swaps` (every Ascend pool, one message per block) and `ascend.status` (transitions). Docs: [Launch holders](https://femtos.xyz/elysium/launch-holders) · [ascend.swaps](https://femtos.xyz/elysium/ws-ascend-swaps) ### 2026-10-20 · Three-layer wallet, named wallets on the EVM layers **added** · REST, WS · https://femtos.xyz/changelog#wallet-three-layers `/v1/wallet/{address}` adds NFTs, HyperEVM and Elysium swaps and transfers, the freshness of each section, bridges in flight and Core → HyperEVM → Elysium journeys. - `/v1/kols/leaderboard` and `/v1/kols/activity` take `layer=hyperevm|elysium`; `kol.activity` pushes those moves on each committed block. Docs: [Wallet](https://femtos.xyz/hypercore/wallet) · [HyperEVM named wallets](https://femtos.xyz/hyperevm/kols) ### 2026-10-20 · Bridge coverage **added** · REST · https://femtos.xyz/changelog#bridge-coverage `GET /v1/bridges/coverage`: HyperCore ↔ HyperEVM matching over the whole history or 30 d, 7 d, 24 h: matched legs, unmatched by reason, pending and reverted credits, latency percentiles. `/v1/status` gains a `bridges` block. Docs: [Bridge coverage](https://femtos.xyz/hypercore/bridge-coverage) ### 2026-10-20 · Public correctness audit **added** · REST, docs · https://femtos.xyz/changelog#correctness-audit Random items of what Femtos serves are compared field by field with their source of truth (Hyperliquid’s public API, the HyperEVM and Elysium chains); every mismatch is published with what became of it. `GET /v1/audit` needs no key. Docs: [Correctness audit](https://femtos.xyz/audit) ### 2026-10-20 · HIP-4 outcome coins in HyperCore trades and candles **changed** · REST, WS · https://femtos.xyz/changelog#hip4-outcomes Outcome coins are traded as Hyperliquid lists them: a match on one side is also a trade of the other side at `1 - px`, a burn is a trade on each side, and splits, merges and settlements are not trades. Docs: [HyperCore trades](https://femtos.xyz/hypercore/trades) ### 2026-10-20 · TWAP slice fills out of userFills **fixed** · hl-compat · https://femtos.xyz/changelog#twap-slice-fills `userFills` and `userFillsByTime` leave a TWAP owner’s slice fills out, as Hyperliquid does (it serves them in `userTwapSliceFills`); the counterparty keeps its side. Found by the correctness audit. Docs: [Hyperliquid-compatible /info](https://femtos.xyz/hypercore/info) ### 2026-10-19 · Public API on api.femtos.xyz **added** · REST, WS, hl-compat · https://femtos.xyz/changelog#public-api `https://api.femtos.xyz` is the public API host: REST under `/v1`, WebSocket at `/v1/ws`, the Hyperliquid-compatible `POST /info` and `/ws`, CORS open. The contract: `https://api.femtos.xyz/v1/openapi.json` (OpenAPI 3.1). - Three layers: HyperCore, HyperEVM and Elysium (served from its testnet until mainnet indexing starts); most routes take `layer=`. - Decimals are exact strings, times Unix milliseconds, addresses lowercase `0x`. - Every answer carries `Server-Timing`: the time spent in the API. Docs: [Status](https://femtos.xyz/hypercore/status) · [OpenAPI](https://api.femtos.xyz/v1/openapi.json) ### 2026-10-19 · Hyperliquid-compatible /info and /ws **added** · hl-compat · https://femtos.xyz/changelog#hyperliquid-compatible `POST https://api.femtos.xyz/info` and `wss://api.femtos.xyz/ws` take the same requests and frames as `api.hyperliquid.xyz`: an existing client (Hyperliquid SDKs, CCXT) changes its base URL and sends the key. Docs: [/info](https://femtos.xyz/hypercore/info) · [/ws](https://femtos.xyz/hypercore/hl-ws) ### 2026-10-19 · Developer portal and agents.md **added** · docs · https://femtos.xyz/changelog#developer-portal femtos.xyz: one page per endpoint with its parameters, response fields, a ready call and its latency measured live, and a speed board per layer. `agents.md` (the whole API in one Markdown file, also `llms-full.txt`) and `llms.txt` are generated from the same endpoint list. Docs: [Agent guide](https://femtos.xyz/agents.md) · [HyperCore](https://femtos.xyz/hypercore) ### 2026-10-19 · Free API keys and per-key rate limits **added** · accounts/keys, REST, WS · https://femtos.xyz/changelog#free-keys-rate-limits Free keys at `https://femtos.xyz/accounts/` (proof of work in the browser, key shown once). Each key has a token bucket on REST and a cap on WebSocket connections. - Over the rate: `429` with `Retry-After` and `X-RateLimit-Limit`, `-Burst`, `-Remaining`, `-Reset`. - `GET /v1/whoami`: the key’s name, tier and the limits in force. Docs: [whoami](https://femtos.xyz/hypercore/whoami) ### 2026-10-19 · HyperEVM layer and EVM datasets **added** · REST, WS · https://femtos.xyz/changelog#hyperevm-layer `layer=hyperevm`: markets, candles, trades, holders, coins, LiquidLaunch launches with their bonding progress, and the `hyperevm.trades`, `hyperevm.candles`, `hyperevm.launches` channels. - On both EVM layers: NFT collections, tokens, holdings and transfers, daily token volume, token families, ERC-20 transfers, liquidity. - A layer still syncing answers what is indexed and says so: `syncing` and `dataUntil` on objects, `X-Layer-State` and `X-Data-Until` on arrays. A source that cannot answer gives `503 {error, unavailable}`. Docs: [HyperEVM endpoints](https://femtos.xyz/hyperevm) ### 2026-10-19 · Named wallets **added** · REST, WS · https://femtos.xyz/changelog#named-wallets `entity` next to addresses in holders, positions, liquidations, wallets, bridges and NFT answers; `/v1/entities`, `/v1/kols/leaderboard`, `/v1/kols/activity` and the `kol.activity` channel. Docs: [KOL leaderboard](https://femtos.xyz/hypercore/kols) · [kol.activity](https://femtos.xyz/hypercore/ws-kols) ### 2026-10-19 · Elysium channels push on each committed block **changed** · WS, REST · https://femtos.xyz/changelog#push-on-commit Elysium trades, candles and launches are pushed as soon as the indexer commits a block, instead of on a 250 to 500 ms poll. `/v1/status` measures each EVM layer against its node’s own head: `chainHead`, `blocksBehind`, `behindMs`. Docs: [Status](https://femtos.xyz/hypercore/status) ### 2026-10-19 · hc.bbo: HyperCore best bid and offer **added** · WS · https://femtos.xyz/changelog#hc-bbo `hc.bbo`: the top of book of one market each block, raced between Hyperliquid’s public feed and our node. `hc.trades` documents its raced copies: `block` is `null` when the public feed was first. Docs: [hc.bbo](https://femtos.xyz/hypercore/ws-bbo) · [hc.trades](https://femtos.xyz/hypercore/ws-trades)