# Trade with your AI agent

Give your AI agent two things: **what is happening on Hyperliquid**, and **the ability to act
on it**. fractrade gives it the first and fractrade-hl-simple the second, and you connect
both to your agent as MCP servers.

## What you need

- **An agent that speaks MCP.**
  - **For the data:** any MCP client, such as Claude Code, Claude Desktop or Codex CLI.
  - **For trading:** Claude, in Claude Code or Claude Desktop. Codex usually refuses to
    place live orders. Open-weight models work too, through any MCP client that runs them.
- **For the data:** a wallet that holds 10,000 FRAC on Hyperliquid (spot), which makes the
  API key your agent needs. [How to get FRAC](/token/#how-to-get-frac). The wallet only signs
  a text to prove it is yours. It never signs a transaction for this and is not used for
  trading. Without a key the MCP server and the API do not answer; you can still look at the
  app, where the open screens show data up to 15 minutes old.
- **For trading:** a Hyperliquid account. It can be a different wallet from the one that
  holds the FRAC, and for most people it should be.

## 1. Sign in with the wallet that holds your FRAC

1. Open **https://app.fractrade.xyz** in a browser that has your wallet (MetaMask, Rabby or
   similar). It is the only place your wallet is asked to sign.
2. Press **Connect wallet**. Your wallet asks you to sign a short text that names the wallet,
   a number used once, and the time.
3. Sign it. This is a signature, **not a transaction**: it costs nothing and moves nothing.

fractrade then reads the wallet's FRAC balance from Hyperliquid's spot side. With 10,000 FRAC
or more you see everything. You stay signed in for 30 days in that browser.

The balance is read again once a day. If the wallet falls below 10,000 FRAC, the parts for
holders close for the account, including its key, until it holds enough again. If you just
bought FRAC, press **Read my balance again** on the API screen instead of waiting.

## 2. Generate your API key

On the **Connect an agent** screen, under **Your key**, press **Generate API key**. The same
screen says what the key allows and shows the finished command for your agent with the key
filled in.

- The key is shown **once**. Copy it then: we keep only a fingerprint of it and cannot show
  it again.
- An account has **one key at a time**. To get a new one, press **Remove key** and generate
  again. Anything that used the old key stops working at once.
- The key lets a program or an agent **read** as your account, and add or remove wallets on
  your account's watchlist. It cannot trade, withdraw, sign anything or change anything in
  your wallet.
- The screen shows when the key was last used, so you can see that it is in use, and by
  nothing you do not know.

## 3. Connect fractrade to your agent

**Claude Code**

```bash
claude mcp add --scope user --transport http fractrade https://api.fractrade.xyz/mcp \
  --header "Authorization: Bearer YOUR_KEY"
```

**Codex CLI**

Put the key into an environment variable, for example `export FRACTRADE_KEY=YOUR_KEY`, and
add this to `~/.codex/config.toml`:

```toml
[mcp_servers.fractrade]
url = "https://api.fractrade.xyz/mcp"
bearer_token_env_var = "FRACTRADE_KEY"
```

**Claude Desktop and other clients**

Add a remote MCP server with the address `https://api.fractrade.xyz/mcp` and the header
`Authorization: Bearer YOUR_KEY`. Any client that supports MCP over HTTP with a custom header
works, and both generations of the protocol are supported.

The agent now has one tool for each question fractrade can answer, among them:

| Tool | Answers |
|---|---|
| `markets`, `market`, `candles` | every market, one market, and its candles |
| `trends` | up, down or sideways on four timeframes, and strength against BTC or the S&P 500 |
| `funding` | funding per year, its history, and what Binance and Bybit pay for the same market |
| `cost` | what a market order of 10,000, 100,000 and 1,000,000 USD pays right now |
| `tradfi` | stocks, indices and commodities: whether the real market is open, and the move since it closed |
| `events` | detections: spikes, large and sliced orders, liquidations, new listings, news |
| `discover`, `analysis`, `history` | wallets ranked by their own trades, and any one wallet in depth |
| `positioning`, `tiers` | what groups of wallets and the whole venue hold, long against short |
| `hedges` | which shorts are against coins the same wallet holds on Hyperliquid, and the long share without them |
| `position_check` | a position you hold or think of, set against its market: who is on each side and since when, where the whales, winners and losers stand, what is liquidated near the price, what funding pays it and what closing it costs |
| `wallet_check` | the same for every position a wallet holds, in one call: each of its largest positions against its market, with where its own liquidation price stands among the others |
| `opened` | who opened a position on a market in the last 1, 4 and 24 hours: longs against shorts by everyone, by wallets that won or lost 100,000 USD in 30 days and by whales, and the largest of them |
| `positions`, `orders` | what one wallet holds and which orders it has resting, asked of Hyperliquid at that moment |
| `whales`, `top_trades` | the largest orders, and the best and worst trades of the day |
| `insiders` | fresh wallets that are paid into and at once make one bet larger than their account, and what the price did after |
| `tracked`, `tracked_wallets` | every move of twenty wallets with the longest run of winning weeks, and why each is on the list |
| `watchlist` | the wallets you marked for yourself in the app, with what is known of each |
| `extras`, `agenda` | Fear & Greed, dollar coins flowing in or out, and the dates that move markets |

