Build a Hyperliquid trading bot in TypeScript
What you write
A Circuit agent is a TypeScript run function. Circuit calls it on a schedule from the triggers in circuit.toml, or runs it continuously, and your code requests typed actions through the agent object. Signing happens outside the agent's sandbox under the user's passkey-signed permit, so your code never handles private keys.
Set up
Install the CLI with Bun: bun install -g @circuitorg/agent-cli. Then circuit new --name my-bot creates index.ts, circuit.toml and DESCRIPTION.md. Edit the three together: the code, its triggers and settings, and the description users read.
Place a Hyperliquid order
agent.hyperliquid.orders.create takes an order proposal: { kind: "perpOpen", asset: "BTC", side: "long", amount: { valueUsdc: "100" } } opens a $100 BTC long with a market order within 1% of the mid. Pass execution to change that: { kind: "limit", price, timeInForce: "ioc" | "gtc" | "alo" } for limits, or takeProfit and stopLoss triggers on perpOpen and perpReduce. perpReduce, spotBuy and spotSell complete the set, and "max" sizes a reduce to the session's own position.
Read state the right way
Size every order from agent.allocation, the session's own holdings, rather than the whole account; a reduce is capped at what the session holds, so your agent never touches positions the user opened elsewhere. Log your reasoning with agent.log so users see why each trade happened.
Test, backtest, ship
circuit check --json verifies the project. circuit backtest --from <ISO> --to <ISO> --usd 1000 --json replays it against recorded Hyperliquid or Lighter markets without a wallet or network writes. circuit run --paper simulates funds on live markets. When it is ready, circuit auth login and circuit upload publish it, and users start it from the Circuit app.
Docs for AI coding tools
The docs publish llms.txt and llms-full.txt for language models, and an MCP server you can add to Claude Code with claude mcp add circuit --transport http https://docs.circuit.org/mcp, so your coding assistant writes against the current SDK.
Self-custodial by design
Agents run on a wallet you create in Circuit or import from Phantom, Rabby or MetaMask. Agents never see private keys: they request typed actions through Circuit's SDK, and Circuit signs outside the agent's sandbox only under a permit you sign with your passkey. Pause, resume or stop any agent at any time; stopping leaves your positions in your wallet.