bitflow-limit-order

What this skill does

# bitflow-limit-order

Agent-powered limit orders on Bitflow. Bitflow has no native limit-order support — the agent IS the order engine.

## What it does

Sets price targets on Bitflow HODLMM pools, polls active bin mid-prices on each heartbeat, and executes swaps autonomously when conditions are met. The agent maintains a local order book (`~/.aibtc/limit-orders/orders.json`), checks prices every 5 minutes via `run`, and fills orders that hit their target.

**Core flow:**
1. `set` — User creates a limit order with pair, side, price, amount, slippage, and expiry
2. `run` — Called every heartbeat: loads active orders, fetches pool prices, executes triggered swaps via BitflowSDK, expires stale orders
3. `list` / `cancel` — Manage the order book

```
User/Agent ──set──▶ Order File ──run──▶ Price Check ──trigger──▶ BitflowSDK Swap
                    (~/.aibtc/          (HODLMM active        (best-route tx via SDK;
                     limit-orders)       bin mid-price)        not necessarily HODLMM)
```

## Why agents need it

- **Agent-native limit orders** — Bitflow's native keeper handles orders server-side; this skill gives agents a self-hosted, fully configurable alternative with no third-party dependency
- Every trader's #1 feature request on any DEX — high-leverage primitive
- Enables autonomous trading strategies: set-and-forget price targets
- HODLMM active bin provides an on-chain price oracle — no external feeds needed
- Write skill (executes actual swaps) — required for daily prize eligibility

## Commands

### `doctor`

Verify wallet, Bitflow API access, price feed, and order storage health.

```bash
bun run bitflow-limit-order/bitflow-limit-order.ts doctor
```

### `set`

Create a new limit order.

```bash
bun run bitflow-limit-order/bitflow-limit-order.ts set \
  --pair STX-sBTC \
  --side buy \
  --price 29000 \
  --amount 0.001 \
  --slippage 1 \
  --expires 24h
```

| Flag | Required | Default | Description |
|------|----------|---------|-------------|
| `--pair` | Yes | — | Trading pair (e.g., `STX-sBTC`) |
| `--side` | Yes | — | `buy` or `sell` |
| `--price` | Yes | — | Target price (HODLMM bin price units) |
| `--amount` | Yes | — | Amount of input token |
| `--slippage` | No | 1% | Max slippage percent (cap: 5%) |
| `--expires` | No | 24h | Expiry duration (e.g., `1h`, `24h`, `7d`) |

### `list`

Show all orders with their current status, or read the JSONL event-log audit trail.

```bash
bun run bitflow-limit-order/bitflow-limit-order.ts list
bun run bitflow-limit-order/bitflow-limit-order.ts list --status active
bun run bitflow-limit-order/bitflow-limit-order.ts list --events
bun run bitflow-limit-order/bitflow-limit-order.ts list --events --order-id 3
```

| Flag | Description |
|------|-------------|
| `--status <s>` | Filter orders by status |
| `--events` | Read `~/.aibtc/limit-orders/events.jsonl` instead of orders |
| `--order-id <n>` | With `--events`, restrict to one order |

### `cancel <ID>`

Cancel a pending order by ID.

```bash
bun run bitflow-limit-order/bitflow-limit-order.ts cancel 3
```

### `run`

Check all active orders against live pool prices. Execute any that trigger. Defaults to one-shot (single cycle, exits) — pass `--watch <interval>` to run as an in-process heartbeat loop.

```bash
# One-shot (called by external scheduler)
bun run bitflow-limit-order/bitflow-limit-order.ts run --confirm --wallet-password <PW>

# In-process loop, every 30s, with 2-tick anti-wick filter
bun run bitflow-limit-order/bitflow-limit-order.ts run --confirm --watch 30s --confirm-ticks 2
```

| Flag | Description |
|------|-------------|
| `--confirm` | Execute swaps on-chain. Without it, dry-run only. |
| `--watch <interval>` | Run in-process heartbeat loop (`5s`, `30s`, `1m`, `5m`, max `1h`). Without it, runs once and exits. |
| `--confirm-ticks <n>` | Anti-wick guard: require N consecutive triggering cycles before firing. Default `2`. Watch mode only. |
| `--wallet-password <pw>` | Keystore password (or set `AIBTC_WALLET_PASSWORD`, or use `STACKS_PRIVATE_KEY`). |

