This tutorial builds a small trading agent in TypeScript. It reads Bloxwap Swing signals, checks each setup against limits you set, and trades the ones that pass on Hyperliquid, with a stop and a target attached. Every order carries the Bloxwap builder code, so it's priced exactly like a trade placed in the app.

The agent uses two tools, each for what it does well:

  • The Bloxwap MCP server for signals. The agent connects to https://bloxwap.app/mcp and calls get_swing_signals, which needs no sign-in.
  • The @bloxwap/hyperliquid SDK for prices, positions, and orders, signed in your own process by an agent wallet: a key that can trade for your account but can't withdraw from it.

The MCP server doesn't place trades. Its order tools turn away every call until an agent can sign with a narrowly scoped key of its own. So in this tutorial, signing happens in your code, with a key that only you hold.

This agent trades real money. It runs as a dry run until you switch that off, and the defaults risk $20 of margin per trade. Leverage magnifies losses as well as gains, and no signal guarantees a profit. Read Keep the risk in view before you go live.

What you'll build

Once a minute, the agent:

  1. Calls get_swing_signals on the Bloxwap MCP server.
  2. Reads live prices and your open positions from Hyperliquid.
  3. Runs each setup through a risk gate: your limits on margin, leverage, stop distance, and expiry.
  4. Opens a position for each setup that passes, using an immediate-or-cancel order with the builder code attached.
  5. Attaches a stop-loss and a take-profit sized to the actual fill.

The whole agent is one file, about 350 lines with comments. This guide builds it in seven parts. Paste each block into agent.ts in order and you'll have the complete program.

Before you start

You'll need:

  • Node.js 22.18 or later, or Bun 1.3.3 or later. Both run TypeScript files directly.
  • A Hyperliquid account with USDC in it. If you trade on Bloxwap, that's the account you already have.
  • One trade on Bloxwap from that account. Your first trade approves the Bloxwap builder fee. The agent checks the approval before it starts. Approve the builder fee explains why it matters.

1. Set up the project

Create a folder and install the SDK and the MCP client:

mkdir swing-agent && cd swing-agent
npm init -y && npm pkg set type=module
npm install @bloxwap/hyperliquid @modelcontextprotocol/sdk

With Bun, run bun init -y and bun add instead. The SDK installs two optional packages, tiny-secp256k1 and hash-wasm, which give it WebAssembly signing and hashing. There's nothing to configure.

2. Create an agent wallet

The agent signs orders with its own key, never with your main wallet's. Hyperliquid calls this an agent wallet (or API wallet). Once you approve it, it can place and cancel orders for your account, but it can't withdraw or transfer funds. You can revoke it at any time.

Generate a key and store it in a .env file, which you keep out of version control:

echo "HYPERLIQUID_AGENT_KEY=0x$(openssl rand -hex 32)" >> .env
echo "HYPERLIQUID_ACCOUNT_ADDRESS=0xYourAccountAddress" >> .env
echo ".env" >> .gitignore

HYPERLIQUID_ACCOUNT_ADDRESS is the public address of the account you trade with. Replace the placeholder with it.

To approve the agent, you need its address. This script prints it:

address.ts
import { getWalletAddress } from '@bloxwap/hyperliquid/signing';

console.log(await getWalletAddress(process.env.HYPERLIQUID_AGENT_KEY as `0x${string}`));
node --env-file=.env address.ts   # or: bun address.ts

Open Hyperliquid's API page, connect the wallet you trade with, and authorize the printed address as an API wallet. Give it a name you'll recognize, such as swing-agent.

Never put your main wallet's private key or seed phrase in this file, in code, or in a prompt. The agent doesn't need either one, and Bloxwap will never ask for them. If the agent key ever leaks, revoke it on the same page. Your funds stay where they are.

Approve the builder fee

A builder code is how an app gets credit for the orders it routes to Hyperliquid. Each order names a builder address and a fee, and Hyperliquid charges that fee only if the account has approved it for that builder.

