# Plans and limits | Femtos

> Femtos plans and limits: the free key, what each call costs in credits, pay as you go, plans, rate limits, what 429 and 402 mean and how to check your usage.

- 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://dashboard.femtos.xyz/signup (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/docs/plans

What a key can spend and how fast it can call, and what the API answers at each limit.

## Free key

Every key starts free: no card, and the credits renew each month.

- Credits each month: 1,000,000 (≈ 1M REST calls or 46 GB of WebSocket data)
- Rate: 5 req/s, burst 30
- WebSocket connections at once: 2

## What a call costs

Every call counts credits against your key: the month's free credits first, then your plan's or your balance. A REST call counts 1 credit; calls that join layers or read long histories count more.

| Call | Credits |
| --- | --- |
| REST call: Any /v1 REST request not listed below | 1 |
| Hyperliquid-compatible call: POST /info (or a /ws post) of any type that is not heavy: meta, l2Book, allMids, clearinghouseState… | 0.5 |
| Medium call: Enriched answers (layers joined, analytics, simulations) | 5 |
| Heavy call: History, long windows and batches | 100 |
| Webhook delivery: Each delivery to your webhook URL; +0.1 per extra event of a batch, failed attempts free | 1 |
| WebSocket data: Every byte pushed to you on /v1/ws, /ws or /hl/ws, uncompressed, replays included, summed per hour (a BTC order book on /v1/ws, about 36 GB a month, is about 0.8M credits). Pongs, errors and status frames are free; a snapshot that mirrors a REST or /info call counts as that call | 1 per 48 KiB |

Medium calls:

- `GET /v1/liquidations/stats` https://femtos.xyz/reference/liquidation-stats.md
- `GET /v1/positions/changes` https://femtos.xyz/reference/position-changes.md
- `GET /v1/hypercore/builders/*/fills` https://femtos.xyz/reference/builder-fills.md
- `GET /v1/launches/*/holders` https://femtos.xyz/reference/launch-holders.md
- `GET /v1/launches/*/timeline` https://femtos.xyz/reference/timeline.md
- `GET /v1/tokens/*/lifecycle` https://femtos.xyz/reference/token-lifecycle.md
- `GET /v1/holders` https://femtos.xyz/reference/holders.md
- `GET /v1/wallet/*` https://femtos.xyz/reference/wallet.md
- `GET /v1/bridges` https://femtos.xyz/reference/bridge.md
- `GET /v1/entities/*/pnl window=90d` https://femtos.xyz/reference/entity-pnl.md
- `GET /v1/entities/*/pnl window=all` https://femtos.xyz/reference/entity-pnl.md
- `GET /v1/kols/leaderboard` https://femtos.xyz/reference/kols.md
- `GET /v1/tokens/*/security` https://femtos.xyz/reference/token-security.md
- `GET /v1/tokens/*/traders` https://femtos.xyz/reference/token-traders.md

Heavy calls:

- `POST /info type=userFills` https://femtos.xyz/reference/hl/info.md
- `POST /info type=userFillsByTime` https://femtos.xyz/reference/hl/info.md
- `POST /info type=candleSnapshot span>30d` https://femtos.xyz/reference/hl/info.md
- `POST /info type=historicalOrders` https://femtos.xyz/reference/hl/info.md
- `POST /info type=userFunding` https://femtos.xyz/reference/hl/info.md
- `POST /info type=userNonFundingLedgerUpdates` https://femtos.xyz/reference/hl/info.md
- `POST /v1/balances/batch` (one heavy call per 20 addresses) https://femtos.xyz/reference/batch-balances.md
- `GET /v1/candles span>30d` https://femtos.xyz/reference/candles.md
- `GET /v1/hypercore/wallet/*/stops history=1` https://femtos.xyz/reference/wallet-stops.md
- `GET /v1/hypercore/oi span>30d` https://femtos.xyz/reference/open-interest.md
- `GET /v1/prices/history span>30d` https://femtos.xyz/reference/price-history.md

Free (never counted, still answered when the key is out of credits):

- `GET /v1/status` https://femtos.xyz/reference/status.md
- `GET /v1/whoami` https://femtos.xyz/reference/whoami.md
- `GET /v1/openapi.json` https://femtos.xyz/reference/openapi.md

No daily limit: a key spends its credits as it likes, within its rate. Each MCP tool counts like the REST call it runs.

## Pay as you go

No plan needed. Past the free credits, calls are paid from your prepaid balance, each credit at the price of its band, counted over the month. Top up in USDC from $1; the balance never expires.

