Skip to content
API Reference

Search is only available in production builds. Try building and previewing the site to test it out locally.

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, quote the exact body to see what each wallet can give, then execute 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 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.

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

Attributes

  • 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 draftcollectinghop_fundedpayingsettlingcompletedfailedcancelled
  • origin object
    Origin of the request.
    Child attributes 2
    • kind enum
      Origin kind.
      Possible values launchagedglobal
    • launch_ext_id string
      Launch ID, for a launch origin.
  • src object
    Source chain and asset.
    Child attributes 2
    • chain enum
      Source chain.
      Possible values solbscethbaserobinhoodarcxlayer
    • asset string
      Source asset.
  • dst object
    Destination.
    Child attributes 3
    • chain enum
      Destination chain.
      Possible values solbscethbaserobinhoodarcxlayer
    • asset string
      Destination asset.
    • address string
      Address credited by the payout.
  • payout_kind enum
    Payout kind.
    Possible values classiccex
  • collected array<object>
    Collection transfers made from the source wallets.
    Child attributes 3
    • 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.
    Child attributes 2
    • 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.
    Child attributes 1
    • 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.
GET /withdraw/routes

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

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.

Parameters

No parameters.

Returns 200 OK · application/json

  • ok boolean
    Always true.
  • classic array<object>
    Classic routes.
    Child attributes 4
    • src_chain enum
      Source chain.
      Possible values solbscethbaserobinhoodarcxlayer
    • src_asset string
      Source asset.
    • dst_chain enum
      Destination chain.
      Possible values solbscethbaserobinhoodarcxlayer
    • dst_asset string
      Destination asset.
  • cex array<object>
    CEX routes.
    Child attributes 7
    • src_chain enum
      Source chain.
      Possible values solbscethbaserobinhoodarcxlayer
    • src_asset string
      Source asset.
    • dst_chain enum
      Destination chain.
      Possible values solbscethbaserobinhoodarcxlayer
    • 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.

Errors

Only the common errors: 401 for a missing or expired session or a base token (license_required) and 429 when rate limited.

Web client proxima.withdraw.getRoutes() src/lib/proxima/endpoints/withdraw.ts

POST /withdraw/quote

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

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. The web app calls it debounced while the user edits a withdraw form, and aborts stale calls.

Body parameters application/json

  • origin object Required
    Universe of wallets the source draws from.
    Child attributes 2
    • 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 launchagedglobal
    • 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.
    Child attributes 15
    • chain enum Required
      Chain the funds are taken from.
      Possible values solbscethbaserobinhoodarcxlayer
    • 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.
      Child attributes 2
      • kind enum Required
        explicit lists wallets; aged takes the trading wallets of the origin; launch_all takes every wallet of the origin.
        Possible values explicitagedlaunch_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_allleave_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.
      Child attributes 3
      • 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.
    Child attributes 10
    • 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 classiccex
    • chain enum Required
      Destination chain. Must equal source.chain for classic.
      Possible values solbscethbaserobinhoodarcxlayer
    • 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 · application/json

  • 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.
    Child attributes 5
    • 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_leavecap_reachednot_foundwatched_no_secretblocked_accountinvalid_addressholder_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.
    Child attributes 1
    • 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

StatusCodeWhen and what to do
400 bad_request 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 is quote outside a launch origin. Use a launch origin, or withdraw the native asset.
400 bad_request Both source.select and source.transfers were sent. Send only one of source.select and source.transfers.
400 bad_request Neither source.select nor source.transfers was sent. Send source.select or source.transfers.
400 bad_request source.transfers was sent with a cex payout. Set payout.kind to classic, or use source.select.
400 bad_request A non-zero source.amount was sent with source.transfers. Drop source.amount and set the amounts in source.transfers.
400 bad_request A transfer has an amount of 0. Give every transfer an amount above 0.
400 bad_request 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 is above payout.delay_max_minutes. Set payout.delay_min_minutes no higher than payout.delay_max_minutes.
400 bad_request 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 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 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 source.leave_on is holders outside a launch origin. Use a launch origin, or another leave_on value.
400 bad_request source.chain is not a chain the API serves. Use a source.chain value listed for this endpoint.
404 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 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 launch on another chain than source.chain. Set source.chain to the launch's chain.
400 bad_request origin.kind is global but source.select.kind is not explicit. Set source.select.kind to explicit and list the wallets.

Also the common errors: 401 for a missing or expired session or a base token (license_required), 403 read_only_token and 429 when rate limited.

Web client proxima.withdraw.quote(request) src/lib/proxima/endpoints/withdraw.ts

POST /withdraw/execute

Starts a withdrawal and returns once its rows are persisted.

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. How it works
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 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 every second until each row is terminal.

