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

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.

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:

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:

  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:
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:

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.