# Cross Venue Router

> 🔀 Cross-Venue Router

- Skill: `starchild-ai-agent/cross-venue-router` (Agent Skill)
- Install (CLI): `npx skillmds@latest add starchild-ai-agent/cross-venue-router`
- Raw SKILL.md: https://api.skillmd.com/api/skills/starchild-ai-agent/cross-venue-router/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: starchild-ai-agent (https://skillmd.com/u/starchild-ai-agent)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/starchild-ai-agent/cross-venue-router

---


# 🔀 Cross-Venue Router

**What:** A Starchild skill that makes Hyperliquid and Orderly act as one venue. Routes trades to best execution, runs persistent strategies in the background, monitors risk 24/7, and gives a unified portfolio view.

**Why it exists:** Current skills are single-venue and request-response. This skill adds three things that didn't exist:
1. **Cross-venue routing** — compare both venues, execute where cost is lowest
2. **Persistent strategies** — DCA, TWAP, grid, conditionals that keep running after conversation ends
3. **Always-on risk** — monitors positions across venues, alerts before problems

## Who it's for

Traders using Starchild who have accounts on both Hyperliquid and Orderly and want:
- Best execution without manually checking both venues
- Automated strategies that survive session restarts
- Portfolio-level risk awareness across venues

---

## 1. Routing Engine

### How routing works

When user says "buy 0.5 BTC":

1. **Pull orderbooks** from both venues simultaneously
   - `hl_orderbook(coin="BTC")` + `woo_orderbook(coin="BTC")`
2. **Walk the book** — simulate VWAP fill at requested size
3. **Add fees** to get true cost per venue
4. **Recommend** the cheaper venue (or split if V2)

### Fee reference (fallback if API unavailable)

| Venue | Maker | Taker |
|-------|-------|-------|
| Hyperliquid | 0.010% | 0.035% |
| Orderly | 0.020% | 0.050% |

Always try to pull live fees first (`hl_account` meta, Orderly fee endpoint).

### Cost formula

```
total_cost = vwap_fill_price × size × (1 + taker_fee_rate)
slippage = (vwap_fill_price - mid_price) / mid_price
effective_cost = slippage + fee_rate
```

Compare `effective_cost` across venues. Route to lowest.

### Output format

```
🔀 Routing: BUY 0.5 BTC

         Hyperliquid    Orderly
Mid:     $69,225        $69,325
VWAP:    $69,226        $69,340
Fee:     0.035%         0.050%
Cost:    $12.36         $19.52
Depth:   32.4 BTC       1.17 BTC

→ Route to Hyperliquid (37% cheaper)
Execute? [y/n]
```

Wait for user confirmation before executing. Never auto-execute a routed trade.

## 2. Persistent Strategies

Strategies use `schedule_task` for persistence. Each strategy stores state in `memory_store` under topic `strategy-{id}`.

### DCA (Dollar-Cost Average)
- **Trigger:** "DCA $100 into ETH every 4 hours on best venue"
- **Implementation:** `schedule_task(schedule="every 4 hours", task="...")` where task includes routing logic
- **State:** total invested, avg entry, fills count, venue breakdown
- **Stop conditions:** total budget hit, user cancels, price outside bounds

### TWAP (Time-Weighted Average Price)
- **Trigger:** "Buy 2 ETH over the next 6 hours"
- **Implementation:** Split into N slices (e.g., 12 × 0.167 ETH every 30 min), each slice routed independently
- **State:** slices remaining, fills so far, avg price achieved vs benchmark

### Grid
- **Trigger:** "Run a grid on ETH between $3,400–$3,800, 10 levels"
- **Implementation:** Place limit orders at grid levels. On fill, place opposite order one level away.
- **Venue selection:** Place on venue with better maker fees (usually HL at 0.01%)
- **State:** grid levels, active orders, realized PnL, fills per level

### Trailing Stop
- **Trigger:** "Trail my BTC long with 3% stop"
- **Implementation:** Poll every 5 min, update stop-loss price as price rises
- **State:** current trail price, high-water mark, trigger distance

### TP Ladder
- **Trigger:** "Take profit on my ETH: 25% at $4k, 50% at $4.5k, 25% at $5k"
- **Implementation:** Place limit sells at each level, or use `hl_tpsl_order` / Orderly TP
- **State:** levels, fill status per level

### Conditional Entry
- **Trigger:** "Buy ETH if BTC drops below $65k"
- **Implementation:** `schedule_task(schedule="every 15 minutes", task="check BTC price, if < 65000 then route buy ETH")` 
- **Self-destruct:** Cancel schedule after trigger fires or after user-set expiry

### Strategy management

All active strategies stored in memory topic `active-strategies`. Commands:
- "Show my strategies" → list all active with status + PnL
- "Pause DCA" → cancel scheduled task, preserve state
- "Resume DCA" → recreate schedule from saved state
- "Kill all strategies" → cancel all strategy-related scheduled tasks

### Task naming convention

All strategy tasks use label format: `strategy-{type}-{coin}-{timestamp}`
Example: `strategy-dca-ETH-1710864000`


## 3. Risk Monitoring

### Always-on monitor

Set up via: "Monitor my positions" or "Turn on risk alerts"

**Implementation:** `schedule_task(schedule="every 30 minutes", task="...")`

The monitor checks:

