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. 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
- 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.
- Press Connect wallet. Your wallet asks you to sign a short text that names the wallet, a number used once, and the time.
- 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
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:
[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:
describereturns 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 passmax_rowsormax_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).
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:
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:
fractrade-hl-mcp --new-key mainmakes an API wallet key on your computer and prints its address.- 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.
- Set your limits in the config file:
max_leverage,max_slippage, and optionallymax_order_usdand the list ofsymbolsit may trade. - Check it, then add the server with trading switched on:
fractrade-hl-mcp --check --enable-trading --online
claude mcp add --scope user hyperliquid -- fractrade-hl-mcp --enable-trading
The fractrade-hl-simple repository 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, thencost) - "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, thenorders) - "Open a 2,000 USD long on ETH with a stop 2% below." (fractrade-hl-simple
buyandstop_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. Common questions are in the FAQ.