aibtcdev/bitflow-limit-order

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.

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

set

Create a new limit order.

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.

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.

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.

# 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.

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

Output contract

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

// 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