Hyperliquid Sub-Accounts: Advanced Position Management for AI Trading Bots

Hyperliquid sub-accounts give your trading bot the isolation it needs to run parallel strategies without cross-contaminating risk — but wiring up the signing logic, policy guards, and cross-protocol hedging yourself is where most teams sink weeks. If you're building an automated trading system that touches Hyperliquid perpetuals, you need wallet infrastructure that keeps up with your execution logic without becoming the bottleneck.

Why Infrastructure Is the Hidden Bottleneck

Algo traders spend most of their time on signal generation and execution logic. Wallet plumbing — key management, transaction signing, approval flows, risk limits — gets bolted on at the end, and that's exactly when it breaks. A missed position because the signing layer threw an unexpected error, a blown leverage limit because nothing was enforcing it programmatically, or a rogue session token that outlived its usefulness: these are infrastructure failures, not strategy failures.

The same problem gets worse at scale. If you're running multiple sub-accounts on Hyperliquid — one for momentum, one for delta-neutral, one for arb — each account needs its own session, its own policy envelope, and its own audit trail. Managing that manually with raw private keys is a liability waiting to materialize.

WAIaaS is an open-source, self-hosted Wallet-as-a-Service built specifically for AI agents and automated bots. It gives you a REST API, 45 MCP tools, and a 7-stage transaction pipeline with policy enforcement baked in — so your bot focuses on alpha, not key hygiene.

What WAIaaS Brings to Hyperliquid Trading

WAIaaS integrates Hyperliquid directly as one of its 15 DeFi protocol providers. That means perpetual futures, spot trading, and sub-accounts are all accessible through the same session-authenticated REST API your bot already uses for everything else.

The full protocol list spans aave-v3, across, dcent-swap, drift, erc8004, hyperliquid, jito-staking, jupiter-swap, kamino, lido-staking, lifi, pendle, polymarket, xrpl-dex, and zerox-swap. For a trading bot, that means you can express a complete strategy — long perp on Hyperliquid, hedge spot on Jupiter, bridge collateral via LI.FI — through one API surface with one authentication model.

No juggling five different SDKs with five different key formats.

The Policy Engine: Your Risk Manager in Code

Before we get to execution, let's talk about the piece that matters most for automated systems: enforcing limits programmatically.

WAIaaS ships a policy engine with 21 policy types and 4 security tiers (INSTANT, NOTIFY, DELAY, APPROVAL). For Hyperliquid specifically, the relevant policies are:

• PERP_MAX_LEVERAGE — hard cap on leverage your bot can set
• PERP_MAX_POSITION_USD — maximum notional per position
• PERP_ALLOWED_MARKETS — whitelist of tradeable markets
• SPENDING_LIMIT — amount-based 4-tier routing for all outgoing value
• VENUE_WHITELIST — allowed trading venues

The system is default-deny: if ALLOWED_TOKENS or CONTRACT_WHITELIST isn't configured, transactions are blocked. That's the right default for an autonomous bot. You define exactly what it can touch, and everything else is denied.

Here's how to set a spending limit with tiered security for a trading wallet:

curl -X POST http://127.0.0.1:3100/v1/policies \
  -H "Content-Type: application/json" \
  -H "X-Master-Password: my-secret-password" \
  -d '{
    "walletId": "<wallet-uuid>",
    "type": "SPENDING_LIMIT",
    "rules": {
      "instant_max_usd": 100,
      "notify_max_usd": 500,
      "delay_max_usd": 2000,
      "delay_seconds": 900,
      "daily_limit_usd": 5000
    }
  }'

With this configuration: transactions under $100 execute immediately (INSTANT), $100–$500 execute and notify you (NOTIFY), $500–$2000 queue for 15 minutes before executing (DELAY), and anything above $2000 requires explicit human approval (APPROVAL). Your bot can operate autonomously within its lane, and anything anomalous gets caught before it hits the chain.

Setting Up a Trading Bot: Step by Step

1. Deploy the Daemon

Start with Docker — the image is ghcr.io/minhoyoo-iotrust/waiaas:latest and binds to 127.0.0.1:3100 by default.