Bloxwap's builder fee is 0.05% of the order's value per fill, or 0.025% for Genesis traders. That's the same fee you pay in the app. The fees page has the full breakdown, including Hyperliquid's own exchange fee.

Only your main wallet can approve a builder fee. An agent wallet can't. Your first trade on Bloxwap asks for that approval, so if you've traded here, you're set. The agent checks the approval at startup and stops with a clear message if it's missing.

3. Configure the agent

Start agent.ts with the imports:

agent.ts
// agent.ts: trade Bloxwap Swing signals on Hyperliquid with the Bloxwap builder code.
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
import { ExchangeClient, HttpTransport, InfoClient } from '@bloxwap/hyperliquid';
import { buildOrder } from '@bloxwap/hyperliquid/api/exchange';
import { getWalletAddress, warmupSigning } from '@bloxwap/hyperliquid/signing';
import { formatPrice, formatSize } from '@bloxwap/hyperliquid/utils';

Then the configuration. LIMITS holds the rules the agent will never break, whatever a signal suggests. The defaults are deliberately small:

agent.ts
// ---------- 1. Configuration ----------

function hexEnv(name: string, length: number, hint: string): `0x${string}` {
  const value = process.env[name]?.toLowerCase();
  if (!value || !new RegExp(`^0x[0-9a-f]{${length}}$`).test(value)) {
    throw new Error(`Set ${name} to ${hint}`);
  }
  return value as `0x${string}`;
}

const DRY_RUN = process.env.DRY_RUN !== 'false'; // dry run unless you opt out
const ACCOUNT = hexEnv('HYPERLIQUID_ACCOUNT_ADDRESS', 40, 'your public account address');
const AGENT_KEY = hexEnv('HYPERLIQUID_AGENT_KEY', 64, 'your agent wallet key');

// Bloxwap's builder address, and the standard builder fee in tenths of a basis point (50 = 0.05%).
const BUILDER = '0x71b09a08257078a4d642f7dd7315e656c837329a';
const BUILDER_FEE = 50;

// Your limits. The agent never trades outside them, whatever a signal suggests.
const LIMITS = {
  marginUsd: 20, // collateral per trade, at the planned entry price
  maxLeverage: 3, // your own cap, below the signal's and the market's
  maxStopPct: 2, // furthest the stop may sit from the live price, in percent
  minMinutesLeft: 10, // skip setups that expire sooner than this
  slippageBps: 50, // entry limit sits 0.5% through the mid
};
const POLL_MS = 60_000;
const ENTRY_TTL_MS = 5_000; // Hyperliquid drops an entry that hasn't run within this window

A few notes:

  • DRY_RUN is on unless you set it to false. In a dry run the agent does everything except sign and send orders.
  • BUILDER_FEE is in tenths of a basis point. A basis point is 0.01%, so 50 tenths is 5 basis points, or 0.05%. If you hold Genesis, set it to 25.
  • maxLeverage caps leverage below the signal's suggestion and the market's maximum. Both of those are ceilings, not targets.

4. Connect the clients

Next, the clients. There's one HTTP transport for Hyperliquid, which keeps its connection warm, and one connection to the Bloxwap MCP server:

agent.ts
// ---------- 2. Clients ----------

// One transport for the life of the process keeps the HTTPS connection warm.
const transport = new HttpTransport();
const info = new InfoClient({ transport });
// Passing the raw key string makes the SDK sign with WASM secp256k1.
const exchange = new ExchangeClient({ transport, wallet: AGENT_KEY });

const mcp = new Client({ name: 'swing-agent', version: '1.0.0' });
await mcp.connect(new StreamableHTTPClientTransport(new URL('https://bloxwap.app/mcp')));

ExchangeClient accepts the raw key string as its wallet. Given a key string, the SDK signs with tiny-secp256k1, a WebAssembly build of the same secp256k1 library Bitcoin uses, and falls back to pure JavaScript where WebAssembly can't load.

5. Read Swing signals over MCP

The MCP client calls get_swing_signals like any other tool. Passing tradableOnly: true leaves out test signals. The server returns the setups as structured data under structuredContent:

