# MCP server for agents · Femtos

> Femtos as a hosted MCP server (Streamable HTTP): Claude, Cursor, OpenAI agents and any MCP client query HyperCore, HyperEVM and Elysium data with no code.

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

## MCP

A hosted MCP server (Model Context Protocol, Streamable HTTP, stateless) at `https://api.femtos.xyz/mcp`: agents query the three
layers with no code. Same key as REST, in `X-API-KEY: $FEMTOS_KEY` or `Authorization: Bearer $FEMTOS_KEY`.
`initialize` and `tools/list` need no key; a tool call without a key (or with an unknown one) answers a tool error
`{"error": "unauthorized", "signup": {agent, browser}, …}`: an agent can sign up by itself (section "Agent onboarding").
Each tool runs one REST call with your key and counts like it (rate limit and usage). Answers are JSON text with the call they ran (`request`), 50 rows by default, cut to fit an agent's context
(`truncated` lists what was left out). Setup and tools: https://femtos.xyz/mcp

Claude Code:

```bash
claude mcp add --transport http femtos "https://api.femtos.xyz/mcp" \
  --header "X-API-KEY: $FEMTOS_KEY"
```

Cursor:

```jsonc
// ~/.cursor/mcp.json (or .cursor/mcp.json in a project)
{
  "mcpServers": {
    "femtos": {
      "url": "https://api.femtos.xyz/mcp",
      "headers": {
        "X-API-KEY": "${env:FEMTOS_KEY}"
      }
    }
  }
}
```

OpenAI:

```jsonc
// Responses API: tools of the request
[
  {
    "type": "mcp",
    "server_label": "femtos",
    "server_url": "https://api.femtos.xyz/mcp",
    "headers": {
      "X-API-KEY": "$FEMTOS_KEY"
    },
    "require_approval": "never"
  }
]
```

JSON:

```jsonc
// any Streamable HTTP client (VS Code, Windsurf, Zed…)
{
  "url": "https://api.femtos.xyz/mcp",
  "headers": {
    "X-API-KEY": "$FEMTOS_KEY"
  }
}
```

| Tool | Layers | Answers | REST call | Counts as |
|---|---|---|---|---|
| `get_status` | all | Each layer: indexed head, lag, live or syncing | `GET /v1/status` | free |
| `list_markets` | all | Perps, spot, HIP-3, outcomes; DEX pools, most traded first | `GET /v1/markets` | rest |
| `get_candles` | all | OHLCV of a coin or pool; pools in USD and market cap too | `GET /v1/candles` | rest (heavy over 30 days) |
| `get_trades` | all | Latest fills of a coin, swaps of a pool | `GET /v1/trades` | rest |
| `search_coins` | all | Tokens by symbol, name or address, linked across layers | `GET /v1/coins` | rest |
| `get_coin` | all | One token: links, markets, largest holders | `GET /v1/coins/{layer}/{id}` | rest |
| `get_holders` | all | Largest holders and concentration | `GET /v1/holders` | rest |
| `list_launches` | Elysium · HyperEVM | Ascend and LiquidLaunch launches, newest first | `GET /v1/launches` | rest |
| `get_launch` | Elysium · HyperEVM | Launch story: dev wallet, early buyers, signals, fees, Ascend progress | `GET /v1/launches/{token}` | rest |
| `get_launch_timeline` | Elysium · HyperEVM | Replayable life: swaps, holders and market cap over time | `GET /v1/launches/{token}/timeline` | rest |
| `get_token_lifecycle` | cross-layer | One token from Elysium launch to HyperCore perp, each link exact or inferred | `GET /v1/tokens/{address}/lifecycle` | rest |
| `get_bridges` | cross-layer | HyperCore ↔ HyperEVM and HyperEVM ↔ Elysium movements, both legs matched | `GET /v1/bridges` | heavy |
| `get_wallet` | cross-layer | One address on the three layers: positions, balances, bridges, latest events | `GET /v1/wallet/{address}` | heavy |
| `get_token_volume` | HyperEVM · Elysium | Daily USD swap volume of a token | `GET /v1/volume` | rest |
| `get_erc20_transfers` | HyperEVM · Elysium | ERC-20 transfers of a token, newest first | `GET /v1/transfers` | rest |
| `get_book` | HyperCore | Live L2 order book of a market from our node, with order counts | `GET /v1/book` | rest |
| `get_liquidations` | HyperCore | Perp liquidations, newest first, by coin, account or size | `GET /v1/liquidations` | rest |
| `get_liquidation_stats` | HyperCore | Liquidations over 1 h to 30 d: totals, per coin, per bucket, largest | `GET /v1/liquidations/stats` | rest |
| `get_positions` | HyperCore | Open positions of a perp: leverage, PnL, liquidation price | `GET /v1/positions` | rest |
| `list_nft_collections` | HyperEVM · Elysium | Most active NFT collections over 1 h or 24 h | `GET /v1/nfts/collections` | rest |
| `get_nft_collection` | HyperEVM · Elysium | One collection: metadata, tokens seen, 24 h activity | `GET /v1/nfts/collections/{address}` | rest |
| `get_nft_tokens` | HyperEVM · Elysium | Tokens of a collection: owner, metadata URI | `GET /v1/nfts/tokens` | rest |
| `get_nfts_owned` | HyperEVM · Elysium | NFTs a wallet holds, per collection | `GET /v1/nfts/owned` | rest |
| `get_nft_transfers` | HyperEVM · Elysium | Transfers of a collection or one token, newest first | `GET /v1/nfts/transfers` | rest |
| `search_entities` | all | Named wallets: KOLs, traders, funds and their addresses | `GET /v1/entities` | rest |
| `kol_leaderboard` | all | Named wallets ranked by PnL, volume, swaps or holdings | `GET /v1/kols/leaderboard` | rest |
| `kol_activity` | all | Latest fills, swaps and transfers of named wallets | `GET /v1/kols/activity` | rest |