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

# Transfers

> Move cash between your account's Polymarket and Hyperliquid balances.

A transfer moves cash from one of your account's venues to the other: from Polymarket to
Hyperliquid, or from Hyperliquid to Polymarket. The cash always lands in your own account's
balance on the other venue. A transfer can't send funds to any other address or account.

> [!NOTE]
>
> Transfers work with test keys today. A live key gets `503 FEATURE_DISABLED` with
> `details.reason: "LIVE_TRANSFERS_UNAVAILABLE"`, and moves nothing. To use cash on the other venue
> with a live key, place the order with `POST /v1/orders`: it pays from the other venue in the same
> call. See [Paying from the other venue](https://docs.lean.xyz/orders.md#paying-from-the-other-venue).

A transfer takes three calls:

1. `POST /v1/transfers/quote` shows the fee, what arrives, the minimum and what you can send.
2. `POST /v1/transfers` creates the transfer and returns the message to sign.
3. `POST /v1/transfers/{id}/execute` sends your signature. Lean then moves the cash.

Creating and executing need a key with the `trade` and `route` scopes. Quoting and reading need
`read`. See [Authentication](https://docs.lean.xyz/authentication.md#create-a-key).

**1. Quote the transfer**

```bash theme={"dark"}
curl -sS -X POST "$LEAN_API_URL/v1/transfers/quote" \
  -H "Authorization: Bearer $LEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "from_venue": "polymarket", "to_venue": "hyperliquid", "amount_usd": "25" }'
```

| Field | Meaning |
| - | - |
| `amount_usd` | What leaves `from_venue`. |
| `fee_usd` | What the move costs. It comes out of `amount_usd`. |
| `receive_usd` | What arrives on `to_venue`: `amount_usd` minus `fee_usd`. |
| `minimum_usd` | The smallest `amount_usd` this route accepts. |
| `available_usd` | What `from_venue` can send right now. |
| `estimated_seconds` | How long the move usually takes once authorized. |
| `expires_at` | Until when a transfer created now can be authorized. |
| `warnings` | Why creating this transfer would be refused: `BELOW_VENUE_MINIMUM` under `minimum_usd`, `INSUFFICIENT_FUNDS` over `available_usd`. Empty means the amount fits the route; creating the transfer can still be refused under the key's notional limits, allowed venues or a placement block. |

A quote never moves cash, and it answers even when the amount is below the minimum or above
what is available, so you can show the numbers before you ask. Check `warnings` before you
create the transfer.

**2. Create the transfer**

```bash theme={"dark"}
curl -sS -X POST "$LEAN_API_URL/v1/transfers" \
  -H "Authorization: Bearer $LEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_transfer_id": "rebalance-2026-11-11-0001",
    "from_venue": "polymarket",
    "to_venue": "hyperliquid",
    "amount_usd": "25"
  }'
```

`client_transfer_id` is your ID for the transfer. Sending the same body again returns the same
transfer, so a retry never moves cash twice. The same ID with a different body is
`409 CONFLICT`, and `details.transfer_id` names the original.

The transfer starts as `awaiting_authorization`, and `amount_usd` is held on `from_venue` at
once: `available_usd` in `GET /v1/balances` drops by it. `authorization` says what to sign:

| Field | Meaning |
| - | - |
| `authorization.signer_address` | The wallet that must sign: the account owner's. |
| `authorization.expires_at` | Sign and execute before this time. |
| `authorization.payloads` | The EIP-712 messages to sign, in order. Each has a `scheme` and `typed_data`. |

**3. Sign and execute**

Sign each `typed_data` exactly as returned, then send the signatures in the same order:

```bash theme={"dark"}
curl -sS -X POST "$LEAN_API_URL/v1/transfers/$TRANSFER_ID/execute" \
  -H "Authorization: Bearer $LEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "authorization": "signature", "signatures": ["0x…"] }'
```

If the account has enabled trading in the Lean app, send `{ "authorization": "delegated" }`
instead and Lean signs with the account's delegated signer.

The transfer moves to `pending`, then `completed` once the cash arrives. Sending the same
signatures again returns the transfer and moves nothing.

## Follow a transfer

`GET /v1/transfers/{id}` returns one transfer. `GET /v1/transfers` lists the key's account's
transfers, newest first. Pass `limit` (1 to 100) and the `next_cursor` from the previous page as
`cursor` to read further back.

| Status | Meaning |
| - | - |
| `awaiting_authorization` | Created. The amount is held on `from_venue` until you execute. |
| `pending` | Authorized. The cash is on its way. |
| `completed` | `receive_usd` arrived on `to_venue`. |
| `failed` | The move did not happen. `failure_reason` says why, and the held amount is released. |
| `expired` | Not executed before `authorization.expires_at`. The held amount is released. |

## Limits and refusals

A transfer counts against the per order and daily limits of the key and its account like an
order, and a paused key or
trading account can't create or execute one. A quote still answers while paused.

| Response | `details.reason` | When |
| - | - | - |
| `400 VALIDATION_ERROR` | | The venues are the same, a venue is not `polymarket` or `hyperliquid`, the amount is malformed, or the body has a field a transfer does not take. |
| `422 VALIDATION_ERROR` | `BELOW_VENUE_MINIMUM` | `amount_usd` is below the route minimum. `details.minimum_usd` is the minimum. |
| `422 VALIDATION_ERROR` | `INSUFFICIENT_FUNDS` | `from_venue` can't send `amount_usd`. `details.available_usd` is what it can send. |
| `422 VALIDATION_ERROR` | `VENUE_NOT_ALLOWED` | The trading account does not allow one of the two venues. `details.allowed_venues` lists the ones it allows. |
| `422 VALIDATION_ERROR` | `ORDER_NOTIONAL_LIMIT`, `DAILY_NOTIONAL_LIMIT` | The amount is over the key's or account's limits. |
| `400 VALIDATION_ERROR` | `SIGNER_MISMATCH`, `INVALID_SIGNATURE` | A signature is not the owner's over the payload Lean returned. |
| `403 FORBIDDEN` | `ACCOUNT_NOT_DELEGATED` | `delegated` was sent, but the account has not enabled trading in the Lean app. |
| `409 CONFLICT` | `PAYMENT_ALREADY_AUTHORIZED` | The transfer was already authorized another way. |
| `409 CONFLICT` | `QUOTE_EXPIRED` | The transfer expired before it was executed. Create a new one. |
| `503 FEATURE_DISABLED` | `TRADING_PAUSED` | The key or its trading account is paused. |
| `503 FEATURE_DISABLED` | `LIVE_TRANSFERS_UNAVAILABLE` | A live key. Transfers are test mode only for now. |

## In test mode

A test transfer moves simulated cash between the test balances. It costs a flat 0.10 USD, its minimum
is 2 USD, and it completes as soon as it is executed. [Reset test mode](https://docs.lean.xyz/api-reference/test-mode/reset-test-mode.md)
deletes the account's test transfers along with its test orders.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.