Plan a position from assets the wallet holds
plan_ladderPlans a ladder, a deposit spread over up to 40 narrow one-sided ranges (rungs) of one pool, from assets the wallet already holds, and returns the unsigned transactions. Use when the wallet holds the token, the quote asset, or both; with only ETH or USDG, prefer plan_build, which buys the missing side and builds in one transaction. Not for an order at one price (plan_limit_order). Rungs under the price hold the quote and buy as it falls; rungs over it hold the token and sell as it rises; each earns the pool's swap fee when traded through. Returns: transactions[] (to, data, value in wei, gas), check (simulated, ok, failedStep, reason, ethNeeded, ethHeld), sendWithin, ifItReverts, slippagePct, rungs (the band as laid), fees (0.25% of what goes in; then 5% of the fees earned, 3.5% for a holder of 100,000 LOOM; every cut paid as USDG). Behavior: read-only on our side; nothing is signed or sent. The plan is laid out from the chain at this block and simulated from the owner; send it within check.sendWithin, and plan again rather than resend one that reverted. Costs quota units (agent_quota). Errors: refused with a reason when the band holds no rung, the pool has no money side, the amounts are zero, or the token is flagged.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| pool | No | A pool id from ladder_pools. Left out: the token's default pool. | |
| owner | Yes | The wallet that signs, sends, and owns the ladder. | |
| rungs | No | How many rungs across the band, 1 to 40; default 40. | |
| shape | No | Where the band puts the most: spot (even), curve (near the price), bidask (at the edges), hybrid (half spot, half bidask), custom (weights). Default bidask. | |
| split | No | With one asset only: swap part of it for the other in the same pool and build the whole band, in one transaction. | |
| token | Yes | The token's address. | |
| copyOf | No | The id of a ladder on the current contract this one copies: its owner is paid 0.1% while it stays open in the same pair. | |
| lowPct | Yes | The band's bottom, in percent from the current price: negative for under it (for example -30). | |
| highPct | Yes | The band's top, in percent from the current price (for example 40). | |
| newPool | No | From plan_open_pool's `then`: a pool being opened in the same plan, so the ladder is laid against its key and opening price. No split in it; both amounts, or one for a one-sided ladder. | |
| weights | No | shape custom only: a relative height per rung, low price to high, any scale; stretched over the rungs built. | |
| referrer | No | The wallet that referred the owner: paid 0.1% of what goes in, out of the opening fee; kept by the contract from the owner's first ladder on. | |
| fullRange | No | One position across every price instead of a band. Never out of range, earns the least per dollar. Needs both amounts, or one with split: true; lowPct and highPct are ignored. | |
| payWithEth | No | For a pool quoted in WETH: pay in plain ETH, wrapped inside the same transaction, nothing to approve. Default: whenever the wallet holds less WETH than amountQuote. | |
| amountQuote | No | How much of the quote asset to put in, as a decimal string. Builds the rungs under the price. | |
| amountToken | No | How much of the token to put in, as a decimal string. Builds the rungs over the price. | |
| slippagePct | No | Room for the price to move before the transaction is mined, in percent. Left out: 2% on a calm pool, more on one that has been moving, at most 10%. | |
| startMarketCapUsd | No | For a token that has never traded, built in the pool plan_open_pool is opening (newPool): the market cap it opens at, the same as given there. |