Body parameters application/json

  • origin object Required
    Universe of wallets the source draws from.
    Child attributes 2
    • 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 launchagedglobal
    • 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.
    Child attributes 15
    • chain enum Required
      Chain the funds are taken from.
      Possible values solbscethbaserobinhoodarcxlayer
    • 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.
      Child attributes 2
      • kind enum Required
        explicit lists wallets; aged takes the trading wallets of the origin; launch_all takes every wallet of the origin.
        Possible values explicitagedlaunch_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_allleave_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.
      Child attributes 3
      • 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.
    Child attributes 10
    • 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 classiccex
    • chain enum Required
      Destination chain. Must equal source.chain for classic.
      Possible values solbscethbaserobinhoodarcxlayer
    • 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 · application/json

  • 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

StatusCodeWhen and what to do
400 bad_request 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 is quote outside a launch origin. Use a launch origin, or withdraw the native asset.
400 bad_request Both source.select and source.transfers were sent. Send only one of source.select and source.transfers.
400 bad_request Neither source.select nor source.transfers was sent. Send source.select or source.transfers.
400 bad_request source.transfers was sent with a cex payout. Set payout.kind to classic, or use source.select.
400 bad_request A non-zero source.amount was sent with source.transfers. Drop source.amount and set the amounts in source.transfers.
400 bad_request A transfer has an amount of 0. Give every transfer an amount above 0.
400 bad_request 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 is above payout.delay_max_minutes. Set payout.delay_min_minutes no higher than payout.delay_max_minutes.
400 bad_request 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 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 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 source.leave_on is holders outside a launch origin. Use a launch origin, or another leave_on value.
400 bad_request payout.address is missing. Set payout.address to the destination.
400 bad_request payout.chain is not a chain the API serves. Use a payout.chain value listed for this endpoint.
400 bad_request payout.address is not a valid address of payout.chain. Send a valid address of the payout chain.
400 bad_request On Solana, the destination is a token mint; sending SOL there would burn it. Use a regular wallet address.
400 bad_request On EVM chains, the destination is a token contract; sending native there would burn it. Use a regular wallet address.
400 bad_request On EVM chains, the destination is a contract that refuses native transfers. Use a regular wallet address.
422 upstream_failure The destination check could not read the address from the RPC. Retry after a short wait.
422 unprocessable 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 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 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 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 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.
422 unprocessable A live withdrawal is already draining these wallets. Wait for it to settle; follow it in List withdrawals.
422 unprocessable The withdrawal would go through lane, which cannot carry a CEX deposit yet. Nothing was sent. Use a classic payout, or retry later.

Also the common errors: 401 for a missing or expired session or a base token (license_required), 403 read_only_token, 401 2fa_required and 429 when rate limited.

Web client proxima.withdraw.execute(request) src/lib/proxima/endpoints/withdraw.ts

GET /withdraw/{withdrawal_id}

Returns one withdrawal row with its status, hop, collected legs and payout transaction.

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.
    Example684b1e4f-decd-437b-babf-4384eebb8b10

Returns 200 OK · application/json

Returns a Withdrawal object.

Errors

StatusCodeWhen and what to do
404 not_found No withdrawal with this ID on the account. Use an id from List withdrawals.

Also the common errors: 401 for a missing or expired session or a base token (license_required) and 429 when rate limited.

Web client proxima.withdraw.getOne(id) src/lib/proxima/endpoints/withdraw.ts

List withdrawals

Bearer JWT
GET /withdraw

Returns the account's withdrawal rows, most recent first, with optional filters.

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 launchagedglobal
  • 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 solbscethbaserobinhoodarcxlayer
  • status enum Optional
    Only rows in this status.
    Possible values draftcollectinghop_fundedpayingsettlingcompletedfailedcancelled
  • limit integer Optional Default 50
    Maximum number of rows, from 1 to 200. The client clamps it to that range.

Returns 200 OK · application/json

Returns a list of Withdrawal objects.

  • withdrawals array<object>
    Withdrawal rows.

Errors

StatusCodeWhen and what to do
400 bad_request origin_kind is not a known value. Use an origin_kind value listed for this endpoint.
400 bad_request status is not a known value. Use a status value listed for this endpoint.
400 bad_request chain is not a chain the API serves. Use a chain value listed for this endpoint.

Also the common errors: 401 for a missing or expired session or a base token (license_required) and 429 when rate limited.

Web client proxima.withdraw.list(query?) src/lib/proxima/endpoints/withdraw.ts

Cancel a withdrawal

Bearer JWT
POST /withdraw/cancel/{withdrawal_id}

Cancels a withdrawal row that is still a draft.

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.
    Example4f9d94e0-65d2-4c21-8e36-963fe5159068

Returns 200 OK · application/json

  • ok boolean
    true when the row was cancelled.
  • id string
    ID of the row.
  • status enum
    New status: cancelled.
    Possible values draftcollectinghop_fundedpayingsettlingcompletedfailedcancelled
  • message string
    Human-readable result.

Errors

StatusCodeWhen and what to do
404 not_found No withdrawal with this ID on the account. Use an id from List withdrawals.
409 conflict The row is past draft: funds may be in flight or settled and cannot be recalled. Follow the row with Retrieve a withdrawal until it settles.

Also the common errors: 401 for a missing or expired session or a base token (license_required), 403 read_only_token and 429 when rate limited.

Web client proxima.withdraw.cancel(id) src/lib/proxima/endpoints/withdraw.ts