# API

Everything fractrade knows is available over plain HTTP at **`https://api.fractrade.xyz`**. The
[MCP server](/docs/agent-trading/) uses the same API, so a tool and an endpoint always give
the same answer.

```bash
curl -H "Authorization: Bearer YOUR_KEY" "https://api.fractrade.xyz/funding?min_oi=1000000"
curl -H "Authorization: Bearer YOUR_KEY" "https://api.fractrade.xyz/whales"
```

## Reference

The API describes itself, so its reference is always current:

| Where | What |
|---|---|
| `https://api.fractrade.xyz/` | every endpoint, its parameters and what it answers, as JSON |
| `https://api.fractrade.xyz/openapi.json` | the same, as an OpenAPI 3.1 document |
| The **API** screen of `https://app.fractrade.xyz` | the same, for people |

Endpoints sit at the top level, as on Hyperliquid's API: `/funding`, `/markets`, `/discover`.

| Group | For example |
|---|---|
| Markets | `/markets`, `/markets/{inst}/candles`, `/markets/{inst}/cost`, `/trends`, `/funding`, `/tradfi`, `/levels` |
| Detections | `/events`, `/events/stream` (server-sent events) |
| Wallets | `/wallets`, `/wallets/{id}`, `/wallets/{id}/analysis`, `/wallets/{id}/positions`, `/wallets/{id}/orders`, `/leaderboard`, `/discover`, `/whales`, `/insiders` |
| Positioning | `/positioning`, `/tiers`, `/hedges`, `/markets/{inst}/check` (one position against its market), `/wallets/{id}/check` (every position of a wallet), `/markets/{inst}/opened` (who opened in the last 1, 4 and 24 hours) |
| Tracked wallets | `/tracked`, `/tracked/wallets` |
| Your watchlist | `/watchlist` |
| News | `/news`, `/news/mentions` |
| Market-wide | `/extras`, `/agenda` |

## Keys

- **Every request needs a key**: the key of an account whose wallet holds 10,000 FRAC. Send it
  as `Authorization: Bearer YOUR_KEY`. Only the reference above is readable without one.
- You get the key in the app. [Trade with your AI agent](/docs/agent-trading/), steps 1 and 2,
  shows how.
- The reference marks some endpoints `open`: those are the ones the app shows to a visitor
  without an account, up to 15 minutes old. Through the API they need the key like the rest.

## Limits

Requests are counted per key.

| | Per minute | Per day |
|---|---|---|
| API key | 120 | 50,000 |

- A request that asks Hyperliquid at that moment (such as the cost of a trade, a position check,
  or a wallet's positions or resting orders right now) counts as **10**.
- Every answer says where you stand, in the headers `X-RateLimit-Limit`,
  `X-RateLimit-Remaining` and `X-RateLimit-Reset`.
- Over the limit, the answer is `429`, with `Retry-After` in seconds. A call through the MCP
  server reports the same as a tool error the agent can read and wait on.

## If something does not work

| You see | It means | Do |
|---|---|---|
| `401` "send your API key" | The request has no key, or its key was removed | Check the `Authorization: Bearer …` header; generate a key if you removed it |
| `403` "this wallet held …" | The account holds less than 10,000 FRAC | Top up, then press **Read my balance again** in the app |
| `429` "too many requests" | A limit was reached | Wait for the seconds in `Retry-After` |
| The balance shows less than you own | Some of it is staked, lent or held elsewhere | Only the spot balance on Hyperliquid counts |
| "No wallet was found in this browser" | The page cannot reach a wallet | Open the app in a browser with your wallet extension |
| The agent does not list the tools | The server was not added, or its address is wrong | Run `claude mcp list`. The address is `https://api.fractrade.xyz/mcp`, not the app's |
