Skip to content
API Reference

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

Withdraw from Wallets

Move the SOL held by a launch's wallets to one address, from the quote to the settled payout, without sending twice.

This guide drains the SOL from every wallet of a launch into one address you control, as the launch page of the web app does. The other sources (imported wallets, funders) use the same calls with a different origin; see step 2.

A withdrawal collects from each source wallet into an intermediate hop wallet, then pays the destination from the hop. The destination sees one transfer, whatever the number of source wallets.

You need:

  • an upgraded session token in $PROXIMA_JWT (Quickstart);
  • the launch id, here 101250846193377;
  • a destination address you control, here GK25SCapKwYLZzvequPVpAMTnCvaViJvJiajETLPyX54.

Amounts are integer strings in base units: lamports for SOL. See Amounts.

1. Check the route

List withdraw routes returns the source and destination pairs the API can pay. A classic route keeps the chain and the asset. A cex route converts through an exchange and can change both.

Terminal window
curl https://api-mig.proxima.tools/withdraw/routes \
-H "Authorization: Bearer $PROXIMA_JWT"
{
"ok": true,
"classic": [
{ "src_chain": "sol", "src_asset": "native", "dst_chain": "sol", "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" }
]
}

Keep: the payout kind. SOL to SOL is classic.

2. Quote the withdrawal

Retrieve a withdraw quote takes the exact body you will execute and moves nothing. Write the body to a file: you will send the same bytes in step 4.

Terminal window
cat > withdraw.json <<'EOF'
{
"origin": { "kind": "launch", "launch_ext_id": "101250846193377" },
"source": {
"chain": "sol",
"asset": "native",
"select": { "kind": "launch_all" },
"mode": "withdraw_all",
"leave_on": [],
"amount": "0"
},
"payout": {
"kind": "classic",
"chain": "sol",
"asset": "native",
"address": "GK25SCapKwYLZzvequPVpAMTnCvaViJvJiajETLPyX54"
}
}
EOF
curl -X POST https://api-mig.proxima.tools/withdraw/quote \
-H "Authorization: Bearer $PROXIMA_JWT" \
-H "Content-Type: application/json" \
-d @withdraw.json

"amount": "0" drains everything. Another value caps the total taken across the wallets.

{
"ok": true,
"total_src_atomic": "2500000000",
"wallets": [
{ "address": "8M4PPg4goA6dH3HTQs7kFtJwgvb3dRgNaMioaGdgGsxA", "drainable": "1412000000", "included": true },
{ "address": "6i6zd3qY5tT7d1LwhqNkQ7pNXzeaqMQP6WjpJ14273VP", "drainable": "655000000", "included": true },
{ "address": "9AaVX5b1d1q9ugSvjjG2vxbY8tMV6T8tWrDYpGAjYHU7", "drainable": "0", "included": false, "reason": "below_gas_and_leave", "needs": "1240000" },
{ "address": "AKSyicFZaZfLsoL45Jp6LcraGTDeNKQcqrhGFQHUYJf6", "drainable": "433000000", "included": true }
],
"plan": { "hop_count": 1 },
"estimated_duration_seconds": 20,
"estimated_receive_atomic": "2499980000"
}

Check three things before going on:

  • destination_refused, when present, says why the destination cannot be paid. Execute would refuse it too.
  • Each wallet with included: false is skipped, and reason says why. withdraw_in_flight means another withdrawal is already draining that wallet. needs is how much SOL the wallet lacks to pay its own fee.
  • estimated_receive_atomic is in the payout asset. It is absent when the API cannot price the route, which does not mean zero.

To withdraw from other wallets, change origin and select the way the app does:

Sourceoriginsource.select
A launch’s wallets{ "kind": "launch", "launch_ext_id": "…" }{ "kind": "launch_all" }, or explicit
Imported wallets{ "kind": "aged" }{ "kind": "explicit", "wallets": ["…"] }
Funders{ "kind": "global" }{ "kind": "explicit", "wallets": ["…"] }

Keep: the addresses with included: true.

3. Pin the wallets

When the quote reports wallets that cannot pay their fees (needs), the app replaces select with an explicit list of the included wallets before executing. Execute then acts on the wallets you reviewed, and not on whatever the selection resolves to a few seconds later.

"select": {
"kind": "explicit",
"wallets": [
"8M4PPg4goA6dH3HTQs7kFtJwgvb3dRgNaMioaGdgGsxA",
"6i6zd3qY5tT7d1LwhqNkQ7pNXzeaqMQP6WjpJ14273VP",
"AKSyicFZaZfLsoL45Jp6LcraGTDeNKQcqrhGFQHUYJf6"
]
}

Save the change in withdraw.json. From here on, do not edit the file.

Keep: withdraw.json, byte for byte.

4. Execute

Execute a withdrawal validates the body and creates the withdrawal. It answers 202 while the transfers run in the background.

Terminal window
curl -X POST https://api-mig.proxima.tools/withdraw/execute \
-H "Authorization: Bearer $PROXIMA_JWT" \
-H "Content-Type: application/json" \
-d @withdraw.json
{ "ok": true, "id": "44fe5946-76d4-460b-8e6b-db90af5ee652", "group_id": "44fe5946-76d4-460b-8e6b-db90af5ee652" }

Keep: id and group_id.

When a second factor is required