Two things worth telling your agent:

- **`describe`** returns the full explanation of any tool: what each field means and where
  the figures come from.
- **Answers are cut to a readable size** (25 rows, 120 chart points). Each answer lists what
  was cut under `_cut`. To see more, the agent can pass `max_rows` or `max_points`, or narrow
  the request.

## 4. Connect fractrade-hl-simple for your account and for trading

This server runs on your computer. Nothing about your account is sent to us. To trade with it,
use Claude or an open-weight model (see [What you need](#what-you-need)).

```bash
pip install "fractrade-hl-simple[mcp]"
fractrade-hl-mcp --init          # creates the config file and says where it is
```

Put the address of the account you trade into the config file, check it, and add the server
to your agent:

```bash
fractrade-hl-mcp --check
claude mcp add --scope user hyperliquid -- fractrade-hl-mcp
```

**It is read-only until you switch trading on.** Until then the agent can see your balances,
positions, orders and fills, and nothing more.

To let it trade:

1. `fractrade-hl-mcp --new-key main` makes an **API wallet** key on your computer and prints
   its address.
2. In the Hyperliquid app (More → API), authorize that address with your trading wallet. An
   API wallet can trade for the account, but it **cannot withdraw**.
3. Set your limits in the config file: `max_leverage`, `max_slippage`, and optionally
   `max_order_usd` and the list of `symbols` it may trade.
4. Check it, then add the server with trading switched on:

```bash
fractrade-hl-mcp --check --enable-trading --online
claude mcp add --scope user hyperliquid -- fractrade-hl-mcp --enable-trading
```

The [fractrade-hl-simple repository](https://github.com/fractrade-xyz/fractrade-hl-simple)
has the full setup guide, every tool and every limit.

> **Keep the approval prompt for trades.** Let the agent run the read tools without asking,
> but keep your client's confirmation for the trade tools, so that you see every order before
> it is sent.

## 5. Ask

With both servers connected, the agent can go from a question to an order:

- *"Which markets have the most extreme funding right now, and is there room to trade them?"*
  (`funding`, then `cost`)
- *"What are the wallets that made over a million in the last 30 days holding on BTC?"*
  (`tiers`, `positioning`)
- *"Which wallets have traded stocks on Hyperliquid best, and what does the top one have
  open?"* (`discover`, `analysis`)
- *"NVDA is closed. How far has the perpetual moved since the close, and what would a 50,000
  USD order cost?"* (`tradfi`, `cost`)
- *"How much of the short interest on HYPE is hedged with HYPE the same wallets hold?"*
  (`hedges`)
- *"I am long 20,000 USD of ETH. Who else is, where are longs liquidated below the price, and
  what does funding cost me per day?"* (`position_check`)
- *"Check every position my wallet holds: which is nearest to its liquidation, and what is
  liquidated before it?"* (`wallet_check`)
- *"Who opened positions on NVDA in the last four hours, and on which side are the wallets
  that made money this month?"* (`opened`)
- *"What do the wallets on my watchlist hold, and where does the largest one have its stop?"*
  (`watchlist`, then `orders`)
- *"Open a 2,000 USD long on ETH with a stop 2% below."* (fractrade-hl-simple `buy` and
  `stop_loss`, which you confirm)

fractrade provides data. It does not give advice, and neither part decides for you.

Keys, limits and error messages are explained on the [API page](/docs/api/). Common questions
are in the [FAQ](/docs/faq/).
