open-broker

What this skill does

# Open Broker - Hyperliquid Trading Skill

Execute trading operations on Hyperliquid DEX with builder fee support.

## Quick Start (Automated Onboarding)

Run these two commands to get started:

```bash
npm install
npx tsx scripts/setup/onboard.ts
```

This will automatically:
1. Generate a new trading wallet
2. Create `.env` with your private key
3. Approve the builder fee (free, no funds needed)
4. Display your wallet address to fund

**After onboarding, fund your wallet:**
1. Send USDC to your wallet address on Arbitrum
2. Deposit to Hyperliquid at https://app.hyperliquid.xyz/
3. Start trading!

## Manual Setup (Alternative)

If you prefer manual setup or have an existing wallet:

1. Install dependencies: `npm install`
2. Copy and configure environment:
   ```bash
   cp config/example.env .env
   # Edit .env with your private key
   ```
3. Approve builder fee:
   ```bash
   npx tsx scripts/setup/approve-builder.ts
   ```

### Builder Fee

Open Broker charges a 1 bps (0.01%) builder fee on trades to fund development.
The onboarding script handles this automatically. To check or manage manually:

```bash
# Check if approved
npx tsx scripts/setup/approve-builder.ts --check

# Approve (must use main wallet, not API wallet)
npx tsx scripts/setup/approve-builder.ts
```

## Quick Reference

### Get Account Info
```bash
npx tsx scripts/info/account.ts
npx tsx scripts/info/account.ts --orders  # include open orders
```

### Get Positions
```bash
npx tsx scripts/info/positions.ts
npx tsx scripts/info/positions.ts --coin ETH
```

### Check Funding Rates
```bash
npx tsx scripts/info/funding.ts --top 20
npx tsx scripts/info/funding.ts --coin ETH
```

### View Markets
```bash
npx tsx scripts/info/markets.ts --top 30
npx tsx scripts/info/markets.ts --coin BTC
```

### All Markets (Perps + Spot + HIP-3)
```bash
npx tsx scripts/info/all-markets.ts                 # Show all markets
npx tsx scripts/info/all-markets.ts --type perp    # Main perps only
npx tsx scripts/info/all-markets.ts --type hip3    # HIP-3 perps only
npx tsx scripts/info/all-markets.ts --type spot    # Spot markets only
npx tsx scripts/info/all-markets.ts --top 20       # Top 20 by volume
```

### Search Markets (Find assets across providers)
```bash
npx tsx scripts/info/search-markets.ts --query GOLD    # Find all GOLD markets
npx tsx scripts/info/search-markets.ts --query BTC     # Find all BTC markets
npx tsx scripts/info/search-markets.ts --query ETH --type perp  # ETH perps only
```

### Spot Markets
```bash
npx tsx scripts/info/spot.ts                  # Show all spot markets
npx tsx scripts/info/spot.ts --coin PURR     # Show PURR market info
npx tsx scripts/info/spot.ts --balances      # Show your spot balances
npx tsx scripts/info/spot.ts --top 20        # Top 20 by volume
```

### Market Order
```bash
npx tsx scripts/operations/market-order.ts --coin ETH --side buy --size 0.1
npx tsx scripts/operations/market-order.ts --coin BTC --side sell --size 0.01 --slippage 100
```

### Limit Order
```bash
npx tsx scripts/operations/limit-order.ts --coin ETH --side buy --size 1 --price 3000
npx tsx scripts/operations/limit-order.ts --coin SOL --side sell --size 10 --price 200 --tif ALO
```

### Set TP/SL on Existing Position
```bash
# Set take profit at $40, stop loss at $30
npx tsx scripts/operations/set-tpsl.ts --coin HYPE --tp 40 --sl 30

# Set TP at +10% from entry, SL at entry (breakeven)
npx tsx scripts/operations/set-tpsl.ts --coin HYPE --tp +10% --sl entry

# Set only stop loss at -5% from entry
npx tsx scripts/operations/set-tpsl.ts --coin ETH --sl -5%

# Partial position TP/SL
npx tsx scripts/operations/set-tpsl.ts --coin ETH --tp 4000 --sl 3500 --size 0.5
```

### Trigger Order (Standalone TP/SL)
```bash
# Take profit: sell when price rises to $40
npx tsx scripts/operations/trigger-order.ts --coin HYPE --side sell --size 0.5 --trigger 40 --type tp

# Stop loss: sell when price drops to $30
npx tsx scripts/operations/trigger-order.ts --coin HYPE --side sell --size 0.5 --trigger 30 --type sl
```