| Credits in a month | USD per million |
| --- | --- |
| First 100M | $12.00 / M |
| 100M to 1B | $10.00 / M |
| Over 1B | $8.00 / M |

### Throughput

Per key, the limits rise with what you prepay and spend: the highest level you reach applies, from the next minute.

| Level | Unlocked by | Req/s | Burst | WS connections |
| --- | --- | --- | --- | --- |
| Free | Every key | 5 | 30 | 2 |
| Level 1 | $10 prepaid | 20 | 40 | 3 |
| Level 2 | $349 spent this month | 100 | 200 | 20 |
| Level 3 | $999 spent this month | 300 | 600 | 50 |

## Plans

A plan buys a monthly allowance of credits and a higher throughput, paid from your balance. Yearly billing takes 15 % off. Past the included credits, calls go on and are charged per million from your balance at the plan's overage rate.

| Plan | Per month | Included credits | Req/s | Burst | WS conns | Past included |
| --- | --- | --- | --- | --- | --- | --- |
| Starter | $49 | 6,000,000 | 20 | 40 | 3 | $10.00 / M |
| Builder | $99 | 14,000,000 | 30 | 60 | 5 | $8.00 / M |
| Pro | $349 | 60,000,000 | 100 | 200 | 20 | $6.00 / M |
| Scale | $999 | 200,000,000 | 300 | 600 | 50 | $5.00 / M |

A monthly cap, set on your billing page, bounds the overage. An upgrade starts at once and credits back the unused part of the current plan; a downgrade starts when the paid period ends. Scale: larger volumes sized per customer. Contact: contact@femtos.xyz.

## At the limits

### 429 Too many requests

Over your key's rate. The rate is a bucket of `burst` requests refilled at `rps` per second: short bursts pass, a sustained rate above it does not. The answer carries `Retry-After` and `retryAfter` (seconds) with `code: "rate_limited"`: wait, then send the same call again. Past your WebSocket connections, a new `/v1/ws` connection is refused with 429 at the upgrade.

Every answer to a keyed call carries the bucket's state:

| Header | Value |
| --- | --- |
| `X-RateLimit-Limit` | Requests per second of your key |
| `X-RateLimit-Burst` | The most requests at once (the bucket) |
| `X-RateLimit-Remaining` | Requests left in the bucket now |
| `X-RateLimit-Reset` | Seconds until the bucket is full again |

### 402 Payment required

Out of credits: the month's free credits are used and the balance is empty. Every call but the free ones answers 402 with `code: "payment_required"`, and WebSockets are refused (an open one closes with code 4002), until you add funds or the month starts again. The body says why (`message`) and how to pay (`checkoutUrl`).

- **Pay per call with x402.** The REST 402 also offers credit packs in USDC on Base, Arbitrum One and HyperEVM (`accepts`, and the `PAYMENT-REQUIRED` header). An agent pays one and sends the same call again with its key: the account is credited and the call served. With no key at all, the same payment opens an account and returns its key. Not on the Hyperliquid-compatible `/info` and `/ws`: credit the account, then call again. How x402 works: https://femtos.xyz/agents.md#pay-with-x402-buy-credits-get-a-key
- **Monthly cap reached.** A cap you set on your billing page stops spending: the same 402, its message naming the cap, with no credit packs, until you raise the cap or the month ends.
- **Debt.** An account that owes money (plan overage past what it may run on credit, a payment taken back) answers 402 with the amount, `debtUsd`, until it is paid in full.

Error codes and what to do: https://femtos.xyz/errors.md (`rate_limited`, `payment_required`).

## Check your usage

`GET /v1/whoami` is free: your key's tier, billing state (`ok`, or why it is refused) and the limits in force, `{rps, burst, maxConns}`.

```sh
curl -s "https://api.femtos.xyz/v1/whoami" -H "Authorization: Bearer $FEMTOS_KEY"
```

- `GET /v1/account`, never counted: balance, credits used this month, free credits left, cap, plan and renewal. MCP: `get_account`.
- `GET /v1/account/usage`: calls, credits and USD per day and call class.
- On your dashboard: Usage & billing, https://dashboard.femtos.xyz/billing
- Both account calls in full: https://femtos.xyz/agents.md#manage-your-account

## Next

- Compare plans and pay: https://femtos.xyz/pricing
- Upgrade from your account: https://dashboard.femtos.xyz/billing#plans
- The price list as JSON: `GET https://femtos.xyz/accounts/pricing`