git clone https://github.com/minhoyoo-iotrust/WAIaaS.git
cd WAIaaS
docker compose up -d

For automated deployments, use auto-provision mode to generate the master password without manual input:

docker run -d \
  --name waiaas \
  -p 127.0.0.1:3100:3100 \
  -v waiaas-data:/data \
  -e WAIAAS_AUTO_PROVISION=true \
  ghcr.io/minhoyoo-iotrust/waiaas:latest

docker exec waiaas cat /data/recovery.key

2. Create a Trading Wallet and Session

# Create a wallet for Hyperliquid trading
curl -X POST http://127.0.0.1:3100/v1/wallets \
  -H "Content-Type: application/json" \
  -H "X-Master-Password: my-secret-password" \
  -d '{"name": "hyperliquid-perp", "chain": "evm", "environment": "mainnet"}'

# Create a session token for the bot
curl -X POST http://127.0.0.1:3100/v1/sessions \
  -H "Content-Type: application/json" \
  -H "X-Master-Password: my-secret-password" \
  -d '{"walletId": "<wallet-uuid>"}'

The session token (wai_sess_...) is what your bot uses for all subsequent calls. It's JWT HS256, scoped to a wallet, and has configurable TTL, maxRenewals, and absoluteLifetime. You can run separate sessions for separate sub-account strategies — each session gets its own policy envelope.

3. Apply Perp-Specific Policies

Before your bot touches Hyperliquid, lock down what it can do:

# Cap leverage at 10x
curl -X POST http://127.0.0.1:3100/v1/policies \
  -H "Content-Type: application/json" \
  -H "X-Master-Password: my-secret-password" \
  -d '{
    "walletId": "<wallet-uuid>",
    "type": "PERP_MAX_LEVERAGE",
    "rules": {"max_leverage": 10}
  }'

# Cap max position size
curl -X POST http://127.0.0.1:3100/v1/policies \
  -H "Content-Type: application/json" \
  -H "X-Master-Password: my-secret-password" \
  -d '{
    "walletId": "<wallet-uuid>",
    "type": "PERP_MAX_POSITION_USD",
    "rules": {"max_position_usd": 50000}
  }'

4. Execute a DeFi Action Through the Bot's Session

Once policies are in place, your bot calls the Hyperliquid provider through its session token:

curl -X POST http://127.0.0.1:3100/v1/actions/hyperliquid/<action-name> \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer wai_sess_<token>" \
  -d '{...}'

The 7-stage transaction pipeline handles validation, auth check, policy evaluation, optional wait (for DELAY-tier), execution, and confirmation — in that order. Your bot doesn't need to implement any of that logic itself.

5. Simulate Before Committing

For strategies where getting the trade wrong is expensive, use dry-run mode to simulate before submitting:

curl -X POST http://127.0.0.1:3100/v1/transactions/send \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer wai_sess_<token>" \
  -d '{
    "type": "TRANSFER",
    "to": "recipient-address",
    "amount": "0.1",
    "dryRun": true
  }'

The simulation runs through the full pipeline — policy checks included — without touching the chain. You get the exact outcome your bot would see on a live submission.

Gas Conditional Execution

One detail that matters for algorithmic systems: WAIaaS supports gas conditional execution, meaning transactions only execute when the gas price meets a configured threshold. For bots doing high-frequency or cost-sensitive operations, this is the difference between a profitable trade and a margin-eroded one.

You define the threshold; the pipeline checks it before execution. If gas is above the limit, the transaction waits. No polling loop in your bot code, no manual gas price checks — the pipeline handles it.

Multi-Strategy Architecture with Separate Sessions

Here's a pattern that works well for Hyperliquid sub-account strategies: one WAIaaS daemon, multiple wallets, multiple sessions, each with its own policy set.

WAIaaS Daemon
├── Wallet A (hyperliquid-momentum)
│   ├── Session: bot-momentum-001
│   ├── Policy: PERP_MAX_LEVERAGE = 5x
│   └── Policy: PERP_ALLOWED_MARKETS = BTC-USD, ETH-USD
│
├── Wallet B (hyperliquid-arb)
│   ├── Session: bot-arb-001
│   ├── Policy: PERP_MAX_LEVERAGE = 2x
│   └── Policy: SPENDING_LIMIT = $500 instant / $2000 delay
│
└── Wallet C (hyperliquid-delta-neutral)
    ├── Session: bot-dn-001
    └── Policy: PERP_MAX_POSITION_USD = $25000

