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.
The Withdrawal object
One withdrawal row: one destination with its own hop. A request with several destinations creates several rows sharing a group_id.
Attributes
-
idstringWithdrawal ID (UUID). -
group_idstringShared by every row created from the same execute request. -
statusenumProgress of the row.completed,failedandcancelledare terminal.Possible valuesdraftcollectinghop_fundedpayingsettlingcompletedfailedcancelled -
originobjectOrigin of the request.Child attributes 2
-
kindenumOrigin kind.Possible valueslaunchagedglobal -
launch_ext_idstringLaunch ID, for a launch origin.
-
-
srcobjectSource chain and asset.Child attributes 2
-
chainenumSource chain.Possible valuessolbscethbaserobinhoodarcxlayer -
assetstringSource asset.
-
-
dstobjectDestination.Child attributes 3
-
chainenumDestination chain.Possible valuessolbscethbaserobinhoodarcxlayer -
assetstringDestination asset. -
addressstringAddress credited by the payout.
-
-
payout_kindenumPayout kind.Possible valuesclassiccex -
collectedarray<object>Collection transfers made from the source wallets.Child attributes 3
-
addressstringSource wallet. -
amountstringAtomic units collected. Preserved as a string by the client because atomic amounts can exceed the JavaScript safe integer range. -
txstringTransaction hash or signature.
-
-
hopobjectIntermediate wallet the funds are collected into before the payout.Child attributes 2
-
addressstringHop address. -
landedstringAtomic units received by the hop. Preserved as a string by the client because atomic amounts can exceed the JavaScript safe integer range.
-
-
payoutobjectPayout progress.Child attributes 1
-
txstringPayout transaction.
-
-
errorstringFailure reason, whenstatusisfailed. -
created_atintegerUnix timestamp (seconds, UTC) at which the row was created. -
started_atintegerUnix timestamp (seconds) at which processing started. -
finished_atintegerUnix timestamp (seconds) at which the row reached a terminal status.
List withdraw routes
/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
-
okbooleanAlwaystrue. -
classicarray<object>Classic routes.Child attributes 4
-
src_chainenumSource chain.Possible valuessolbscethbaserobinhoodarcxlayer -
src_assetstringSource asset. -
dst_chainenumDestination chain.Possible valuessolbscethbaserobinhoodarcxlayer -
dst_assetstringDestination asset.
-
-
cexarray<object>CEX routes.Child attributes 7
-
src_chainenumSource chain.Possible valuessolbscethbaserobinhoodarcxlayer -
src_assetstringSource asset. -
dst_chainenumDestination chain.Possible valuessolbscethbaserobinhoodarcxlayer -
dst_assetstringDestination asset. -
providersarray<string>Exchanges that can serve the route. -
husher_onlybooleanWhether Husher liquidity is the only option (always onrobinhood). -
indicative_min_src_atomicstringIndicative minimum in source atomic units; omitted when it cannot be computed. Use it for sorting only and gate on the quote'sneeds. 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
Retrieve a withdraw quote
/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
-
originobject RequiredUniverse of wallets the source draws from.Child attributes 2
-
kindenum Requiredlaunch: the wallets of a launch.aged: your trading wallets.global: any wallet of the account named explicitly (requiressource.select.kindexplicit), for example a funder.Possible valueslaunchagedglobal -
launch_ext_idstring OptionalLaunch ID. Required whenkindislaunch.
-
-
sourceobject RequiredWhich wallets to drain and how much. Use eitherselectortransfers, never both.Child attributes 15
-
chainenum RequiredChain the funds are taken from.Possible valuessolbscethbaserobinhoodarcxlayer -
assetstring Requirednative, a token mint or contract address, orquote(the launch's quote token; requiresorigin.kindlaunch). Never a symbol. -
selectobject OptionalWallet selection inside the origin.Child attributes 2
-
kindenum Requiredexplicitlists wallets;agedtakes the trading wallets of the origin;launch_alltakes every wallet of the origin.Possible valuesexplicitagedlaunch_all -
walletsarray<string> OptionalAddresses to drain. Required whenkindisexplicit.
-
-
modeenum OptionalRequired withselect.leave_onkeeps the wallets of the roles inleave_onfull.Possible valueswithdraw_allleave_on -
leave_onarray<string> OptionalRequired withselect(may be empty). Roles left untouched:dev,aged,funder,others,holders(holdersrequiresorigin.kindlaunch). -
amountstring OptionalRequired withselect. 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_amountstring OptionalAtomic units left behind in each wallet. -
dust_amount_minstring OptionalLower bound of a random amount left behind per wallet. At mostdust_amount_max. -
dust_amount_maxstring OptionalUpper bound of a random amount left behind per wallet. -
transfersarray<object> OptionalManual per-wallet transfers, instead ofselect. Requirespayout.kindclassic. Each distincttobecomes its own row.Child attributes 3
-
fromstring RequiredSource wallet. -
tostring RequiredDestination address. -
amountstring RequiredAtomic-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.
-
-
-
payoutobject RequiredWhere and how the funds are delivered.Child attributes 10
-
kindenum Requiredclassicdelivers the same asset on the same chain.cexgoes through an exchange and can change chain and asset.Possible valuesclassiccex -
chainenum RequiredDestination chain. Must equalsource.chainforclassic.Possible valuessolbscethbaserobinhoodarcxlayer -
assetstring RequiredDestination asset, same format assource.asset. Must equalsource.assetforclassic. -
addressstring OptionalDestination address. Required to execute unlesssource.transfersis used; if sent withtransfers, it must match everyto. -
providersarray<string> Optionalcexonly. Restricts the exchange pool. -
legsinteger Optionalcexonly. Number of legs the payout is split into. -
delay_min_minutesinteger Optionalcexonly. Minimum gap between two consecutive legs, in minutes. -
delay_max_minutesinteger Optionalcexonly. Maximum gap between two consecutive legs, in minutes. At leastdelay_min_minutes. -
split_jitter_pctinteger Optionalcexonly. Irregularity of the split percentages. -
per_wallet_ordersboolean Optionalcexonly. One hop and one exchange order per source wallet.
-
Returns 200 OK · application/json
-
okbooleanAlwaystrue. -
total_src_atomicstringMaximum 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. -
walletsarray<object>Per-wallet breakdown.Child attributes 5
-
addressstringWallet address. -
drainablestringAtomic units this wallet can give. Preserved as a string by the client because atomic amounts can exceed the JavaScript safe integer range. -
includedbooleanWhether the wallet takes part. -
reasonenumWhy the wallet is excluded.Possible valuesbelow_gas_and_leavecap_reachednot_foundwatched_no_secretblocked_accountinvalid_addressholder_status_unknown -
needsstringShortfall 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.
-
-
planobjectExecution plan.Child attributes 1
-
hop_countinteger1, or the number of distinct destinations intransfersmode.
-
-
estimated_duration_secondsintegerExpected time until the destination is credited, including CEX leg delays. -
estimated_receive_atomicstringWhat the destination receives net of fees, in atomic units ofpayout.assetonpayout.chain(not the same scale astotal_src_atomicon 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_atomicstringCEX only. Binding source-side order minimum, in atomic units. -
needs_src_atomicstringCEX only. Aggregate shortfall against the order minimum after fees, in atomic units.
Errors
| Status | Code | When 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
Execute a withdrawal
/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.withdrawwhen 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_idfilter, so matchgroup_idon 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
-
originobject RequiredUniverse of wallets the source draws from.Child attributes 2
-
kindenum Requiredlaunch: the wallets of a launch.aged: your trading wallets.global: any wallet of the account named explicitly (requiressource.select.kindexplicit), for example a funder.Possible valueslaunchagedglobal -
launch_ext_idstring OptionalLaunch ID. Required whenkindislaunch.
-
-
sourceobject RequiredWhich wallets to drain and how much. Use eitherselectortransfers, never both.Child attributes 15
-
chainenum RequiredChain the funds are taken from.Possible valuessolbscethbaserobinhoodarcxlayer -
assetstring Requirednative, a token mint or contract address, orquote(the launch's quote token; requiresorigin.kindlaunch). Never a symbol. -
selectobject OptionalWallet selection inside the origin.Child attributes 2
-
kindenum Requiredexplicitlists wallets;agedtakes the trading wallets of the origin;launch_alltakes every wallet of the origin.Possible valuesexplicitagedlaunch_all -
walletsarray<string> OptionalAddresses to drain. Required whenkindisexplicit.
-
-
modeenum OptionalRequired withselect.leave_onkeeps the wallets of the roles inleave_onfull.Possible valueswithdraw_allleave_on -
leave_onarray<string> OptionalRequired withselect(may be empty). Roles left untouched:dev,aged,funder,others,holders(holdersrequiresorigin.kindlaunch). -
amountstring OptionalRequired withselect. 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_amountstring OptionalAtomic units left behind in each wallet. -
dust_amount_minstring OptionalLower bound of a random amount left behind per wallet. At mostdust_amount_max. -
dust_amount_maxstring OptionalUpper bound of a random amount left behind per wallet. -
transfersarray<object> OptionalManual per-wallet transfers, instead ofselect. Requirespayout.kindclassic. Each distincttobecomes its own row.Child attributes 3
-
fromstring RequiredSource wallet. -
tostring RequiredDestination address. -
amountstring RequiredAtomic-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.
-
-
-
payoutobject RequiredWhere and how the funds are delivered.Child attributes 10
-
kindenum Requiredclassicdelivers the same asset on the same chain.cexgoes through an exchange and can change chain and asset.Possible valuesclassiccex -
chainenum RequiredDestination chain. Must equalsource.chainforclassic.Possible valuessolbscethbaserobinhoodarcxlayer -
assetstring RequiredDestination asset, same format assource.asset. Must equalsource.assetforclassic. -
addressstring OptionalDestination address. Required to execute unlesssource.transfersis used; if sent withtransfers, it must match everyto. -
providersarray<string> Optionalcexonly. Restricts the exchange pool. -
legsinteger Optionalcexonly. Number of legs the payout is split into. -
delay_min_minutesinteger Optionalcexonly. Minimum gap between two consecutive legs, in minutes. -
delay_max_minutesinteger Optionalcexonly. Maximum gap between two consecutive legs, in minutes. At leastdelay_min_minutes. -
split_jitter_pctinteger Optionalcexonly. Irregularity of the split percentages. -
per_wallet_ordersboolean Optionalcexonly. One hop and one exchange order per source wallet.
-
Returns 202 Accepted · application/json
-
okbooleanAlwaystrue. -
idstringID of the first row accepted for background execution. -
group_idstringShared by every row created from this request.
Errors
| Status | Code | When 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
Retrieve a withdrawal
/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_idstring RequiredID of the withdrawal row.Example684b1e4f-decd-437b-babf-4384eebb8b10
Returns 200 OK · application/json
Returns a Withdrawal object.
Errors
| Status | Code | When 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
/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_kindenum OptionalOnly rows with this origin.Possible valueslaunchagedglobal -
launch_ext_idstring OptionalOnly rows of this launch. An unknown launch returns an empty list. -
chainenum OptionalOnly rows on this chain.Possible valuessolbscethbaserobinhoodarcxlayer -
statusenum OptionalOnly rows in this status.Possible valuesdraftcollectinghop_fundedpayingsettlingcompletedfailedcancelled -
limitinteger OptionalMaximum 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.
-
withdrawalsarray<object>Withdrawal rows.
Errors
| Status | Code | When 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
/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_idstring RequiredID of the withdrawal row.Example4f9d94e0-65d2-4c21-8e36-963fe5159068
Returns 200 OK · application/json
-
okbooleantruewhen the row was cancelled. -
idstringID of the row. -
statusenumNew status:cancelled.Possible valuesdraftcollectinghop_fundedpayingsettlingcompletedfailedcancelled -
messagestringHuman-readable result.
Errors
| Status | Code | When 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