agent.ts
// ---------- 3. Signals from the Bloxwap MCP server ----------

type SwingSignal = {
  coin: string;
  signalId: string;
  direction: 'LONG' | 'SHORT';
  entryPrice: number;
  stopLoss: number;
  takeProfit: number;
  leverage: number;
  confidence: number | null;
  expiresAt: number;
  tradable: boolean;
  entryPriceMin?: number | null;
  entryPriceMax?: number | null;
};

async function getSwingSignals(): Promise<SwingSignal[]> {
  const result = await mcp.callTool({
    name: 'get_swing_signals',
    arguments: { tradableOnly: true },
  });
  if (result.isError) {
    throw new Error(`get_swing_signals failed: ${JSON.stringify(result.content)}`);
  }
  const data = result.structuredContent as { signals?: SwingSignal[] } | undefined;
  return data?.signals ?? [];
}

Each setup has a direction, an entry price with an optional entry range, a stop, a target, a suggested leverage, and an expiry time. Let your AI agent read Trend and Swing signals explains every field.

6. Read markets and positions from Hyperliquid

Hyperliquid identifies each perpetual market by its position in the exchange's market list, its asset ID. szDecimals sets how finely a size can be split, and it also limits how many decimals a price can have:

agent.ts
// ---------- 4. Market data and positions from Hyperliquid ----------

type Market = { assetId: number; szDecimals: number; maxLeverage: number };

async function loadMarkets(): Promise<Map<string, Market>> {
  const meta = await info.meta();
  const markets = new Map<string, Market>();
  meta.universe.forEach((m, assetId) => {
    if (m.isDelisted) return;
    markets.set(m.name, { assetId, szDecimals: m.szDecimals, maxLeverage: m.maxLeverage });
  });
  return markets;
}

async function openCoins(): Promise<Set<string>> {
  const state = await info.clearinghouseState({ user: ACCOUNT });
  return new Set(state.assetPositions.filter((p) => Number(p.position.szi) !== 0).map((p) => p.position.coin));
}

openCoins reads your account by its public address, so it doesn't need a signature. The agent uses it to keep to one position per market.

7. Write the risk gate

The gate turns a signal into an exact order, or explains why it won't. Every check reads the live price, not the price when the signal was made:

agent.ts
// ---------- 5. The risk gate ----------

type Plan = {
  coin: string;
  market: Market;
  isBuy: boolean;
  leverage: number;
  size: string;
  entryPx: string;
  stopPx: string;
  targetPx: string;
};

// Returns a plan, or the reason the setup was skipped.
function plan(s: SwingSignal, market: Market | undefined, mid: number, held: Set<string>): Plan | string {
  if (!market) return 'market not listed';
  if (held.has(s.coin)) return 'already holding a position';
  if (s.expiresAt - Date.now() < LIMITS.minMinutesLeft * 60_000) return 'expires too soon';
  if (!(mid > 0)) return 'no live price';
  if (s.entryPriceMin != null && mid < s.entryPriceMin) return 'price below the entry range';
  if (s.entryPriceMax != null && mid > s.entryPriceMax) return 'price above the entry range';

  // Round prices to the market's rules first, then check what will actually be sent.
  const px = (n: number) => formatPrice(n, market.szDecimals);
  const isBuy = s.direction === 'LONG';
  const stopPx = px(s.stopLoss);
  const targetPx = px(s.takeProfit);
  const stop = Number(stopPx);
  const target = Number(targetPx);
  const stopOnRightSide = isBuy ? stop < mid : stop > mid;
  const targetOnRightSide = isBuy ? target > mid : target < mid;
  if (!stopOnRightSide || !targetOnRightSide) return 'price has moved past a level';
  const stopPct = (Math.abs(mid - stop) / mid) * 100;
  if (stopPct > LIMITS.maxStopPct) return `stop is ${stopPct.toFixed(2)}% away`;

  const leverage = Math.floor(Math.min(s.leverage, LIMITS.maxLeverage, market.maxLeverage));
  if (leverage < 1) return 'leverage below 1x';
  const slip = LIMITS.slippageBps / 10_000;
  const entryPx = isBuy ? px(mid * (1 + slip)) : roundUpPx(mid * (1 - slip), market.szDecimals);
  const entrySlip = Math.abs(Number(entryPx) - mid) / mid;
  if (entrySlip > slip) return 'price too coarse for the slippage limit';
  // Size from the worse of the mid and the entry limit: a long that fills at its limit
  // still uses no more than marginUsd.
  const notional = LIMITS.marginUsd * leverage;
  const rawSize = notional / Math.max(mid, Number(entryPx));
  const size = rawSize >= 10 ** -market.szDecimals ? formatSize(rawSize, market.szDecimals) : '0';
  if (Number(size) * mid < 10) return 'below the $10 minimum order';

  return { coin: s.coin, market, isBuy, leverage, size, entryPx, stopPx, targetPx };
}