Each bot process holds its own session token. Policies are enforced independently. If one strategy goes rogue — unexpected order size, wrong market, leverage spike — the policy engine blocks it without affecting the others.

TypeScript SDK for Bot Integration

If you'd rather use a typed SDK than raw curl, the TypeScript SDK (@waiaas/sdk) gives you the same capabilities with async/await and typed errors:

import { WAIaaSClient, WAIaaSError } from '@waiaas/sdk';

const client = new WAIaaSClient({
  baseUrl: process.env['WAIAAS_BASE_URL'] ?? 'http://localhost:3100',
  sessionToken: process.env['WAIAAS_SESSION_TOKEN'],
});

// Check balance before opening position
const balance = await client.getBalance();
console.log(`Balance: ${balance.balance} ${balance.symbol} (${balance.chain}/${balance.network})`);

// Submit transaction with error handling
try {
  const tx = await client.sendToken({
    type: 'TRANSFER',
    to: 'recipient-address',
    amount: '0.001',
  });

  // Poll for confirmation
  const POLL_TIMEOUT_MS = 60_000;
  const startTime = Date.now();
  while (Date.now() - startTime < POLL_TIMEOUT_MS) {
    const result = await client.getTransaction(tx.id);
    if (result.status === 'COMPLETED') {
      console.log(`Confirmed: ${result.txHash}`);
      break;
    }
    if (result.status === 'FAILED') {
      console.error(`Failed: ${result.error}`);
      break;
    }
    await new Promise(resolve => setTimeout(resolve, 1000));
  }
} catch (error) {
  if (error instanceof WAIaaSError) {
    // Structured errors: INSUFFICIENT_BALANCE, POLICY_DENIED, TOKEN_EXPIRED
    console.error(`[${error.code}] ${error.message}`);
  }
}

The Python SDK (waiaas) follows the same pattern with async/await if your bot stack is Python.

Human-in-the-Loop for High-Stakes Trades

For positions that exceed your APPROVAL tier threshold, WAIaaS integrates WalletConnect so the fund owner gets a signing request on their mobile wallet. The bot submits the transaction, it queues for approval, and execution only proceeds when the owner signs.

Three signing channels are available: push-relay, Telegram, and wallet-notification. You configure whichever fits your ops setup. For a trading team running a large book, Telegram notifications for anything above $10k with mobile approval is a sensible pattern — the bot handles everything below that autonomously.

# Approve a queued transaction (owner signs off-chain, submits via API)
curl -X POST http://127.0.0.1:3100/v1/transactions/<tx-id>/approve \
  -H "X-Owner-Signature: <ed25519-or-secp256k1-signature>" \
  -H "X-Owner-Message: <signed-message>"

MCP Integration for AI-Driven Trading

If your trading system uses an LLM layer — Claude, GPT, or any MCP-compatible agent framework — WAIaaS exposes 45 MCP tools covering wallet, transaction, DeFi, NFT, and x402 operations. The hyperliquid and polymarket tools are available directly, so an AI agent can reason about positions, execute trades, and query state without custom tool code.

Setup is one command:

waiaas mcp setup --all

That auto-registers all wallets with Claude Desktop. For multi-strategy setups, configure separate MCP servers per wallet so each AI agent operates within its own session scope.

What's Next

The full API surface — 39 REST route modules with an OpenAPI 3.0 spec and interactive Scalar reference UI at /reference — is the place to go deep on Hyperliquid-specific action parameters and the complete policy schema. The 683+ test files in the codebase are also worth reading if you want to understand exactly how the pipeline handles edge cases.

If you're building something where execution reliability and risk containment matter more than convenience, self-hosting WAIaaS gives you full control over the signing layer, the policy engine, and the audit trail — nothing passes through third-party infrastructure.

Explore the codebase and deploy your own instance:

• GitHub: https://github.com/minhoyoo-iotrust/WAIaaS
• Official site: https://waiaas.ai