| Check | Threshold | Action |
|-------|-----------|--------|
| Liquidation buffer | <15% margin remaining | ⚠️ Alert user |
| Liquidation buffer | <8% margin remaining | 🚨 URGENT alert + suggest reduce |
| Notional exposure | >80% of account value | Warn over-leveraged |
| Single-asset concentration | >60% of portfolio | Warn concentration risk |
| Funding bleed | Paying >0.05%/8h cumulative | Suggest venue migration |
| Venue health | API errors or latency spike | Alert + pause strategies |

### Cross-venue aggregation

```
Portfolio snapshot:
├── Hyperliquid
│   ├── BTC-PERP: +0.5 long @ $68,200 (PnL: +$512)
│   ├── ETH-PERP: +3.0 long @ $3,450 (PnL: -$89)
│   └── Margin used: $4,200 / $12,000 (35%)
├── Orderly
│   ├── SOL-PERP: +50 long @ $142 (PnL: +$200)
│   └── Margin used: $1,800 / $5,000 (36%)
└── TOTAL
    ├── Net exposure: $58,750 long
    ├── Total margin: $6,000 / $17,000 (35%)
    └── Effective leverage: 3.5x
```

### Position migration

If funding rate diverges significantly between venues:
- "Your ETH long on HL is paying 0.08%/8h. Orderly charges 0.02%/8h. Want me to migrate?"
- Migration = close on expensive venue + open on cheap venue, routed atomically (close first, then open)

### Funding arbitrage

When same asset has divergent funding across venues (>0.01%/8h delta):
- Alert user to opportunity
- If user opts in: go long on negative-funding venue, short on positive-funding venue
- Monitor convergence, suggest exit when spread normalizes

## 4. Portfolio View

**Trigger:** "Show my portfolio" / "What's my exposure?"

Pulls from both venues simultaneously:
- `hl_account()` + `hl_balances()` for Hyperliquid
- `woo_positions()` + `woo_holdings()` for Orderly

Presents unified view:
- Positions by asset (merged across venues)
- Total PnL (realized + unrealized)
- Margin utilization per venue
- Net directional exposure
- Funding costs (daily/weekly projection)

## 5. Safety Rules

1. **No auto-execution on routed trades.** Always show comparison and wait for confirmation.
2. **Size sanity check.** If order is >25% of account equity, warn before proceeding.
3. **Strategy budget caps.** Every persistent strategy must have a max budget. No infinite DCA.
4. **Fail-safe on API errors.** If either venue API is unreachable during strategy execution, skip that slice and alert user. Do NOT blindly route to the other venue.
5. **Kill switch.** "Stop everything" cancels all scheduled strategies immediately.
6. **No margin increase without asking.** Never auto-increase leverage to fill an order.
7. **Liquidation guard.** Refuse to open new positions if either venue margin utilization >85%.
8. **Venue down handling.** If a venue is unreachable, all strategies on that venue pause automatically. Resume when healthy.

## 6. UX Flows

### First-time user
```
User: "Buy some ETH"
Agent: I can route this across Hyperliquid and Orderly for best execution.
       How much ETH? And market order or limit?
User: "0.5 ETH, market"
Agent: [runs routing comparison]
       HL: $1,732.50 total cost (0.02% slippage + 0.035% fee)
       Orderly: $1,738.20 total cost (0.05% slippage + 0.050% fee)
       → Hyperliquid is $5.70 cheaper. Execute there?
User: "yes"
Agent: [executes on HL, confirms fill]
       Filled 0.5 ETH @ $3,464.10 on Hyperliquid. Fee: $0.61.
```

### Setting up DCA
```
User: "DCA $500 into BTC weekly"
Agent: Got it. I'll buy ~$500 BTC every week, routed to whichever
       venue is cheapest at execution time.
       Budget cap? (I'll stop after this amount)
User: "$10,000 total"
Agent: Running: $500/week BTC DCA, best-venue routing, $10k cap.
       That's 20 weeks. I'll send you a summary after each buy.
       Say "show my strategies" anytime or "stop DCA" to kill it.
```

### Risk alert (push)
```
Agent: ⚠️ Risk Alert — ETH position on Hyperliquid
       Your margin buffer is at 12% (threshold: 15%).
       ETH is down 8% in the last 4 hours.
       Options:
       1. Reduce position by 30% (brings buffer to ~25%)
       2. Add $500 margin
       3. Move to Orderly (lower maintenance margin)
       4. Do nothing (I'll alert again at 8%)
```

## 7. Build Sequence

| Week | Deliverable |
|------|-------------|
| 1 | Routing engine: orderbook pull, VWAP walk, fee calc, comparison output |
| 2 | DCA + TWAP strategies with schedule_task persistence |
| 3 | Risk monitor: margin checks, liquidation alerts, kill switch |
| 4 | Portfolio view: cross-venue aggregation, funding projection |
| 5 | Grid + trailing stop + TP ladder strategies |
| 6 | Conditional triggers, funding arb detection |
| 7 | Position migration, venue health monitoring |
| 8 | Polish: error handling, edge cases, UX refinement |

### Supported assets (V1)
BTC, ETH, SOL — expand based on demand.

### Future venues (V2+)
Architecture is venue-agnostic. Adding a venue means:
1. Orderbook pull function
2. Order execution function
3. Position/balance query function
4. Fee schedule

dYdX, GMX, Vertex are natural next candidates.