> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parlayx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rebalance (Move Funds)

> Move funds from one venue to another ahead of trading to skip the inline cross-chain bridge

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](/api-reference/orders/submit-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:

| Venue        | Chain   | Spendable form              |
| ------------ | ------- | --------------------------- |
| `polymarket` | Polygon | pUSD on your deposit wallet |
| `limitless`  | Base    | Native USDC on your EOA     |

`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](/api-reference/rebalances/submit-rebalance).

```bash theme={null}
curl -X POST https://api.parlayx.com/v1/rebalances \
  -H "x-api-key: $PARLAYX_API_KEY" \
  -H "Idempotency-Key: rb-2026-06-07-001" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceVenue": "limitless",
    "destinationVenue": "polymarket",
    "amount": 25
  }'
```

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**.

```json theme={null}
{
  "rebalanceId": "3f8b2c9a-2d18-4f7e-9c2a-1b6e1f0c8a4d"
}
```

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}](/api-reference/rebalances/get-rebalance).

```bash theme={null}
curl "https://api.parlayx.com/v1/rebalances/3f8b2c9a-2d18-4f7e-9c2a-1b6e1f0c8a4d" \
  -H "x-api-key: $PARLAYX_API_KEY"
```

The `Rebalance` resource carries the move and its lifecycle state. The
`Idempotency-Key` is returned as a response header, not in the body:

```json theme={null}
{
  "rebalanceId": "3f8b2c9a-2d18-4f7e-9c2a-1b6e1f0c8a4d",
  "sourceVenue": "limitless",
  "destinationVenue": "polymarket",
  "amount": 25,
  "status": "processing",
  "error": null,
  "createdAt": "2026-06-07T18:42:11.000Z",
  "updatedAt": "2026-06-07T18:42:13.000Z"
}
```

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](/api-reference/rebalances/list-rebalances), which returns
the most-recently-active first.

## Lifecycle

Every rebalance moves through a four-state lifecycle.

| Status       | Meaning                                                                 | Terminal |
| ------------ | ----------------------------------------------------------------------- | -------- |
| `pending`    | Accepted by the aggregator; not yet started.                            | No       |
| `processing` | Converting and/or bridging funds into the destination's spendable form. | No       |
| `completed`  | The amount landed at the destination venue.                             | Yes      |
| `failed`     | Terminal. No funds were moved; check `error`.                           | Yes      |

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.

| `error.code`         | What it means                                                                          |
| -------------------- | -------------------------------------------------------------------------------------- |
| `INSUFFICIENT_FUNDS` | The source venue does not hold enough to move the requested amount to the destination. |
| `INTERNAL_ERROR`     | An internal failure. Safe to retry; contact support if it persists.                    |