// formatPrice truncates, which moves a sell limit away from the mid. Step it back up a tick.
function roundUpPx(target: number, szDecimals: number): string {
  const down = formatPrice(target, szDecimals);
  if (Number(down) >= target) return down;
  // One tick: five significant figures, at most 6 - szDecimals decimals, never coarser than 1.
  const exp = Math.floor(Math.log10(Number(down))) + 1;
  const tick = 10 ** Math.min(Math.max(exp - 5, szDecimals - 6), 0);
  return formatPrice(Number(down) + 1.5 * tick, szDecimals);
}

In order, the gate skips a setup when:

  • The market isn't listed, or you already hold a position in it.
  • It expires within 10 minutes. A setup that's about to expire leaves no room to manage the trade.
  • Price has left the entry range. If the market has already run, the setup's levels no longer describe the trade you'd get.
  • Price has moved past the stop or the target. Opening then would trigger an exit right away.
  • The stop is more than 2% away. At 3× leverage, a 2% move against you costs about 6% of your margin, plus fees.
  • The order would be under $10. That's Hyperliquid's minimum order value.

The entry is a limit order 0.5% through the mid price. It fills right away at the best prices available inside that band, and any part it can't fill is cancelled. The size is worked out from the worse of the mid and that limit price, so a long that fills at the top of the band still uses no more than marginUsd. A short can fill above the mid if price rises first. That uses a little more margin, but with the stop fixed, the loss at the stop is smaller.

formatPrice and formatSize round values to the market's rules: at most five significant figures for a price, and no more decimals than szDecimals allows for a size. Hyperliquid rejects orders that break those rules. Both helpers round down, and the gate checks the rounded prices, not the originals. Rounding down would push a short's entry limit further from the mid, so roundUpPx rounds it up instead. If a market's price steps are too coarse to fit inside the slippage limit, the gate skips it.

8. Place orders with the builder code

The order fields are terse. a is the asset ID, b is buy or sell, p is the price, s is the size, r marks the order reduce-only, and t is the order type. The builder object carries the Bloxwap builder address and fee on every order:

agent.ts
// ---------- 6. Execution ----------

// Every order carries the Bloxwap builder code.
const builder = { b: BUILDER, f: BUILDER_FEE } as const;

// a = asset, b = is buy, p = price, s = size, r = reduce only, t = order type.
function entryOrder(p: Plan) {
  // Keys in schema order, normalized decimal strings, a lowercase builder address:
  // the canonical wire form that lets the live path skip validation.
  return {
    orders: [
      {
        a: p.market.assetId,
        b: p.isBuy,
        p: p.entryPx,
        s: p.size,
        r: false,
        t: { limit: { tif: 'Ioc' as const } },
      },
    ],
    grouping: 'na' as const,
    builder,
  };
}