### Cancel Orders
```bash
npx tsx scripts/operations/cancel.ts --all           # cancel all
npx tsx scripts/operations/cancel.ts --coin ETH      # cancel ETH orders
npx tsx scripts/operations/cancel.ts --oid 123456    # cancel specific order
```

### TWAP (Time-Weighted Average Price)
```bash
# Execute 1 ETH buy over 1 hour (auto-calculates slices)
npx tsx scripts/operations/twap.ts --coin ETH --side buy --size 1 --duration 3600

# Custom intervals with randomization
npx tsx scripts/operations/twap.ts --coin BTC --side sell --size 0.5 --duration 1800 --intervals 6 --randomize 20
```

### Scale In/Out (Grid Orders)
```bash
# Place 5 buy orders ranging 2% below current price
npx tsx scripts/operations/scale.ts --coin ETH --side buy --size 1 --levels 5 --range 2

# Scale out with exponential distribution
npx tsx scripts/operations/scale.ts --coin BTC --side sell --size 0.5 --levels 4 --range 3 --distribution exponential --reduce
```

### Bracket Order (Entry + TP + SL)
```bash
# Long ETH with 3% take profit and 1.5% stop loss
npx tsx scripts/operations/bracket.ts --coin ETH --side buy --size 0.5 --tp 3 --sl 1.5

# Short with limit entry
npx tsx scripts/operations/bracket.ts --coin BTC --side sell --size 0.1 --entry limit --price 100000 --tp 5 --sl 2
```

### Chase Order (Follow Price)
```bash
# Chase buy with ALO orders until filled
npx tsx scripts/operations/chase.ts --coin ETH --side buy --size 0.5 --timeout 300

# Aggressive chase with tight offset
npx tsx scripts/operations/chase.ts --coin SOL --side buy --size 10 --offset 2 --timeout 60
```

## Trading Strategies

### Funding Arbitrage
```bash
# Collect funding on ETH if rate > 25% annualized
npx tsx scripts/strategies/funding-arb.ts --coin ETH --size 5000 --min-funding 25

# Run for 24 hours, check every 30 minutes
npx tsx scripts/strategies/funding-arb.ts --coin BTC --size 10000 --duration 24 --check 30 --dry
```

### Grid Trading
```bash
# ETH grid from $3000-$4000 with 10 levels, 0.1 ETH per level
npx tsx scripts/strategies/grid.ts --coin ETH --lower 3000 --upper 4000 --grids 10 --size 0.1

# Accumulation grid (buys only)
npx tsx scripts/strategies/grid.ts --coin BTC --lower 90000 --upper 100000 --grids 5 --size 0.01 --mode long
```

### DCA (Dollar Cost Averaging)
```bash
# Buy $100 of ETH every hour for 24 hours
npx tsx scripts/strategies/dca.ts --coin ETH --amount 100 --interval 1h --count 24

# Invest $5000 in BTC over 30 days with daily purchases
npx tsx scripts/strategies/dca.ts --coin BTC --total 5000 --interval 1d --count 30
```

### Market Making Spread
```bash
# Market make ETH with 0.1 size, 10bps spread
npx tsx scripts/strategies/mm-spread.ts --coin ETH --size 0.1 --spread 10

# Tighter spread with position limit
npx tsx scripts/strategies/mm-spread.ts --coin BTC --size 0.01 --spread 5 --max-position 0.1
```

### Maker-Only MM (ALO orders)
```bash
# Market make using ALO (post-only) orders - guarantees maker rebates
npx tsx scripts/strategies/mm-maker.ts --coin HYPE --size 1 --offset 1

# Wider offset for volatile assets
npx tsx scripts/strategies/mm-maker.ts --coin ETH --size 0.1 --offset 2 --max-position 0.5
```

## Order Types

### Limit Orders vs Trigger Orders

**Limit Orders** (`limit-order.ts`):
- Execute immediately if price is met
- Rest on the order book until filled or cancelled
- A limit sell BELOW current price fills immediately (taker)
- NOT suitable for stop losses

**Trigger Orders** (`trigger-order.ts`, `set-tpsl.ts`):
- Stay dormant until trigger price is reached
- Only activate when price hits the trigger level
- Proper way to set stop losses and take profits
- Won't fill prematurely

### When to Use Each

| Scenario | Use |
|----------|-----|
| Buy at specific price below market | Limit order |
| Sell at specific price above market | Limit order |
| Stop loss (exit if price drops) | Trigger order (SL) |
| Take profit (exit at target) | Trigger order (TP) |
| Add TP/SL to existing position | `set-tpsl.ts` |