# Withdrawals

> Quote and execute withdrawals from your wallets to one address, on the same chain or across chains through an exchange.

A withdrawal drains a set of wallets into one destination. The request names the wallets (`origin` and `source`), the asset to take, and the `payout`: `classic` delivers the same asset on the same chain, `cex` goes through an exchange and can change chain and asset, optionally split into delayed legs.

The flow is: [list the routes](#list-withdraw-routes), [quote](#retrieve-a-withdraw-quote) the exact body to see what each wallet can give, then [execute](#execute-a-withdrawal) the same body. Execution returns `202` once the work is persisted; collection, payout and exchange settlement continue in the background. Follow each row with [Retrieve a withdrawal](#retrieve-a-withdrawal) until it is `completed`, `failed` or `cancelled`.

Every amount is an integer string in atomic units (lamports, wei or token base units), because values can exceed JavaScript's safe integer range. The web app uses these endpoints for wallet withdrawals, funder withdrawals, Clean dust and bridge deposits into a funder.

Base URL: `https://api-mig.proxima.tools`

## Endpoints

- `GET /withdraw/routes`: List withdraw routes
- `POST /withdraw/quote`: Retrieve a withdraw quote
- `POST /withdraw/execute`: Execute a withdrawal
- `GET /withdraw/{withdrawal_id}`: Retrieve a withdrawal
- `GET /withdraw`: List withdrawals
- `POST /withdraw/cancel/{withdrawal_id}`: Cancel a withdrawal

## The Withdrawal object

One withdrawal row: one destination with its own hop. A request with several destinations creates several rows sharing a `group_id`.

- `id` (string): Withdrawal ID (UUID).
- `group_id` (string): Shared by every row created from the same execute request.
- `status` (enum): Progress of the row. `completed`, `failed` and `cancelled` are terminal. Possible values: `draft`, `collecting`, `hop_funded`, `paying`, `settling`, `completed`, `failed`, `cancelled`.
- `origin` (object): Origin of the request.
  - `kind` (enum): Origin kind. Possible values: `launch`, `aged`, `global`.
  - `launch_ext_id` (string): Launch ID, for a launch origin.
- `src` (object): Source chain and asset.
  - `chain` (enum): Source chain. Possible values: `sol`, `bsc`, `eth`, `base`, `robinhood`, `arc`, `xlayer`.
  - `asset` (string): Source asset.
- `dst` (object): Destination.
  - `chain` (enum): Destination chain. Possible values: `sol`, `bsc`, `eth`, `base`, `robinhood`, `arc`, `xlayer`.
  - `asset` (string): Destination asset.
  - `address` (string): Address credited by the payout.
- `payout_kind` (enum): Payout kind. Possible values: `classic`, `cex`.
- `collected` (array<object>): Collection transfers made from the source wallets.
  - `address` (string): Source wallet.
  - `amount` (string): Atomic units collected. Preserved as a string by the client because atomic amounts can exceed the JavaScript safe integer range.
  - `tx` (string): Transaction hash or signature.
- `hop` (object): Intermediate wallet the funds are collected into before the payout.
  - `address` (string): Hop address.
  - `landed` (string): Atomic units received by the hop. Preserved as a string by the client because atomic amounts can exceed the JavaScript safe integer range.
- `payout` (object): Payout progress.
  - `tx` (string): Payout transaction.
- `error` (string): Failure reason, when `status` is `failed`.
- `created_at` (integer): Unix timestamp (seconds, UTC) at which the row was created.
- `started_at` (integer): Unix timestamp (seconds) at which processing started.
- `finished_at` (integer): Unix timestamp (seconds) at which the row reached a terminal status.

```json
{
  "id": "684b1e4f-decd-437b-babf-4384eebb8b10",
  "group_id": "684b1e4f-decd-437b-babf-4384eebb8b10",
  "status": "completed",
  "origin": {
    "kind": "aged"
  },
  "src": {
    "chain": "sol",
    "asset": "native"
  },
  "dst": {
    "chain": "sol",
    "asset": "native",
    "address": "DKfba8BZznqYcPa9r2dE1oxd635exYJWuZtrefA8XyPF"
  },
  "payout_kind": "classic",
  "collected": [
    {
      "address": "C31EeqtSvpjYHFQxBoP9bBTpqtUWV2avNhjdaN1yem44",
      "amount": "1489000000",
      "tx": "4UAUY1zva1Wg1a2mBXkZLkjukpMhbSe3X43BpNL6UP9AuzGhwLh2PnsY11H3JJMjuZswyk9zA2CKiw3Lip4hTGbL"
    },
    {
      "address": "ART7zvRihsxp6iuCegVRED44XZMov9u6fnFJHF7HqcN4",
      "amount": "1000000000",
      "tx": "5K1g9bQMqoMvVUgSD92K9PUDSwmNuCpzQDU6DiEj9iBuYVDeph7qEmxrsodWFSguTfgUrZhhcZG7K3jMeSwHC2up"
    }
  ],
  "hop": {
    "address": "AqaW1YghutnQEhjycn8m26Rr4RzZuZAoaNYsFjRP5NDp",
    "landed": "2489000000"
  },
  "payout": {
    "tx": "QhdKjiybHRzvb1Z815uLe9gXfNFkWk4iXBh6sdT3YHL6pV3ohS2ZUXsXA6sDf4jS5Lwf631zbaUYeZQUCwQajkYo"
  },
  "created_at": 1793560000,
  "started_at": 1793560001,
  "finished_at": 1793560019
}
```

### List withdraw routes

`GET /withdraw/routes`

Returns the source and destination pairs that can be served, for classic and CEX payouts. (Bearer JWT)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: allowed.
- Retry: Safe to retry.

Cached server-side with no live calls, so it is safe to load when a withdraw screen opens. A route may name the launch quote token either as `quote` or as its mint; compare both forms. Launch quote on a classic payout is accepted by quote and execute even though this list only shows `native` for classic.

#### Returns 200 OK

- `ok` (boolean): Always `true`.
- `classic` (array<object>): Classic routes.
  - `src_chain` (enum): Source chain. Possible values: `sol`, `bsc`, `eth`, `base`, `robinhood`, `arc`, `xlayer`.
  - `src_asset` (string): Source asset.
  - `dst_chain` (enum): Destination chain. Possible values: `sol`, `bsc`, `eth`, `base`, `robinhood`, `arc`, `xlayer`.
  - `dst_asset` (string): Destination asset.
- `cex` (array<object>): CEX routes.
  - `src_chain` (enum): Source chain. Possible values: `sol`, `bsc`, `eth`, `base`, `robinhood`, `arc`, `xlayer`.
  - `src_asset` (string): Source asset.
  - `dst_chain` (enum): Destination chain. Possible values: `sol`, `bsc`, `eth`, `base`, `robinhood`, `arc`, `xlayer`.
  - `dst_asset` (string): Destination asset.
  - `providers` (array<string>): Exchanges that can serve the route.
  - `husher_only` (boolean): Whether Husher liquidity is the only option (always on `robinhood`).
  - `indicative_min_src_atomic` (string): Indicative minimum in source atomic units; omitted when it cannot be computed. Use it for sorting only and gate on the quote's `needs`. Preserved as a string by the client because atomic amounts can exceed the JavaScript safe integer range.

#### Example request

```bash
curl "https://api-mig.proxima.tools/withdraw/routes" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "ok": true,
  "classic": [
    {
      "src_chain": "sol",
      "src_asset": "native",
      "dst_chain": "sol",
      "dst_asset": "native"
    },
    {
      "src_chain": "bsc",
      "src_asset": "native",
      "dst_chain": "bsc",
      "dst_asset": "native"
    }
  ],
  "cex": [
    {
      "src_chain": "sol",
      "src_asset": "native",
      "dst_chain": "bsc",
      "dst_asset": "native",
      "providers": [
        "binance",
        "kucoin"
      ],
      "husher_only": false,
      "indicative_min_src_atomic": "71000000"
    }
  ]
}
```

### Retrieve a withdraw quote

`POST /withdraw/quote`

Describes what a withdraw request would collect and deliver, without signing or moving anything. (Bearer JWT)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. Read-only: nothing is created or sent.

Takes the exact body of [Execute a withdrawal](#execute-a-withdrawal). The web app calls it debounced while the user edits a withdraw form, and aborts stale calls.

#### Body parameters

- `origin` (object, required): Universe of wallets the source draws from.
  - `kind` (enum, required): `launch`: the wallets of a launch. `aged`: your trading wallets. `global`: any wallet of the account named explicitly (requires `source.select.kind` `explicit`), for example a funder. Possible values: `launch`, `aged`, `global`.
  - `launch_ext_id` (string, optional): Launch ID. Required when `kind` is `launch`.
- `source` (object, required): Which wallets to drain and how much. Use either `select` or `transfers`, never both.
  - `chain` (enum, required): Chain the funds are taken from. Possible values: `sol`, `bsc`, `eth`, `base`, `robinhood`, `arc`, `xlayer`.
  - `asset` (string, required): `native`, a token mint or contract address, or `quote` (the launch's quote token; requires `origin.kind` `launch`). Never a symbol.
  - `select` (object, optional): Wallet selection inside the origin.
    - `kind` (enum, required): `explicit` lists wallets; `aged` takes the trading wallets of the origin; `launch_all` takes every wallet of the origin. Possible values: `explicit`, `aged`, `launch_all`.
    - `wallets` (array<string>, optional): Addresses to drain. Required when `kind` is `explicit`.
  - `mode` (enum, optional): Required with `select`. `leave_on` keeps the wallets of the roles in `leave_on` full. Possible values: `withdraw_all`, `leave_on`.
  - `leave_on` (array<string>, optional): Required with `select` (may be empty). Roles left untouched: `dev`, `aged`, `funder`, `others`, `holders` (`holders` requires `origin.kind` `launch`).
  - `amount` (string, optional): Required with `select`. Total cap in atomic units across all wallets; `"0"` drains everything. Preserved as a string by the client because atomic amounts can exceed the JavaScript safe integer range.
  - `dust_amount` (string, optional): Atomic units left behind in each wallet.
  - `dust_amount_min` (string, optional): Lower bound of a random amount left behind per wallet. At most `dust_amount_max`.
  - `dust_amount_max` (string, optional): Upper bound of a random amount left behind per wallet.
  - `transfers` (array<object>, optional): Manual per-wallet transfers, instead of `select`. Requires `payout.kind` `classic`. Each distinct `to` becomes its own row.
    - `from` (string, required): Source wallet.
    - `to` (string, required): Destination address.
    - `amount` (string, required): Atomic-unit cap for this transfer, greater than 0. Preserved as a string by the client because atomic amounts can exceed the JavaScript safe integer range.
- `payout` (object, required): Where and how the funds are delivered.
  - `kind` (enum, required): `classic` delivers the same asset on the same chain. `cex` goes through an exchange and can change chain and asset. Possible values: `classic`, `cex`.
  - `chain` (enum, required): Destination chain. Must equal `source.chain` for `classic`. Possible values: `sol`, `bsc`, `eth`, `base`, `robinhood`, `arc`, `xlayer`.
  - `asset` (string, required): Destination asset, same format as `source.asset`. Must equal `source.asset` for `classic`.
  - `address` (string, optional): Destination address. Required to execute unless `source.transfers` is used; if sent with `transfers`, it must match every `to`.
  - `providers` (array<string>, optional): `cex` only. Restricts the exchange pool.
  - `legs` (integer, optional): `cex` only. Number of legs the payout is split into.
  - `delay_min_minutes` (integer, optional, default "8"): `cex` only. Minimum gap between two consecutive legs, in minutes.
  - `delay_max_minutes` (integer, optional, default "13"): `cex` only. Maximum gap between two consecutive legs, in minutes. At least `delay_min_minutes`.
  - `split_jitter_pct` (integer, optional): `cex` only. Irregularity of the split percentages.
  - `per_wallet_orders` (boolean, optional): `cex` only. One hop and one exchange order per source wallet.

#### Returns 200 OK

- `ok` (boolean): Always `true`.
- `total_src_atomic` (string): Maximum withdrawable in source atomic units: the cap to offer. Preserved as a string by the client because atomic amounts can exceed the JavaScript safe integer range.
- `wallets` (array<object>): Per-wallet breakdown.
  - `address` (string): Wallet address.
  - `drainable` (string): Atomic units this wallet can give. Preserved as a string by the client because atomic amounts can exceed the JavaScript safe integer range.
  - `included` (boolean): Whether the wallet takes part.
  - `reason` (enum): Why the wallet is excluded. Possible values: `below_gas_and_leave`, `cap_reached`, `not_found`, `watched_no_secret`, `blocked_account`, `invalid_address`, `holder_status_unknown`.
  - `needs` (string): Shortfall in atomic units for the wallet to be included. Omitted when satisfied or unknown. Preserved as a string by the client because atomic amounts can exceed the JavaScript safe integer range.
- `plan` (object): Execution plan.
  - `hop_count` (integer): `1`, or the number of distinct destinations in `transfers` mode.
- `estimated_duration_seconds` (integer): Expected time until the destination is credited, including CEX leg delays.
- `estimated_receive_atomic` (string): What the destination receives net of fees, in atomic units of `payout.asset` on `payout.chain` (not the same scale as `total_src_atomic` on cross-chain routes). Absent when nothing can price the route; `"0"` means zero. Preserved as a string by the client because atomic amounts can exceed the JavaScript safe integer range.
- `minimum_src_atomic` (string): CEX only. Binding source-side order minimum, in atomic units.
- `needs_src_atomic` (string): CEX only. Aggregate shortfall against the order minimum after fees, in atomic units.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `origin.launch_ext_id required for origin.kind=launch` | `origin.kind` is `launch` but `origin.launch_ext_id` is missing. | Set `origin.launch_ext_id` to the launch's external ID. |
| 400 | `bad_request` | `source.asset=quote requires origin.kind=launch` | `source.asset` is `quote` outside a launch origin. | Use a launch origin, or withdraw the native asset. |
| 400 | `bad_request` | `source.select and source.transfers are mutually exclusive` | Both `source.select` and `source.transfers` were sent. | Send only one of `source.select` and `source.transfers`. |
| 400 | `bad_request` | `source requires either select or transfers` | Neither `source.select` nor `source.transfers` was sent. | Send `source.select` or `source.transfers`. |
| 400 | `bad_request` | `source.transfers requires payout.kind=classic` | `source.transfers` was sent with a `cex` payout. | Set `payout.kind` to `classic`, or use `source.select`. |
| 400 | `bad_request` | `source.amount and source.transfers are mutually exclusive` | A non-zero `source.amount` was sent with `source.transfers`. | Drop `source.amount` and set the amounts in `source.transfers`. |
| 400 | `bad_request` | `source.transfers amount must be > 0` | A transfer has an amount of 0. | Give every transfer an amount above 0. |
| 400 | `bad_request` | `payout.address disagrees with source.transfers[].to` | `payout.address` differs from the `to` of the transfers. | Make `payout.address` match the transfers' `to`, or omit it. |
| 400 | `bad_request` | `payout.delay_min_minutes must be <= payout.delay_max_minutes` | `payout.delay_min_minutes` is above `payout.delay_max_minutes`. | Set `payout.delay_min_minutes` no higher than `payout.delay_max_minutes`. |
| 400 | `bad_request` | `a classic payout cannot change chain or asset; use kind=cex` | A `classic` payout changes chain or asset. | Match `payout.chain` and `payout.asset` to the source, or set `payout.kind` to `cex`. |
| 400 | `bad_request` | `mixing options require payout.kind=cex` | A `classic` payout carries CEX-only options: `legs`, `providers`, `delay_min_minutes`, `delay_max_minutes`, `split_jitter_pct` or `per_wallet_orders`. | Remove those options or set `payout.kind` to `cex`. |
| 400 | `bad_request` | `dust_amount_min must be <= dust_amount_max` | `source.dust_amount_min` is above `source.dust_amount_max`. | Set `source.dust_amount_min` no higher than `source.dust_amount_max`. |
| 400 | `bad_request` | `leave_on=holders requires origin.kind=launch` | `source.leave_on` is `holders` outside a launch origin. | Use a launch origin, or another `leave_on` value. |
| 400 | `bad_request` | `unknown source chain: <chain>` | `source.chain` is not a chain the API serves. | Use a `source.chain` value listed for this endpoint. |
| 404 | `not_found` | `launch not found` | The launch in `origin.launch_ext_id` is not on the account. | Use the external ID of one of your launches. |
| 400 | `bad_request` | `invalid origin.launch_ext_id` | `origin.launch_ext_id` is not a valid launch external ID. | Use the external ID of one of your launches. |
| 400 | `bad_request` | `origin.launch_ext_id is a <chain> launch, but source.chain is <chain>: origin names the launch whose wallets are drained; a launch receiving the payout goes in payout.launch_ext_id` | `origin.launch_ext_id` is a launch on another chain than `source.chain`. | Set `source.chain` to the launch's chain. |
| 400 | `bad_request` | `origin.kind=global requires select.kind=explicit` | `origin.kind` is `global` but `source.select.kind` is not `explicit`. | Set `source.select.kind` to `explicit` and list the wallets. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/withdraw/quote" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "origin": {
    "kind": "aged"
  },
  "source": {
    "chain": "sol",
    "asset": "native",
    "select": {
      "kind": "explicit",
      "wallets": [
        "C31EeqtSvpjYHFQxBoP9bBTpqtUWV2avNhjdaN1yem44",
        "ART7zvRihsxp6iuCegVRED44XZMov9u6fnFJHF7HqcN4"
      ]
    },
    "mode": "withdraw_all",
    "leave_on": [],
    "amount": "0"
  },
  "payout": {
    "kind": "classic",
    "chain": "sol",
    "asset": "native",
    "address": "DKfba8BZznqYcPa9r2dE1oxd635exYJWuZtrefA8XyPF"
  }
}'
```

#### Example response

```json
{
  "ok": true,
  "total_src_atomic": "2489000000",
  "wallets": [
    {
      "address": "C31EeqtSvpjYHFQxBoP9bBTpqtUWV2avNhjdaN1yem44",
      "drainable": "1489000000",
      "included": true
    },
    {
      "address": "ART7zvRihsxp6iuCegVRED44XZMov9u6fnFJHF7HqcN4",
      "drainable": "1000000000",
      "included": true
    }
  ],
  "plan": {
    "hop_count": 1
  },
  "estimated_duration_seconds": 20,
  "estimated_receive_atomic": "2488985000"
}
```

### Execute a withdrawal

`POST /withdraw/execute`

Starts a withdrawal and returns once its rows are persisted. (Bearer JWT · 2FA step-up)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Two-factor: step-up for `wallet.withdraw` when the user protects it (`401 2fa_required`).
- Retry: Check before retrying. A repeat while the first withdrawal is live is refused, but once it settles a repeat withdraws again. Before retrying, call [List withdrawals](/reference/withdrawals/#list-withdrawals) and look for recent rows with the same origin and destination; there is no `group_id` filter, so match `group_id` on the returned rows.

Same body as the quote. Responds `202 Accepted` with the first row's `id` and the `group_id`; when `id` differs from `group_id`, list withdrawals and match `group_id` on the returned rows to find every row. The web app then polls [Retrieve a withdrawal](#retrieve-a-withdrawal) every second until each row is terminal.

> Moves funds out of your wallets. Once a classic row starts collecting it cannot be recalled.

> Protected by the `wallet.withdraw` 2FA action when enabled, unless every destination is one of your own funders.

#### Body parameters

- `origin` (object, required): Universe of wallets the source draws from.
  - `kind` (enum, required): `launch`: the wallets of a launch. `aged`: your trading wallets. `global`: any wallet of the account named explicitly (requires `source.select.kind` `explicit`), for example a funder. Possible values: `launch`, `aged`, `global`.
  - `launch_ext_id` (string, optional): Launch ID. Required when `kind` is `launch`.
- `source` (object, required): Which wallets to drain and how much. Use either `select` or `transfers`, never both.
  - `chain` (enum, required): Chain the funds are taken from. Possible values: `sol`, `bsc`, `eth`, `base`, `robinhood`, `arc`, `xlayer`.
  - `asset` (string, required): `native`, a token mint or contract address, or `quote` (the launch's quote token; requires `origin.kind` `launch`). Never a symbol.
  - `select` (object, optional): Wallet selection inside the origin.
    - `kind` (enum, required): `explicit` lists wallets; `aged` takes the trading wallets of the origin; `launch_all` takes every wallet of the origin. Possible values: `explicit`, `aged`, `launch_all`.
    - `wallets` (array<string>, optional): Addresses to drain. Required when `kind` is `explicit`.
  - `mode` (enum, optional): Required with `select`. `leave_on` keeps the wallets of the roles in `leave_on` full. Possible values: `withdraw_all`, `leave_on`.
  - `leave_on` (array<string>, optional): Required with `select` (may be empty). Roles left untouched: `dev`, `aged`, `funder`, `others`, `holders` (`holders` requires `origin.kind` `launch`).
  - `amount` (string, optional): Required with `select`. Total cap in atomic units across all wallets; `"0"` drains everything. Preserved as a string by the client because atomic amounts can exceed the JavaScript safe integer range.
  - `dust_amount` (string, optional): Atomic units left behind in each wallet.
  - `dust_amount_min` (string, optional): Lower bound of a random amount left behind per wallet. At most `dust_amount_max`.
  - `dust_amount_max` (string, optional): Upper bound of a random amount left behind per wallet.
  - `transfers` (array<object>, optional): Manual per-wallet transfers, instead of `select`. Requires `payout.kind` `classic`. Each distinct `to` becomes its own row.
    - `from` (string, required): Source wallet.
    - `to` (string, required): Destination address.
    - `amount` (string, required): Atomic-unit cap for this transfer, greater than 0. Preserved as a string by the client because atomic amounts can exceed the JavaScript safe integer range.
- `payout` (object, required): Where and how the funds are delivered.
  - `kind` (enum, required): `classic` delivers the same asset on the same chain. `cex` goes through an exchange and can change chain and asset. Possible values: `classic`, `cex`.
  - `chain` (enum, required): Destination chain. Must equal `source.chain` for `classic`. Possible values: `sol`, `bsc`, `eth`, `base`, `robinhood`, `arc`, `xlayer`.
  - `asset` (string, required): Destination asset, same format as `source.asset`. Must equal `source.asset` for `classic`.
  - `address` (string, optional): Destination address. Required to execute unless `source.transfers` is used; if sent with `transfers`, it must match every `to`.
  - `providers` (array<string>, optional): `cex` only. Restricts the exchange pool.
  - `legs` (integer, optional): `cex` only. Number of legs the payout is split into.
  - `delay_min_minutes` (integer, optional, default "8"): `cex` only. Minimum gap between two consecutive legs, in minutes.
  - `delay_max_minutes` (integer, optional, default "13"): `cex` only. Maximum gap between two consecutive legs, in minutes. At least `delay_min_minutes`.
  - `split_jitter_pct` (integer, optional): `cex` only. Irregularity of the split percentages.
  - `per_wallet_orders` (boolean, optional): `cex` only. One hop and one exchange order per source wallet.

#### Returns 202 Accepted

- `ok` (boolean): Always `true`.
- `id` (string): ID of the first row accepted for background execution.
- `group_id` (string): Shared by every row created from this request.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `origin.launch_ext_id required for origin.kind=launch` | `origin.kind` is `launch` but `origin.launch_ext_id` is missing. | Set `origin.launch_ext_id` to the launch's external ID. |
| 400 | `bad_request` | `source.asset=quote requires origin.kind=launch` | `source.asset` is `quote` outside a launch origin. | Use a launch origin, or withdraw the native asset. |
| 400 | `bad_request` | `source.select and source.transfers are mutually exclusive` | Both `source.select` and `source.transfers` were sent. | Send only one of `source.select` and `source.transfers`. |
| 400 | `bad_request` | `source requires either select or transfers` | Neither `source.select` nor `source.transfers` was sent. | Send `source.select` or `source.transfers`. |
| 400 | `bad_request` | `source.transfers requires payout.kind=classic` | `source.transfers` was sent with a `cex` payout. | Set `payout.kind` to `classic`, or use `source.select`. |
| 400 | `bad_request` | `source.amount and source.transfers are mutually exclusive` | A non-zero `source.amount` was sent with `source.transfers`. | Drop `source.amount` and set the amounts in `source.transfers`. |
| 400 | `bad_request` | `source.transfers amount must be > 0` | A transfer has an amount of 0. | Give every transfer an amount above 0. |
| 400 | `bad_request` | `payout.address disagrees with source.transfers[].to` | `payout.address` differs from the `to` of the transfers. | Make `payout.address` match the transfers' `to`, or omit it. |
| 400 | `bad_request` | `payout.delay_min_minutes must be <= payout.delay_max_minutes` | `payout.delay_min_minutes` is above `payout.delay_max_minutes`. | Set `payout.delay_min_minutes` no higher than `payout.delay_max_minutes`. |
| 400 | `bad_request` | `a classic payout cannot change chain or asset; use kind=cex` | A `classic` payout changes chain or asset. | Match `payout.chain` and `payout.asset` to the source, or set `payout.kind` to `cex`. |
| 400 | `bad_request` | `mixing options require payout.kind=cex` | A `classic` payout carries CEX-only options: `legs`, `providers`, `delay_min_minutes`, `delay_max_minutes`, `split_jitter_pct` or `per_wallet_orders`. | Remove those options or set `payout.kind` to `cex`. |
| 400 | `bad_request` | `dust_amount_min must be <= dust_amount_max` | `source.dust_amount_min` is above `source.dust_amount_max`. | Set `source.dust_amount_min` no higher than `source.dust_amount_max`. |
| 400 | `bad_request` | `leave_on=holders requires origin.kind=launch` | `source.leave_on` is `holders` outside a launch origin. | Use a launch origin, or another `leave_on` value. |
| 400 | `bad_request` | `payout.address is required` | `payout.address` is missing. | Set `payout.address` to the destination. |
| 400 | `bad_request` | `unknown chain: <chain>` | `payout.chain` is not a chain the API serves. | Use a `payout.chain` value listed for this endpoint. |
| 400 | `bad_request` | `invalid payout address` | `payout.address` is not a valid address of `payout.chain`. | Send a valid address of the payout chain. |
| 400 | `bad_request` | `recipient <address> is a token mint — withdrawing SOL there would burn it. Use a regular wallet address instead.` | On Solana, the destination is a token mint; sending SOL there would burn it. | Use a regular wallet address. |
| 400 | `bad_request` | `recipient <address> is a token contract — withdrawing native there would burn it. Use a regular wallet address instead.` | On EVM chains, the destination is a token contract; sending native there would burn it. | Use a regular wallet address. |
| 400 | `bad_request` | `recipient <address> refuses a native transfer (<reason>) — it is a contract with no payable receive. Use a regular wallet address instead.` | On EVM chains, the destination is a contract that refuses native transfers. | Use a regular wallet address. |
| 422 | `upstream_failure` | `rpc api issue: recipient check failed: <error>` | The destination check could not read the address from the RPC. | Retry after a short wait. |
| 422 | `unprocessable` | `launch not found` | The launch in `origin.launch_ext_id` is not on the account. Returned as a 422 here, as a 404 by the quote. | Use the external ID of one of your launches. |
| 422 | `unprocessable` | `invalid origin.launch_ext_id` | `origin.launch_ext_id` is not a valid launch external ID. Returned as a 422 here, as a 400 by the quote. | Use the external ID of one of your launches. |
| 422 | `unprocessable` | `origin.launch_ext_id is a <chain> launch, but source.chain is <chain>: origin names the launch whose wallets are drained; a launch receiving the payout goes in payout.launch_ext_id` | `origin.launch_ext_id` is a launch on another chain than `source.chain`. Returned as a 422 here, as a 400 by the quote. | Set `source.chain` to the launch's chain. |
| 422 | `unprocessable` | `origin.kind=global requires select.kind=explicit` | `origin.kind` is `global` but `source.select.kind` is not `explicit`. Returned as a 422 here, as a 400 by the quote. | Set `source.select.kind` to `explicit` and list the wallets. |
| 422 | `unprocessable` | `no source wallet eligible for withdrawal` | None of the selected wallets can be withdrawn from, for example because each is empty or already claimed by a live withdrawal. | Check the `wallets` verdicts in [Retrieve a withdraw quote](/reference/withdrawals/#retrieve-a-withdraw-quote). |
| 422 | `unprocessable` | `already withdrawing from <addresses>` | A live withdrawal is already draining these wallets. | Wait for it to settle; follow it in [List withdrawals](/reference/withdrawals/#list-withdrawals). |
| 422 | `unprocessable` | `this withdrawal cannot go through lane: a cex deposit is not one of its legs yet. Nothing was sent` | The withdrawal would go through lane, which cannot carry a CEX deposit yet. Nothing was sent. | Use a `classic` payout, or retry later. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/withdraw/execute" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "origin": {
    "kind": "aged"
  },
  "source": {
    "chain": "sol",
    "asset": "native",
    "select": {
      "kind": "explicit",
      "wallets": [
        "C31EeqtSvpjYHFQxBoP9bBTpqtUWV2avNhjdaN1yem44",
        "ART7zvRihsxp6iuCegVRED44XZMov9u6fnFJHF7HqcN4"
      ]
    },
    "mode": "withdraw_all",
    "leave_on": [],
    "amount": "0"
  },
  "payout": {
    "kind": "cex",
    "chain": "bsc",
    "asset": "native",
    "address": "0x24667d03fe6130c45584ed9985167d254fc6ab2f",
    "legs": 3,
    "delay_min_minutes": 8,
    "delay_max_minutes": 13
  }
}'
```

#### Example response

```json
{
  "ok": true,
  "id": "cc0799f5-ab8b-4bcc-83b9-805a99315190",
  "group_id": "cc0799f5-ab8b-4bcc-83b9-805a99315190"
}
```

### Retrieve a withdrawal

`GET /withdraw/{withdrawal_id}`

Returns one withdrawal row with its status, hop, collected legs and payout transaction. (Bearer JWT)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: allowed.
- Retry: Safe to retry.

#### Path parameters

- `withdrawal_id` (string, required): ID of the withdrawal row.

#### Returns 200 OK

Returns a [Withdrawal](#object-withdrawal) object.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 404 | `not_found` | `withdraw not found` | No withdrawal with this ID on the account. | Use an `id` from [List withdrawals](/reference/withdrawals/#list-withdrawals). |

#### Example request

```bash
curl "https://api-mig.proxima.tools/withdraw/684b1e4f-decd-437b-babf-4384eebb8b10" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "id": "684b1e4f-decd-437b-babf-4384eebb8b10",
  "group_id": "684b1e4f-decd-437b-babf-4384eebb8b10",
  "status": "completed",
  "origin": {
    "kind": "aged"
  },
  "src": {
    "chain": "sol",
    "asset": "native"
  },
  "dst": {
    "chain": "sol",
    "asset": "native",
    "address": "DKfba8BZznqYcPa9r2dE1oxd635exYJWuZtrefA8XyPF"
  },
  "payout_kind": "classic",
  "collected": [
    {
      "address": "C31EeqtSvpjYHFQxBoP9bBTpqtUWV2avNhjdaN1yem44",
      "amount": "1489000000",
      "tx": "4UAUY1zva1Wg1a2mBXkZLkjukpMhbSe3X43BpNL6UP9AuzGhwLh2PnsY11H3JJMjuZswyk9zA2CKiw3Lip4hTGbL"
    },
    {
      "address": "ART7zvRihsxp6iuCegVRED44XZMov9u6fnFJHF7HqcN4",
      "amount": "1000000000",
      "tx": "5K1g9bQMqoMvVUgSD92K9PUDSwmNuCpzQDU6DiEj9iBuYVDeph7qEmxrsodWFSguTfgUrZhhcZG7K3jMeSwHC2up"
    }
  ],
  "hop": {
    "address": "AqaW1YghutnQEhjycn8m26Rr4RzZuZAoaNYsFjRP5NDp",
    "landed": "2489000000"
  },
  "payout": {
    "tx": "QhdKjiybHRzvb1Z815uLe9gXfNFkWk4iXBh6sdT3YHL6pV3ohS2ZUXsXA6sDf4jS5Lwf631zbaUYeZQUCwQajkYo"
  },
  "created_at": 1793560000,
  "started_at": 1793560001,
  "finished_at": 1793560019
}
```

### List withdrawals

`GET /withdraw`

Returns the account's withdrawal rows, most recent first, with optional filters. (Bearer JWT)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: allowed.
- Retry: Safe to retry.

The web app uses it for the withdraw history and to resolve every row of an execute request.

#### Query parameters

- `origin_kind` (enum, optional): Only rows with this origin. Possible values: `launch`, `aged`, `global`.
- `launch_ext_id` (string, optional): Only rows of this launch. An unknown launch returns an empty list.
- `chain` (enum, optional): Only rows on this chain. Possible values: `sol`, `bsc`, `eth`, `base`, `robinhood`, `arc`, `xlayer`.
- `status` (enum, optional): Only rows in this status. Possible values: `draft`, `collecting`, `hop_funded`, `paying`, `settling`, `completed`, `failed`, `cancelled`.
- `limit` (integer, optional, default "50"): Maximum number of rows, from 1 to 200. The client clamps it to that range.

#### Returns 200 OK

Returns a list of [Withdrawal](#object-withdrawal) objects.

- `withdrawals` (array<object>): Withdrawal rows.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `unknown origin_kind: <origin_kind>` | `origin_kind` is not a known value. | Use an `origin_kind` value listed for this endpoint. |
| 400 | `bad_request` | `unknown status: <status>` | `status` is not a known value. | Use a `status` value listed for this endpoint. |
| 400 | `bad_request` | `unknown chain: <chain>` | `chain` is not a chain the API serves. | Use a `chain` value listed for this endpoint. |

#### Example request

```bash
curl "https://api-mig.proxima.tools/withdraw" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "withdrawals": [
    {
      "id": "684b1e4f-decd-437b-babf-4384eebb8b10",
      "group_id": "684b1e4f-decd-437b-babf-4384eebb8b10",
      "status": "completed",
      "origin": {
        "kind": "aged"
      },
      "src": {
        "chain": "sol",
        "asset": "native"
      },
      "dst": {
        "chain": "sol",
        "asset": "native",
        "address": "DKfba8BZznqYcPa9r2dE1oxd635exYJWuZtrefA8XyPF"
      },
      "payout_kind": "classic",
      "collected": [
        {
          "address": "C31EeqtSvpjYHFQxBoP9bBTpqtUWV2avNhjdaN1yem44",
          "amount": "1489000000",
          "tx": "4UAUY1zva1Wg1a2mBXkZLkjukpMhbSe3X43BpNL6UP9AuzGhwLh2PnsY11H3JJMjuZswyk9zA2CKiw3Lip4hTGbL"
        },
        {
          "address": "ART7zvRihsxp6iuCegVRED44XZMov9u6fnFJHF7HqcN4",
          "amount": "1000000000",
          "tx": "5K1g9bQMqoMvVUgSD92K9PUDSwmNuCpzQDU6DiEj9iBuYVDeph7qEmxrsodWFSguTfgUrZhhcZG7K3jMeSwHC2up"
        }
      ],
      "hop": {
        "address": "AqaW1YghutnQEhjycn8m26Rr4RzZuZAoaNYsFjRP5NDp",
        "landed": "2489000000"
      },
      "payout": {
        "tx": "QhdKjiybHRzvb1Z815uLe9gXfNFkWk4iXBh6sdT3YHL6pV3ohS2ZUXsXA6sDf4jS5Lwf631zbaUYeZQUCwQajkYo"
      },
      "created_at": 1793560000,
      "started_at": 1793560001,
      "finished_at": 1793560019
    }
  ]
}
```

### Cancel a withdrawal

`POST /withdraw/cancel/{withdrawal_id}`

Cancels a withdrawal row that is still a draft. (Bearer JWT)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. A repeat after a successful cancel returns 409 because the row is already `cancelled`.

No request body. Only a `draft` row is reversible; a classic row is created directly in `collecting`.

#### Path parameters

- `withdrawal_id` (string, required): ID of the withdrawal row.

#### Returns 200 OK

- `ok` (boolean): `true` when the row was cancelled.
- `id` (string): ID of the row.
- `status` (enum): New status: `cancelled`. Possible values: `draft`, `collecting`, `hop_funded`, `paying`, `settling`, `completed`, `failed`, `cancelled`.
- `message` (string): Human-readable result.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 404 | `not_found` | `withdraw not found` | No withdrawal with this ID on the account. | Use an `id` from [List withdrawals](/reference/withdrawals/#list-withdrawals). |
| 409 | `conflict` | `withdraw <id> is already <status>: funds may be in flight or already settled, a cancel cannot recall them` | The row is past `draft`: funds may be in flight or settled and cannot be recalled. | Follow the row with [Retrieve a withdrawal](/reference/withdrawals/#retrieve-a-withdrawal) until it settles. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/withdraw/cancel/4f9d94e0-65d2-4c21-8e36-963fe5159068" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "ok": true,
  "id": "4f9d94e0-65d2-4c21-8e36-963fe5159068",
  "status": "cancelled"
}
```
