Bitflow DEX on Stacks — token swaps with aggregated liquidity, market ticker data, swap routing, price impact analysis, and Keeper automation for scheduled orders. All operations are mainnet-only. No API key required (500 req/min public rate limit). Write operations require an unlocked wallet.
Provides DEX operations on the Bitflow aggregated liquidity protocol:
All Bitflow operations are mainnet-only. No API key is required — the Bitflow SDK works with public endpoints at 500 requests/minute per IP. For higher rate limits, contact [email protected].
Write operations (swap, create-order) require an unlocked wallet (use bun run wallet/wallet.ts unlock first).
bun run bitflow/bitflow.ts <subcommand> [options]
Get market ticker data from Bitflow DEX. Returns price, volume, and liquidity data for all trading pairs. Optionally filter by a specific pair.
bun run bitflow/bitflow.ts get-ticker [--base-currency <contractId>] [--target-currency <contractId>]
Options:
--base-currency (optional) — Filter by base currency contract ID--target-currency (optional) — Filter by target currency contract IDOutput:
{
"network": "mainnet",
"pairCount": 42,
"tickers": [
{
"ticker_id": "token-stx_token-sbtc",
"base_currency": "token-stx",
"target_currency": "token-sbtc",
"last_price": "0.000012",
"base_volume": "5000000",
"target_volume": "60",
"bid": "0.000011",
"ask": "0.000013",
"high": "0.000014",
"low": "0.000010",
"liquidity_in_usd": "1500000"
}
]
}
Get all available tokens for swapping on Bitflow.
bun run bitflow/bitflow.ts get-tokens
Output:
{
"network": "mainnet",
"tokenCount": 15,
"tokens": [
{
"id": "token-stx",
"name": "Stacks",
"symbol": "STX",
"contractId": "token-stx",
"decimals": 6
}
]
}
Get possible swap target tokens for a given input token. Returns all tokens that can be received when swapping from the specified token.
bun run bitflow/bitflow.ts get-swap-targets --token-id <contractId>
Options:
--token-id (required) — The input token ID (contract address)Output:
{
"network": "mainnet",
"inputToken": "token-stx",
"targetCount": 8,
"targets": ["token-sbtc", "token-aeusdc", "token-alex"]
}
Get a swap quote from Bitflow DEX. Returns expected output amount, best route, and price impact analysis.
bun run bitflow/bitflow.ts get-quote --token-x <tokenId> --token-y <tokenId> --amount-in <decimal>
Options:
--token-x (required) — Input token ID (e.g. token-stx, token-sbtc)--token-y (required) — Output token ID (e.g. token-sbtc, token-aeusdc)--amount-in (required) — Amount of input token in human-readable decimal (e.g. 0.00015 for 15,000 sats sBTC, 21.0 for 21 STX). The SDK auto-scales by 10^decimals internally.Output:
{
"network": "mainnet",
"quote": {
"tokenIn": "token-stx",
"tokenOut": "token-sbtc",
"amountIn": "1.0",
"expectedAmountOut": "0.0000036",
"route": ["token-stx", "token-sbtc"]
},
"priceImpact": {
"combinedImpact": 0.0023,
"combinedImpactPct": "0.23%",
"severity": "low",
"hops": [...],
"totalFeeBps": 30
}
}
Get all possible swap routes between two tokens, including multi-hop routes through intermediate tokens.
bun run bitflow/bitflow.ts get-routes --token-x <tokenId> --token-y <tokenId>
Options:
--token-x (required) — Input token ID--token-y (required) — Output token IDOutput:
{
"network": "mainnet",
"tokenX": "token-stx",
"tokenY": "token-sbtc",
"routeCount": 3,
"routes": [
{
"tokenPath": ["token-stx", "token-sbtc"],
"dexPath": ["xyk-pool-v1"]
}
]
}
Execute a token swap on Bitflow DEX. Automatically finds the best route across all pools. Includes a high-impact safety gate — swaps with >5% price impact require --confirm-high-impact. Requires an unlocked wallet.
bun run bitflow/bitflow.ts swap \
--token-x <tokenId> --token-y <tokenId> --amount-in <decimal> \
[--slippage-tolerance <decimal>] [--fee <value>] [--confirm-high-impact]
Options:
--token-x (required) — Input token ID (contract address)--token-y (required) — Output token ID (contract address)--amount-in (required) — Amount of input token in human-readable decimal (e.g. 0.00015 for 15,000 sats sBTC, 21.0 for 21 STX). The SDK auto-scales by 10^decimals internally.--slippage-tolerance (optional) — Slippage tolerance as decimal (default 0.01 = 1%)--fee (optional) — Fee: low | medium | high preset or micro-STX amount. If omitted, auto-estimated.--confirm-high-impact (optional) — Required to execute swaps with price impact above 5%Output:
{
"success": true,
"txid": "abc123...",
"swap": {
"tokenIn": "token-stx",
"tokenOut": "token-sbtc",
"amountIn": "1.0",
"slippageTolerance": 0.01,
"priceImpact": { "combinedImpactPct": "0.23%", "severity": "low" }
},
"network": "mainnet",
"explorerUrl": "https://explorer.hiro.so/txid/abc123...?chain=mainnet"
}
Get or create a Bitflow Keeper contract for automated swaps.
bun run bitflow/bitflow.ts get-keeper-contract [--address <stacksAddress>]
Options:
--address (optional) — Stacks address (uses wallet if not specified)Output:
{
"network": "mainnet",
"address": "SP2...",
"contractIdentifier": "SP2...keeper-v1",
"status": "active"
}
Create an automated swap order via Bitflow Keeper. Creates a pending order that will be executed by the Keeper service.
bun run bitflow/bitflow.ts create-order \
--contract-identifier <id> --action-type <type> \
--funding-tokens '{"token-stx":"1000000"}' --action-amount <units> \
[--min-received-amount <units>] [--auto-adjust]
Options:
--contract-identifier (required) — Keeper contract identifier--action-type (required) — Action type (e.g., SWAP_XYK_SWAP_HELPER)--funding-tokens (required) — JSON map of token IDs to amounts for funding--action-amount (required) — Amount for the action--min-received-amount (optional) — Minimum amount to receive (slippage protection)--auto-adjust (optional) — Auto-adjust minimum received based on market (default true)Output:
{
"success": true,
"network": "mainnet",
"orderId": "order-123",
"status": "pending",
"order": {
"contractIdentifier": "SP2...keeper-v1",
"actionType": "SWAP_XYK_SWAP_HELPER",
"fundingTokens": { "token-stx": "1000000" },
"actionAmount": "1000000"
}
}
Get details of a Bitflow Keeper order.
bun run bitflow/bitflow.ts get-order --order-id <id>
Options:
--order-id (required) — The order ID to retrieveOutput:
{
"network": "mainnet",
"order": {
"orderId": "order-123",
"status": "completed",
"actionType": "SWAP_XYK_SWAP_HELPER",
"actionAmount": "1000000"
}
}
Cancel a Bitflow Keeper order before execution.
bun run bitflow/bitflow.ts cancel-order --order-id <id>
Options:
--order-id (required) — The order ID to cancelOutput:
{
"network": "mainnet",
"orderId": "order-123",
"cancelled": true
}
Get Bitflow Keeper user info and orders. Retrieves user's keeper contracts and order history.
bun run bitflow/bitflow.ts get-keeper-user [--address <stacksAddress>]
Options:
--address (optional) — Stacks address (uses wallet if not specified)Output:
{
"network": "mainnet",
"userInfo": {
"stacksAddress": "SP2...",
"contracts": [{ "identifier": "SP2...keeper-v1", "status": "active" }],
"orders": [{ "orderId": "order-123", "status": "completed" }]
}
}
BITFLOW_API_KEY and BITFLOW_API_HOST environment variables.--confirm-high-impact flag as a safety measure.get-keeper-contract to get started.bun run wallet/wallet.ts unlock first).