The sells and buys that bring your strategy positions to its book, with no quotes
/signals-orders /rebalance /planReturns 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/sellwith{ "ticker": <ticker>, "amount_shares": <shares>, "chain": "sol", "sol_wallet": <sol_wallet>, "ownership_proof": <proof>, "max_slippage_bps": <bps> } - a buy is
POST /quote/buywith{ "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:
- Call with
amount_usdcomitted. Submit the sells. - Once they settle, call again with
amount_usdcset to the smaller offunding.next_amount_usdcandusdc_available(proceeds land net of fees and slippage). Omitamount_usdcwhen that is zero:"0"is refused with400. 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
- 200
- 400
- 401
- 403
- 404
- 409
- 422
- 429
- 503
OK
Invalid request body (including eth_wallet, protocol or amount_usdc: "0"), or slippage out of range.
Missing, malformed or unknown X-API-Key, or an ownership-proof failure.
address_blocked (sanctions screening flagged the wallet), or insufficient_scope, key_revoked or integrator_suspended.
No such strategy for you (see GET /signals/strategies/{id}).
book_changed: expected_book_hash is not the book served now. The wallet was not read and nothing was quoted; re-read the book (book_hash is the served one) and decide again.
book_unavailable: the strategy has no book yet.holdings_unknownorprice_unavailablewithtickers: those names could not be read or priced, so no plan is offered. A read or price failure is usually transient and can be retried, but a book name that is no longer tradable (an inactive listing) refuses every rebalance on this strategy until its next book, so do not retry blindly;POST /signals-orders/exitskips that name and serves the rest.insufficient_balance:amount_usdcis more than the wallet's Solana USDC.strategy_halted: the strategy is halted, so no rebalance is offered and nothing is read;POST /signals-orders/exit/planstill serves it.
Sliding window exceeded: per-IP or per-(IP, wallet), plus a per-organisation bucket (shared across all of your keys) whenever a valid X-API-Key is presented. Retry-After header carries delta-seconds.
Transient; retry.
screening_unavailableorintegrator_fee_misconfigured(seePOST /quote/sell)balance_unavailable: the wallet's Solana USDC could not be read, and is never reported as zeroholdings_unavailable: the wallet's holdings could not be read.
When the reads behind the plan (screening, the strategy and its book, holdings, prices and
USDC) did not answer within 15 seconds, the call answers holdings_unavailable, or
screening_unavailable when screening was the read still pending, with Retry-After: 15.
Response Headers
Delta-seconds, 15, sent when the reads passed their deadline. Wait that long before retrying.