function protectionOrder(p: Plan, size: string) {
  const close = { a: p.market.assetId, b: !p.isBuy };
  return {
    orders: [
      // Stop: becomes a market order once the mark price reaches the trigger.
      {
        ...close,
        p: p.stopPx,
        s: size,
        r: true,
        t: { trigger: { isMarket: true, triggerPx: p.stopPx, tpsl: 'sl' as const } },
      },
      // Target: a limit order at the target price, so it never fills worse than planned.
      {
        ...close,
        p: p.targetPx,
        s: size,
        r: true,
        t: { trigger: { isMarket: false, triggerPx: p.targetPx, tpsl: 'tp' as const } },
      },
    ],
    grouping: 'positionTpsl' as const,
    builder,
  };
}

async function execute(p: Plan) {
  if (DRY_RUN) {
    // Validate both actions exactly as the SDK would before signing; nothing is signed or sent.
    buildOrder(entryOrder(p));
    buildOrder(protectionOrder(p, p.size));
    console.log(
      `[dry run] ${p.isBuy ? 'LONG' : 'SHORT'} ${p.size} ${p.coin} @ ${p.entryPx} limit,`,
      `${p.leverage}x isolated, stop ${p.stopPx}, target ${p.targetPx}`,
    );
    return;
  }

  // Isolated margin caps the loss on this position at its own margin.
  await exchange.updateLeverage({
    asset: p.market.assetId,
    isCross: false,
    leverage: p.leverage,
  });

  const t0 = performance.now();
  const expiresAfter = Date.now() + ENTRY_TTL_MS;
  try {
    const entry = await exchange.order(entryOrder(p), { skipValidation: true, expiresAfter });
    const status = JSON.stringify(entry.response.data.statuses[0]);
    console.log(`${p.coin}: entry ${status} in ${(performance.now() - t0).toFixed(0)} ms`);
  } catch (error) {
    // A rejected entry throws, but so does a lost response to an entry that filled.
    // Wait out the expiry: after it, an entry that hasn't run never will.
    console.error(`${p.coin}: entry request failed`, error);
    await new Promise((resolve) => setTimeout(resolve, expiresAfter - Date.now() + 1_000));
  }

  try {
    await protect(p);
  } catch (error) {
    // Never leave a position without its stop: close it at once.
    console.error(`${p.coin}: could not protect the position, closing`, error);
    await closeOrHalt(p);
  }
}

// The account, not the entry's response, says what filled. Protect exactly that size.
async function protect(p: Plan) {
  const size = await positionSize(p.coin);
  if (Number(size) === 0) {
    console.log(`${p.coin}: no position opened`);
    return;
  }
  await exchange.order(protectionOrder(p, size));
  console.log(`${p.coin}: holding ${size}, stop ${p.stopPx}, target ${p.targetPx}`);
}

// The open size as Hyperliquid reports it, already at the market's size precision.
async function positionSize(coin: string): Promise<string> {
  const state = await info.clearinghouseState({ user: ACCOUNT });
  const position = state.assetPositions.find((a) => a.position.coin === coin);
  return position ? position.position.szi.replace('-', '') : '0';
}

// Close the position with reduce-only orders until it's flat. If that can't be confirmed,
// stop the agent: an unprotected position needs a person.
async function closeOrHalt(p: Plan) {
  try {
    for (let attempt = 1; attempt <= 3; attempt++) {
      const size = await positionSize(p.coin);
      if (Number(size) === 0) return;
      const mid = Number((await info.allMids())[p.coin]);
      await exchange
        .order({
          orders: [
            {
              a: p.market.assetId,
              b: !p.isBuy,
              p: formatPrice(p.isBuy ? mid * 0.95 : mid * 1.05, p.market.szDecimals),
              s: size,
              r: true,
              t: { limit: { tif: 'Ioc' } },
            },
          ],
          grouping: 'na',
          builder,
        })
        .catch((error) => console.error(`${p.coin}: close attempt ${attempt} failed`, error));
    }
    if (Number(await positionSize(p.coin)) === 0) return;
  } catch (error) {
    console.error(`${p.coin}: could not confirm the close`, error);
  }
  console.error(`${p.coin}: POSITION MAY BE OPEN WITHOUT A STOP. Check the Bloxwap app now.`);
  process.exit(1);
}

