femtos

Changelog

Every change to the Femtos API a developer sees: REST, WebSocket, MCP, the Hyperliquid-compatible API and keys. Additive changes ship without notice; a breaking one is announced here first.

Atom feed · Markdown · surfaces: REST, WS, MCP, hl-compat, accounts/keys, docs

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: <https://femtos.xyz/changelog#<entry>>; 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.

Unified pagination

changeddeprecatedREST

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=<next_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: <https://femtos.xyz/changelog#pagination>; rel="deprecation".
  • Move to ?cursor= before 2027-01-31; the rows themselves do not change.

Versioning and deprecation policyOpenAPI

Stable error codes

addedREST

Every error body carries a stable code, a readable message, a docs_url (https://femtos.xyz/errors#<code>) 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.

Error codes

Authorization: Bearer is the one documented key header

changedRESTWSMCPhl-compatdocs

The docs, snippets, OpenAPI, 401 bodies and the MCP registry entry (1.1.0) show one header for the key: Authorization: Bearer <key>, on REST, the WebSocket ticket, MCP and the Hyperliquid-compatible /info.

  • X-API-KEY is still accepted everywhere it was: existing clients change nothing.

Agent guide

MCP: keyless discovery, 27 tools

addedchangedMCP

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.

MCP server

401 answers say how to get a key

changedRESTMCP

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".

Agent onboarding

WebSocket tickets: no key in URLs

addeddeprecatedWS

POST /v1/ws-ticket with your key answers {ticket, ttlS: 30}; open wss://api.femtos.xyz/v1/ws?ticket=<ticket> with it (single use, 30 s). The key never travels in a URL, so it stays out of proxy logs.

  • /v1/ws?token=<key> 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.

WebSocket guide

Exact token amounts beyond 18 decimals

fixedRESTWS

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.

HyperEVM trades

Named wallets: handles in place of addresses

changedRESTWSMCP

A named wallet (the KOLs, traders and funds of /v1/entities) appears as its stable handle <entityId>.<hex> 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.

Named wallets

Account area and key management

addedaccounts/keys

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.

Agent onboarding

Bounded liquidation scans and WebSocket limits

changedRESTWShl-compat

/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.

Liquidations

Docs readable by crawlers and agents

addeddocsMCP

Every femtos.xyz page is prerendered (readable with no JavaScript) and has a Markdown mirror: /index.md, /<layer>.md, /<layer>/<slug>.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.

llms.txt

Hosted MCP server

addedMCP

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.

MCP server

Agent self-signup by proof of work

addedaccounts/keys

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.

Agent onboarding

Provenance on every row and aggregate

addedRESTWS

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.

Elysium trades

Spam tokens flagged and left out of lists

addedchangedRESTWS

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.

Spam tokens

One token across the three layers

addedRESTWS

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.

Token lifecycleascend.lifecycle

Ascend launches: filters, holders, live streams

addedRESTWS

/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).

Launch holdersascend.swaps

Bridge coverage

addedREST

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.

Bridge coverage

Public correctness audit

addedRESTdocs

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.

Correctness audit

Public API on api.femtos.xyz

addedRESTWShl-compat

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.

StatusOpenAPI

Hyperliquid-compatible /info and /ws

addedhl-compat

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.

/info/ws

Developer portal and agents.md

addeddocs

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.

Agent guideHyperCore

Free API keys and per-key rate limits

addedaccounts/keysRESTWS

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.

whoami

HyperEVM layer and EVM datasets

addedRESTWS

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

HyperEVM endpoints

Named wallets

addedRESTWS

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.

KOL leaderboardkol.activity

Elysium channels push on each committed block

changedWSREST

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.

Status

hc.bbo: HyperCore best bid and offer

addedWS

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.

hc.bbohc.trades