**Watch-mode output:** newline-delimited JSON. Each cycle emits one `watch-cycle` JSON line. SIGINT/SIGTERM trigger a final `watch-summary` line before exit. Each line is independently a valid JSON object.

**Anti-wick rationale:** thin L2 liquidity can briefly spike for a single block. Requiring `N` consecutive cycles where `currentPrice` crosses `targetPrice` before firing prevents getting wicked at 3am. The tick counter is in-memory, per-process — it resets on restart and on the first cycle the order stops triggering. Only active under `--watch` (one-shot has no history to check).

**Event log:** every meaningful action (`triggered`, `pending_trigger`, `skipped`, `filled`, `expired`, `error`) appends one JSON line to `~/.aibtc/limit-orders/events.jsonl`. File rotates to `events.jsonl.1` at 10 MB. Read back with `list --events`.

### `install-packs`

Install required npm dependencies.

```bash
bun run bitflow-limit-order/bitflow-limit-order.ts install-packs
```

## Output contract

All output is JSON to stdout. Logs go to stderr.

```json
// set — order created
{ "status": "success", "action": "set", "data": { "orderId": 1, "pair": "STX-sBTC", "side": "buy", "targetPrice": 29000, "amount": 0.001, "slippage": 1, "expires": "2026-04-13T12:00:00Z" }, "error": null }

// run — order triggered
{ "status": "success", "action": "execute", "data": { "orderId": 1, "fillPrice": 29800, "txId": "0x8f3a...", "amount": 0.001, "dryRun": false }, "error": null }

// run — no triggers
{ "status": "success", "action": "check", "data": { "checked": 3, "triggered": 0, "closest": { "orderId": 2, "distance": "2.1%" } }, "error": null }

// error
{ "status": "error", "action": "set", "data": null, "error": "Pool STX-FAKE not found" }

// error (swap failure)
{ "status": "error", "action": "execute", "data": null, "error": "Order #1 swap failed: Broadcast failed: ..." }
```

## Safety notes

| Guard | Default | Configurable |
|-------|---------|-------------|
| Max order size | 2000 STX / 0.005 sBTC | No (hardcoded floor) |
| Slippage cap | 1% default | Yes, via `--slippage` (max 5%) |
| Mandatory expiry | 24h | Yes, via `--expires` (max 7d) |
| Max active orders | 10 | No (hardcoded) |
| Balance check | Before every execution | Always enforced |
| One fill per cycle | Sequential processing | Always enforced |
| Silent retry | Never — errors surface immediately | Always enforced |
| Confirmation | `--confirm` required for writes | Always enforced |

**Refusal conditions:**
- Insufficient wallet balance (STX or sBTC, including STX-for-fee on sBTC orders) → order skipped this cycle with `lastSkipReason`, stays active for retry
- Balance API failure → order skipped this cycle (never proceeds with unknown balance)
- Wallet decryption failure → cycle aborts, no further orders processed this cycle
- Slippage exceeds threshold → swap aborted
- Pool inactive or not found → order rejected at `set` time
- Nonce out of sequence → broadcast fails safely
- Order expired → automatically marked `expired` on next `run`

## Price source

HODLMM pool active bin mid-price via Bitflow API:
- Pools: `https://bff.bitflowapis.finance/api/quotes/v1/pools`
- Active bin: `https://bff.bitflowapis.finance/api/quotes/v1/bins/{poolId}/active`

**Never use `api.bitflow.finance`** (dead endpoint).

## Dependencies

- `commander` — CLI argument parsing
- `@bitflowlabs/core-sdk` — Bitflow swap routing and execution
- `@stacks/transactions` — Transaction construction and broadcast
- `@stacks/network` — Stacks mainnet config
- `@stacks/wallet-sdk` — Wallet derivation
- `@stacks/encryption` — Keystore decryption

## Origin

Winner of AIBTC x Bitflow Skills Pay the Bills competition.
Original author: @ClankOS
Competition PR: https://github.com/BitflowFinance/bff-skills/pull/277