The agent works in two steps:

  1. Open the position. It sets the market to isolated margin at the planned leverage, then sends the entry with the builder code. Isolated margin keeps this position's losses within its own margin instead of drawing on the rest of your account.
  2. Protect what filled. It reads the open size from your account and attaches a stop and a target for exactly that size, grouped as positionTpsl, so they close the position they belong to.

The agent reads the size from the account, not from the order's response, on purpose. If the network drops the response to an entry that filled, the request fails, but the position is still there and still gets its stop.

The entry also carries expiresAfter, a deadline five seconds out. Hyperliquid rejects the order if it hasn't run by then. When an entry request fails, the agent waits out that deadline before reading the account, so a request that was only delayed can't open a position after the agent has looked. This relies on your computer's clock being roughly right.

Why not send the entry and its exits in one request? Hyperliquid can bundle them, but if the entry fills only partly, it cancels the bundled exits. Sizing the exits from the account avoids that.

An open position without a stop is the outcome the agent exists to avoid. If the agent can't read the position, or Hyperliquid rejects the stop and target, closeOrHalt closes the position with reduce-only orders, checking the account after each attempt. If it can't confirm the position is flat after three tries, it prints a warning and stops the whole agent, because that position now needs a person.

The stop becomes a market order when Hyperliquid's mark price reaches the trigger. The target is a limit order at the target price, so it never fills worse than planned, but it can be left unfilled if price touches the level and turns. Neither one guarantees an exit price in a fast market.

9. Run the loop

The last part checks the setup before it trades, then polls once a minute:

agent.ts
// ---------- 7. The loop ----------

async function main() {
  // Preflight: the agent wallet is approved for your account, and the builder fee is approved.
  const agentAddress = await getWalletAddress(AGENT_KEY);
  const role = await info.userRole({ user: agentAddress });
  if (role.role !== 'agent' || role.data.user.toLowerCase() !== ACCOUNT) {
    throw new Error(`Agent wallet ${agentAddress} is not approved for ${ACCOUNT}`);
  }
  const approvedFee = await info.maxBuilderFee({ user: ACCOUNT, builder: BUILDER });
  if (approvedFee < BUILDER_FEE) {
    throw new Error('Approve the Bloxwap builder fee: trade once in Bloxwap with this account');
  }
  // Load WASM and compile the signing path now, not on the first order.
  await warmupSigning(AGENT_KEY);

  const markets = await loadMarkets();
  const acted = new Set<string>(); // signals already acted on in this run
  const lastSkip = new Map<string, string>(); // log each skip reason once per signal
  console.log(`swing agent running (${DRY_RUN ? 'dry run' : 'LIVE'}) for ${ACCOUNT}`);

  const tick = async () => {
    const [signals, mids, held] = await Promise.all([getSwingSignals(), info.allMids(), openCoins()]);
    for (const s of signals) {
      if (acted.has(s.signalId)) continue;
      let result: Plan | string;
      try {
        result = plan(s, markets.get(s.coin), Number(mids[s.coin]), held);
      } catch (error) {
        result = `could not price the order (${(error as Error).message})`;
      }
      if (typeof result === 'string') {
        if (lastSkip.get(s.signalId) !== result) {
          console.log(`skip ${s.coin} ${s.direction}: ${result}`);
        }
        lastSkip.set(s.signalId, result);
        continue;
      }
      acted.add(s.signalId);
      await execute(result);
      held.add(s.coin);
    }
  };

  for (;;) {
    await tick().catch((error) => console.error('tick failed', error));
    await new Promise((resolve) => setTimeout(resolve, POLL_MS));
  }
}

await main();

Before it does anything else, the agent confirms three things:

  • The agent wallet is approved for your account. userRole returns the account an agent wallet belongs to.
  • The builder fee is approved. maxBuilderFee returns the highest fee your account allows for the Bloxwap builder.
  • The signing path is warm. warmupSigning loads the WebAssembly modules and signs a throwaway action, so the first real order doesn't pay that start-up cost. Nothing is sent.

