Skip to main content

The sells and buys that bring your strategy positions to its book, with no quotes

POST/signals-orders/rebalance/plan

Returns the orders that move your wallet's positions in the strategy's names to the strategy's current book: the Solana wallet, or eth_wallet on BNB Smart Chain with chain: "bnb". Nothing is quoted and nothing expires, so this is the default flow: show the orders, then call POST /quote/sell (send shares as amount_shares) or POST /quote/buy (send notional_usdc as amount_usdc) per order when the signer is ready, and submit each quote through POST /trade/submit unchanged.

Quoting each order. With the same wallet and a fresh proof,

  • a sell is POST /quote/sell with { "ticker": <ticker>, "amount_shares": <shares>, "chain": "sol", "sol_wallet": <sol_wallet>, "ownership_proof": <proof>, "max_slippage_bps": <bps> }
  • a buy is POST /quote/buy with { "ticker": <ticker>, "amount_usdc": <notional_usdc>, "chain": "sol", "sol_wallet": <sol_wallet>, "ownership_proof": <proof>, "max_slippage_bps": <bps> }.

Send no protocol: the plan reads every Solana venue. To submit several Solana quotes in one request, send them together through POST /trade/submit/batch.

With chain: "bnb". Quote each order with "chain": "bnb", "protocol": ["ondo","xstocks"], eth_wallet in place of sol_wallet, and a fresh proof carrying its eth_signature; the plan reads ondo and xStocks only, and an unpinned bnb quote can route to bStocks. Submit each quote on its own POST /trade/submit, never as a batch. One call orders at most 25 names, with no quote-call cap.

Without amount_usdc the book's cash weight is sold on every call. nav is then only what you hold in scope, and the targets sum to the book's deployed weight of it, so a book that is 10% cash sells about 10% of your held value each time it is called without amount_usdc. Carry funding.next_amount_usdc into the next call to keep that cash in nav.

Buy-in. To buy into a strategy from cash, call with amount_usdc on a wallet that holds none of its names: every order is a buy, sized by its book weight of amount_usdc. One call orders at most 25 names and, on Solana, 30 upstream quote calls (a buy costs one per Solana venue it can buy on), so a book of 20 names on two venues each takes more than one round: submit the buys, wait for them to settle, and call again with funding.next_amount_usdc.

Scoped nav. The plan sizes every name against nav_usdc: the value of what you hold in the book's names (plus any tickers you add), plus amount_usdc. Each name's target is its book weight times that nav; the book's unweighted remainder stays as USDC and is never ordered. A tickers name outside the book has weight zero and is sold in full. Holdings outside the scope and the rest of your USDC are never touched. Every sol venue counts, so protocol is not accepted here.

Funding. Buys spend only amount_usdc, never the rest of the wallet's USDC, and are never larger than it: when the buys need more, each is scaled down pro rata and rounded down (funding.buys_scaled). Scaling is pro rata and a scaled buy under $1 is skipped, so a small amount_usdc spread over many buys (for example under $1 per buy when they are equal) can deploy nothing that round; the whole shortfall stays in funding.buys_deferred_usdc.

A buy that cannot be funded is skipped as awaiting_sell_proceeds when the plan also sells, or insufficient_balance when it does not. A rebalance that only reshuffles what you hold is therefore two rounds:

  1. Call with amount_usdc omitted. Submit the sells.
  2. Once they settle, call again with amount_usdc set to the smaller of funding.next_amount_usdc and usdc_available (proceeds land net of fees and slippage). Omit amount_usdc when that is zero: "0" is refused with 400. Submit the buys.

Use funding.next_amount_usdc, not funding.buys_deferred_usdc: it is the strategy's cash after this round (amount_usdc plus the sells, less the buys), so it keeps the book's unweighted remainder and the weight of any not_tradable name in nav. Calling round 2 without amount_usdc, or with only the deferred buys, shrinks nav, and the plan sells again.

Wait for every order to finish before calling again. Each order from the previous round must have reached a final status (GET /quote/{quote_id}/status) before any new call. The plan reads your holdings as they stand and this route never refuses an early or retried call, so it returns the same sells again and both sets can execute. (POST /signals-orders/rebalance refuses such a call with 409 orders_in_flight.)

One wallet per strategy. Your holdings are not tracked per strategy: every name of the book you hold in this wallet counts, whichever strategy (or none) you bought it for. Two strategies sharing a name in one wallet will sell or resize each other's position, so give each strategy its own wallet.

expected_book_hash, when sent, must equal the served book's book_hash, or the call is refused with 409 book_changed before the wallet is read or anything is quoted.

Sells are floored to 18 decimal places and buys to 6, never rounded up. A gap under $1 is skipped as below_min_notional. A book name Treasures cannot buy on Solana is skipped as not_tradable and its weight stays in USDC. At most 25 orders are returned and their upstream quote calls are capped at 30 (see POST /signals-orders/rebalance): sells are admitted first, then buys, each side largest first; the first order that does not fit and every one after it is skipped as leg_cap.

Unlike /exit, which skips a name it cannot read, a rebalance refuses the whole request when any name in scope cannot be read (holdings_unknown) or a held one cannot be priced (price_unavailable), because one mis-sized name would mis-size every other order. The refusal lists the tickers to retry or remove.

max_slippage_bps is optional here (nothing is quoted) and range-checked when sent. Requires your general (tik_) key; a reporting key is refused.

Request​

Responses​

OK