| name | bitflow-hodlmm-deposit |
| description | HODLMM-Primitive. Deposits selected assets into Bitflow HODLMM bins with proof-ready guardrails. |
| metadata | {"author":"macbotmini-eng","author-agent":"Hex Stallion","user-invocable":"false","arguments":"doctor | status | run","entry":"bitflow-hodlmm-deposit/bitflow-hodlmm-deposit.ts","requires":"wallet, signing, settings","tags":"defi, write, mainnet-only, requires-funds, infrastructure, l2"} |
Bitflow HODLMM Deposit
What it does
bitflow-hodlmm-deposit deposits wallet assets into selected Bitflow HODLMM bins on Stacks mainnet. It is a primitive write skill: one action, one HODLMM add-liquidity transaction, and proof-ready JSON output.
The skill is pool-agnostic across Bitflow HODLMM pools that satisfy the expected liquidity-router, token, pool-token, and pool-token-id interface.
Selected bins may already have wallet LP position state or may be first-time wallet position targets. The bin itself must exist in the protocol pool; the skill does not create protocol bins. It supports first-time deposits into valid selected bins and only uses existing wallet position state to adjust the postcondition plan.
Why agents need it
Agents need a reliable HODLMM entry primitive before they can build full economic loops such as Zest-to-HODLMM routing or HODLMM range deployment. Without this primitive, a router can identify that capital should enter HODLMM, but it cannot safely execute the HODLMM deposit leg.
Safety notes
- This is a write skill and can move funds.
- It deposits wallet token balances into HODLMM liquidity bins on mainnet.
- It requires explicit
--confirm=DEPOSIT before broadcast.
- It blocks unsupported pool/router/token interfaces before broadcast.
- It validates one-sided and two-sided deposit rules for the selected bins.
- It supports both topping up existing wallet bin positions and initializing wallet position state in valid selected protocol bins.
- It uses active-bin tolerance, minimum DLP protection, liquidity-fee bounds, balance checks, pending-transaction checks, and deny-mode postconditions where expressible.
- It is not a withdrawal, recentering, DCA, keeper order, swap, APY router, or cross-protocol workflow.
Commands
doctor
Checks environment, selected pool readiness, router interface, token contracts, token balances, STX gas reserve, and pending transaction depth. Safe to run anytime.
bun run bitflow-hodlmm-deposit/bitflow-hodlmm-deposit.ts doctor --wallet <stacks-address> --pool-id <pool-id>
status
Builds a read-only deposit preview. It reports selected bins, active-bin offsets, token amounts, minimum DLP, fee bounds, wallet balance requirements, active-bin tolerance, and postcondition plan.
bun run bitflow-hodlmm-deposit/bitflow-hodlmm-deposit.ts status --wallet <stacks-address> --pool-id <pool-id> --amount-x <amount> --amount-y <amount>
Useful selection options:
bun run bitflow-hodlmm-deposit/bitflow-hodlmm-deposit.ts status --wallet <stacks-address> --pool-id <pool-id> --offsets -1,0,1 --amount-x <amount> --amount-y <amount>
bun run bitflow-hodlmm-deposit/bitflow-hodlmm-deposit.ts status --wallet <stacks-address> --pool-id <pool-id> --range -2:2 --amount-x <amount> --amount-y <amount>
bun run bitflow-hodlmm-deposit/bitflow-hodlmm-deposit.ts status --wallet <stacks-address> --pool-id <pool-id> --plan-json '[{"offset":0,"xAmount":"1000","yAmount":"1000"}]'
run
Rechecks all live state, builds the HODLMM add-liquidity transaction, broadcasts only after explicit confirmation, and returns proof JSON.
bun run bitflow-hodlmm-deposit/bitflow-hodlmm-deposit.ts run --wallet <stacks-address> --pool-id <pool-id> --amount-x <amount> --amount-y <amount> --confirm=DEPOSIT
Without --confirm=DEPOSIT, run refuses before broadcast.
Agent selection surface
The skill exposes the same kind of strategy surface as the withdrawal primitive, with deposit-specific amount controls.
| Option | Required | Purpose |
|---|
--wallet <stacks-address> | Yes | Wallet that owns the tokens and signs the write. |
--pool-id <pool-id> | Yes | HODLMM pool to inspect and deposit into. |
--amount-x <amount> | Conditional | Token X amount to deposit in base units. |
--amount-y <amount> | Conditional | Token Y amount to deposit in base units. |
--bin-id <id> | No | Deposit into one absolute bin. |
--bin-ids <ids> | No | Deposit into a comma-separated selected set of bins. |
--offsets <offsets> | No | Deposit into active-bin-relative offsets. |
--range <start:end> | No | Deposit across an active-bin-relative range. |
--distribution <mode> | No | equal or explicit. |
--plan-json <json> | No | Explicit per-bin amounts for advanced agent composition. |
--slippage-bps <bps> | No | Minimum DLP and fee-bound tolerance. |
--active-bin-max-deviation <bins> | No | Abort if active bin drifts too far before broadcast. |
--min-gas-reserve-ustx <uSTX> | No | Minimum STX reserve to preserve after deposit and fee. |
--confirm DEPOSIT | Run only | Explicit write confirmation. |
--wait-seconds <seconds> | No | Inclusion/status wait window. |
Exactly one selector may be used at a time: --plan-json, --bin-id, --bin-ids, --offsets, or --range. If no selector is provided, the default is the current active bin. At least one nonzero token amount is required through --amount-x, --amount-y, or --plan-json.
Output contract
All outputs are JSON to stdout.
Success:
{ "status": "success", "action": "status", "data": {}, "error": null }
Blocked:
{
"status": "blocked",
"action": "run",
"data": {},
"error": {
"code": "CONFIRMATION_REQUIRED",
"message": "This write skill requires explicit confirmation.",
"next": "Re-run with --confirm=DEPOSIT."
}
}
Fatal error:
{ "error": "descriptive message" }
Known constraints
- Mainnet only.
- The selected pool must be a live Bitflow HODLMM pool with the shared
dlmm-liquidity-router-v-1-1 interface.
- The proof path targets
add-relative-liquidity-same-multi.
- The default plan deposits into the current active bin if no bin selector is provided.
- The default active-bin deviation is
0, meaning broadcast uses an exact active-bin match unless --active-bin-max-deviation is increased.
- Below-active bins accept only token Y; above-active bins accept only token X; active-bin deposits may be one-sided or two-sided.
- The skill prefers active/restored AIBTC wallet sessions before fallback signer inputs. A locked wallet returns JSON guidance rather than prompting interactively.
- Nonce serialization across multiple write legs belongs in a composed skill or workflow guide, not inside this primitive.
Origin
Winner of AIBTC x Bitflow Skills Pay the Bills competition.
Original author: @macbotmini-eng
Competition PR: https://github.com/BitflowFinance/bff-skills/pull/556
Post-condition correctness update (2026-07-15 field audit F-7)
Per-bin position-NFT post-conditions are keyed on actual NFT ownership (Hiro NFT holdings), not only userLiquidity > 0. Root cause: the pool's tag-pool-token-id burns and re-mints the bin NFT on every mint/burn where the wallet already owns it — and ownership persists at zero liquidity, so re-entering a previously fully-withdrawn bin moves the NFT even though the positions endpoint shows no liquidity. Without the PC, such a deposit aborts in Deny mode and burns the fee.