The agent acts on each signal at most once per run, and logs each skip reason once per signal, so the log stays readable. It keeps that memory only while it runs. A restart forgets it, though the one-position-per-market check still applies.

Run it

Start with a dry run:

node --env-file=.env agent.ts   # or: bun agent.ts

The agent runs every check, builds and validates every order with the SDK's buildOrder, and prints what it would do. The output looks like this (illustrative, not a live signal):

swing agent running (dry run) for 0x…
skip ETH SHORT: already holding a position
skip SOL LONG: stop is 3.00% away
[dry run] LONG 0.00081 BTC @ 73563 limit, 3x isolated, stop 72465, target 74661

There may be no Swing setups at the moment you start. The agent just waits for the next one.

When the dry run looks right, go live with the same small limits:

DRY_RUN=false node --env-file=.env agent.ts

Live positions appear in the Bloxwap app like any other trade, with their stop and target. Stop the agent with Ctrl+C. Open positions keep their stop and target on Hyperliquid after the agent stops.

Low-latency recipes

A Swing setup plays out over minutes, so this agent doesn't need to be fast. If you adapt it for faster strategies, the SDK has four levers. The agent already uses the first three. The figures come from the SDK's own benchmarks, measured with Bun on one Linux server, and will vary on your machine:

  • Sign with WebAssembly. Passing the key string as wallet signs with WebAssembly secp256k1. In those benchmarks a signed order took about 118 microseconds this way, against about 159 with a pure-JavaScript viem account.
  • Warm up before the first order. A cold process's first order took about 5.5 milliseconds to sign, against about 0.1 once warm. After warmupSigning, the first order took about 1.3.
  • Skip validation on trusted input. By default the SDK validates and normalizes every action before signing it. { skipValidation: true } skips that pass, so the input must already be in Hyperliquid's exact wire form: keys in schema order, decimals as normalized strings, and lowercase addresses. The agent uses it only for the entry, whose shape its own code controls. The dry run checks that same shape with buildOrder, so an error shows up before any money is involved.
  • Batch orders. One order() call can carry many orders under a single signature. In the benchmarks, 100 orders in one call cost about 3.2 microseconds each.

Signing takes microseconds. The network round trip to Hyperliquid's API takes far longer, so keep one transport for the life of the process, as the agent does, and run the agent close to the API. The low-latency recipes cover more.

Where an LLM fits

This agent has no language model in it, on purpose. The decisions that move money are plain code you can read and test.

If you build with LangGraph, CrewAI, or your own loop, keep that split:

  • Let the model read. It can call the Bloxwap MCP server, summarize setups, compare them, or explain one in plain language.
  • Let the model veto, never add. A model step can drop a setup the gate passed. It can't raise a limit or create an order the gate didn't plan.
  • Keep the key out of the model's reach. The agent key belongs to the process that runs execute, never in a prompt, a tool argument, or a model's context.

In a graph framework, that means a model node between fetching signals and running the gate, and execute reachable only from the gate's output.

Keep the risk in view

An agent trades faster than you can watch. These habits keep it inside the lines:

  • Start small. Keep marginUsd low until you've watched the agent through many signals, not one good day.
  • Watch the first live trades. Confirm in the app that each position has its stop and target.
  • Know how to stop it. Ctrl+C stops new trades. Revoking the agent wallet on Hyperliquid's API page makes Hyperliquid reject anything it signs.
  • Remember that signals can be wrong. Swing describes a setup, not an outcome. Funding, fees, and liquidation risk still apply. Agent permissions covers more guardrails, such as daily loss limits.
  • Check where you live. Bloxwap isn't available in every country. Running your own agent doesn't change the terms that apply to you.

Go further

  • The /agents page has MCP setup for each client, SDK quickstarts, and example prompts.
  • llms.txt and llms-full.txt give your coding assistant Bloxwap's docs in one file. Point it there before asking it to extend this agent.
  • Signing flows covers agent wallets, hardware wallets, and browser wallets.
  • The SDK documentation documents every client, method, and utility.

New to the signals themselves? Read Bloxwap Signals: how Swing and Trend work.