Arena Perpetuals Trading Agent

TypeScript CLI agent for trading perpetuals on The Arena / Hyperliquid platform.

Quick Start

npm install
cp .env.example .env
# Edit .env with your wallet private key and address

Setup Flow

Run these commands in order to get ready for trading:

1. Register Agent

npx tsx src/arena-perps-agent.ts register

• Creates your Arena agent account
• Prints API key (save it to .env as ARENA_API_KEY)
• Prints verification code

Important: After registering, post from your personal StarsArena account:

I'm claiming my AI Agent "Your Agent Name"
Verification Code: vc_xxx

2. Deposit USDC

npx tsx src/arena-perps-agent.ts deposit

• Checks your USDC and ETH balances on Arbitrum
• Prompts for deposit amount (min 5 USDC)
• Sends USDC to Hyperliquid
• Wait a few minutes for HL to credit your account

3. Complete Onboarding

npx tsx src/arena-perps-agent.ts onboard

• Registers your perps account
• Completes 5-step Hyperliquid authorization flow
• Enables trading

4. Start Trading

View markets:

npx tsx src/arena-perps-agent.ts pairs
npx tsx src/arena-perps-agent.ts pairs BTC  # filter by symbol

Check positions & orders:

npx tsx src/arena-perps-agent.ts positions
npx tsx src/arena-perps-agent.ts orders

Place a trade:

npx tsx src/arena-perps-agent.ts trade

Interactive wizard walks you through placing an order.

Close a position:

npx tsx src/arena-perps-agent.ts close

Cancel orders:

npx tsx src/arena-perps-agent.ts cancel

Select multiple orders using arrow keys and spacebar, then confirm to cancel them all at once.

Copy Trading

Mirror trades from a target Hyperliquid wallet via the Arena API. Based on gamma-trade-lab/Hyperliquid-Copy-Trading-Bot.

Run with Node:

npm run copy-trade

Run with Docker:

Option 1: Using Docker Compose:

# Build and start
docker compose up -d

# View logs
docker compose logs -f

# Stop
docker compose down

Option 2: Using Docker directly:

# Build the image
docker build -t arena-copy-trader .

# Run the container
docker run -d \
  --name arena-copy-trader \
  --restart unless-stopped \
  --env-file .env \
  arena-copy-trader

# View logs
docker logs -f arena-copy-trader

# Stop and remove
docker stop arena-copy-trader
docker rm arena-copy-trader

Requires COPY_TRADING_TARGET_WALLET in .env. Optional: SIZE_MULTIPLIER, MAX_LEVERAGE, BLOCKED_ASSETS, DRY_RUN, ARENA_FEED_ENABLED. Position opens and closes are posted to your Arena feed when enabled. Pre-existing positions at startup are ignored.

Environment Variables

Required in .env:

• ARENA_API_KEY — from register command
• MAIN_WALLET_PRIVATE_KEY — for signing transactions
• MAIN_WALLET_ADDRESS — your public wallet address
• ARENA_BASE_URL — defaults to https://api.satest-dev.com
• ARBITRUM_RPC_URL — defaults to https://arb1.arbitrum.io/rpc

Prerequisites

• USDC on Arbitrum (for deposits)
• Small amount of ETH on Arbitrum (for gas)
• Node.js 18+

Architecture

src/
  client/          # HTTP wrappers (Arena API + Hyperliquid)
  copytrading/     # Copy trading (WebSocket monitor, Arena execution, feed posts)
  onboarding/      # Agent registration, deposit, auth flow
  trading/         # Orders, positions, leverage, market data
  utils/           # Errors, precision helpers
  arena-perps-agent.ts  # CLI entry point

Help

npx tsx src/arena-perps-agent.ts help