aibtcdev/bitflow-hodlmm-deposit

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