Skip to main content
A rebalance — sometimes called “Move Funds” in the console — moves an exact amount from one venue’s spendable form into another’s. The cross-chain bridge happens once, deliberately, instead of inline on the first order you submit against an under-funded venue. This guide explains when to use a rebalance, the lifecycle a request moves through, and the idempotency rules you should follow when wiring it into your own workflow.

​
Why rebalance

Each venue settles in a specific chain and token. When the venue you are trading on lives on a different chain than where your funds are currently resting, submitting an order blocks synchronously on a cross-chain bridge — typically a couple of minutes, with a hard cap of ten. Every order placed on the “wrong” chain pays that latency. A rebalance moves the bridge off the order path. You tell the aggregator how much to move from one venue to another; it does the conversions and bridge once. Later orders on the destination venue fire immediately because their collateral is already in the venue’s spendable form. Rebalancing is optional. The inline bridge stays as the fallback — if you submit an order against an under-funded venue, the aggregator will still route the funds for you. Use a rebalance when you know which venue you are about to trade on and want the first order to be fast.

​
Per-venue resting forms

Each venue resolves to a specific chain and token that its books settle in. A rebalance debits the source venue’s resting form and lands the amount in the destination venue’s resting form: sourceVenue and destinationVenue must differ. A rebalance only moves a venue’s own spendable form — loose USDC sitting on a chain that isn’t yet in a venue’s resting form is not a valid source.

​
Submit a rebalance

Submit a request with POST /v1/rebalances.
The response body is just the aggregator-issued rebalanceId — the handle you use for status lookups. The Idempotency-Key you sent is echoed back in the Idempotency-Key response header.
A few things to know about the request:
  • amount is the amount that must land at the destination, in USDC, up to six decimal places. It must be greater than zero. The aggregator grosses up the source debit to cover bridge and swap slippage so the destination receives at least amount.
  • sourceVenue is debited and destinationVenue is credited. They must be different venues.
  • maxSlippageBps is optional. It caps slippage on the lossy swap and bridge steps; if omitted, the aggregator applies a server-side default.

​
Idempotency

Pass an Idempotency-Key request header. Re-submitting the same key with the same body returns the existing rebalance instead of starting a new one — safe to retry on network errors or process restarts. Pick something stable per logical request (for example, rb-2026-06-07-001). A few rules to keep in mind:
  • The header is required; a request without it is rejected with 400.
  • The key is unique per customer. Two different customers can use the same Idempotency-Key without conflict.
  • Re-submitting the same key with a different body is rejected with 422. Pick a new key when the source, destination, or amount changes.

​
Poll the rebalance

Fetch the latest state with GET /v1/rebalances/{rebalanceId}.
The Rebalance resource carries the move and its lifecycle state. The Idempotency-Key is returned as a response header, not in the body:
Poll until status reaches a terminal state. A one- to two-second interval is usually enough; updatedAt advances on every state change. To page through past rebalances, use GET /v1/rebalances, which returns the most-recently-active first.

​
Lifecycle

Every rebalance moves through a four-state lifecycle. A failed rebalance is fail-closed: the aggregator did not partially move your funds. Your funds stay available and you can submit a new rebalance (with a fresh Idempotency-Key) or fall back to submitting the order directly.

​
Failure reasons

When status is failed, error is an object with a machine-readable code and a human-readable message; it is null otherwise.