If the account protects wallet.withdraw, the first call answers 401 with code: "2fa_required" and moves nothing. The check is skipped when every destination is one of your registered funders on the payout chain.

{
"ok": false,
"code": "2fa_required",
"message": "2fa challenge required",
"twoFaAlgoId": "a98dee99-b8f2-4bd9-9b87-88b5b6c64f1a",
"method": "totp",
"label": "wallet.withdraw"
}

Send the same file again with the answer in headers. The challenge is bound to a hash of the body, expires after five minutes and works once. See Two-factor step-up for wallet signatures and backup codes.

Terminal window
curl -X POST https://api-mig.proxima.tools/withdraw/execute \
-H "Authorization: Bearer $PROXIMA_JWT" \
-H "Content-Type: application/json" \
-H "X-2FA-Algo-Id: a98dee99-b8f2-4bd9-9b87-88b5b6c64f1a" \
-H "X-2FA-Response: 482913" \
-d @withdraw.json

5. Find every row

One execute can create several withdrawal rows that share a group_id. This happens with one row per destination when source.transfers names several recipients, or one row per wallet with a cex payout and per_wallet_orders.

  • If id equals group_id, there is one row, and its id is id.
  • Otherwise, call List withdrawals and keep the rows whose group_id matches.
Terminal window
curl "https://api-mig.proxima.tools/withdraw?launch_ext_id=101250846193377&limit=200" \
-H "Authorization: Bearer $PROXIMA_JWT"

Keep: the id of each row.

6. Follow each row until it is terminal

Poll Retrieve a withdrawal every second until status is completed, failed or cancelled. A classic withdrawal goes collecting, hop_funded, then completed. A cex withdrawal adds paying and settling.

Terminal window
curl https://api-mig.proxima.tools/withdraw/44fe5946-76d4-460b-8e6b-db90af5ee652 \
-H "Authorization: Bearer $PROXIMA_JWT"

While it runs:

{
"id": "44fe5946-76d4-460b-8e6b-db90af5ee652",
"group_id": "44fe5946-76d4-460b-8e6b-db90af5ee652",
"status": "collecting",
"origin": { "kind": "launch", "launch_ext_id": "101250846193377" },
"src": { "chain": "sol", "asset": "native" },
"dst": { "chain": "sol", "asset": "native", "address": "GK25SCapKwYLZzvequPVpAMTnCvaViJvJiajETLPyX54" },
"payout_kind": "classic",
"collected": [
{ "address": "8M4PPg4goA6dH3HTQs7kFtJwgvb3dRgNaMioaGdgGsxA", "amount": "1412000000", "tx": "3jHysd8FQDH96nh4rwTa5mvNc4iJqpnbfwX5JprNfMu11knLZsjEBEak89SaiSBPByMUmmSdjfeDW9em6o23qrUP" }
],
"awaiting": [
{ "address": "6i6zd3qY5tT7d1LwhqNkQ7pNXzeaqMQP6WjpJ14273VP", "tx": "4Es8NYqYh6RMxBu4QoqdWBH9qBAYi728uPUJPdHGeE2DLm1EDb7vpYsUAzgDgkrFk6gcmAeSLLtYR3ZPVEH13iGX" }
],
"hop": { "address": "4xzNFidgfTahziM2qyvmswto5ABZ4PXyYzFPhuErarVx" },
"payout": {},
"created_at": 1793671200,
"started_at": 1793671201
}

Once it is done:

{
"id": "44fe5946-76d4-460b-8e6b-db90af5ee652",
"status": "completed",
"collected": [ "… three entries …" ],
"hop": { "address": "4xzNFidgfTahziM2qyvmswto5ABZ4PXyYzFPhuErarVx", "landed": "2500000000" },
"payout": { "tx": "655UrHeo364qmaCcVmKmvLjF4CbwuQSPWVg1ZrkCiG9UKy1ZUh6oTwoLTqCWgSBUEk4num8fFEzzpQYMHatRKfKv" },
"finished_at": 1793671219
}
FieldMeaning
collectedLegs confirmed into the hop, with the amount and transaction of each.
awaitingLegs sent but not yet confirmed. They are on the wire: wait for them.
hop.landedWhat reached the hop.
payout.txThe transaction that paid the destination.
errorWhy a failed row stopped.
repatriationOn a failed row, the transfer that sent the hop’s balance back (tx, to, amount).

Keep: payout.tx as the proof of payment.

Avoid sending twice

Execute has no idempotency key. These rules come from how the API and the web app behave.

  • One request at a time. Block a second submit while the first call is pending. The app does this on its confirm button.
  • Wallets already in flight are locked. While a withdrawal is running, its wallets are excluded from any new withdrawal on the same chain. A quote shows them with reason: "withdraw_in_flight". An execute that only names such wallets answers 422 with already withdrawing from <addresses> or no source wallet eligible for withdrawal.
  • The lock ends with the row. Once the first withdrawal is terminal, the same body runs again on what is left. With "amount": "0", that is usually dust or new deposits. With a fixed amount, it moves that amount a second time.
  • After a timeout or a 5xx, look before you resend. List recent rows and look for one with the same destination created in the last few minutes. If you find it, follow it (step 6). If not, quote again: a wallet marked withdraw_in_flight means the first call went through.
Terminal window
curl "https://api-mig.proxima.tools/withdraw?launch_ext_id=101250846193377&limit=20" \
-H "Authorization: Bearer $PROXIMA_JWT"

Next steps