Cleanup
Move a launch's tokens from one set of its wallets to another over randomized rounds.
Cleanup moves the launch's token from input wallets (sellers) to output wallets (buyers) in rounds separated by a random delay. On Solana the tokens move through an on-chain buyback by default, or through a Streamflow airdrop; EVM launches name their wallets with input_addresses and output_addresses.
The web app polls the status endpoint every 5 seconds.
On an EVM multi-launch container, the session endpoints answer 400 (multi-launch container: sessions run on the winner launch once it resolves); call them on the winning launch instead.
The Cleanup status object
The launch's Cleanup session and its progress.
Attributes
-
statusenumSession state. The client also accepts lowercase values.Possible valuesNonePlannedRunningCompletedCancelledFailed -
infoobjectSession details. Absent whenstatusisNone.Child attributes 6
-
paramsobjectThe parameters the session was started with. -
started_atinteger | nullUnix timestamp (seconds) the session started. -
ended_atinteger | nullUnix timestamp (seconds) the session ended. -
status_reasonstring | nullWhy the session ended or failed, when known. -
rounds_completedintegerRounds completed. -
rounds_totalintegerRounds planned.
-
Start a Cleanup session
/launch/cleanup/run/{launch_id} Starts moving tokens from the input wallets to the output wallets.
- Token
- Upgraded session token, bound to a license.
- Read-only tokens
- Refused with
403 read_only_token. - Retry
- Check before retrying Read Retrieve Cleanup status first:
Runningmeans the first call went through, and a second run is refused while it runs. On EVM a failed call may already have topped up wallets from the funder; a repeat only tops up what is still short.
The launch must be live. Delays must lie within 500–300000 ms with min_delay_ms not above max_delay_ms, and double_buy_pct within 0–100. On EVM, before the session opens, the funder tops up every wallet short of gas for its rounds; the call fails without starting a session if the funder cannot cover them all.
Path parameters
-
launch_idstring RequiredLaunch ID: the 15-digit chain-encoded ID. Its first three digits name the chain (101Solana,201BSC,202Base,204Ethereum).Example101000000004217
Body parameters application/json
-
input_wallet_pubkeysarray<string> OptionalSolana: wallets whose tokens are moved out (sellers). Required on Solana. -
output_wallet_pubkeysarray<string> OptionalSolana: wallets that receive the tokens (buyers). Required on Solana. -
input_addressesarray<string> OptionalEVM: wallets whose tokens are moved out. Required on EVM chains. -
output_addressesarray<string> OptionalEVM: wallets that receive the tokens. Required on EVM chains. -
min_delay_msinteger RequiredMinimum delay between rounds in milliseconds (500–300000). -
max_delay_msinteger RequiredMaximum delay between rounds in milliseconds, at leastmin_delay_msand at most 300000. -
methodenum OptionalSolana: how tokens move.buybacksells input tokens to the output wallets through an on-chain buyback;streamflow_airdropdistributes them through a Streamflow airdrop. EVM accepts onlybuyback.Possible valuesbuybackstreamflow_airdrop -
double_buy_pctinteger OptionalSolana,buybackonly: double-buy percentage, 0–100. EVM refuses any value other than 0. -
fake_tip_pctinteger OptionalTyped by the web client but ignored on Solana, whose request has no such field. EVM refuses any value other than 0.
Returns 200 OK · application/json
Returns ok and a confirmation message.
-
okbooleanAlwaystrueon success. -
messagestringHuman-readable confirmation.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | launch_id is not a chain-encoded launch ID. Pass the 15-digit chain-encoded launch ID exactly as the API returned it. |
| 404 | not_found | No launch with this ID belongs to the license in your token. Check the launch ID and that your token is upgraded onto the license that owns the launch. |
| 400 | bad_request | EVM: launch_id is a multi-launch group container. This route loads the launch itself, so it answers with the launch-level wording rather than the session one. Call it with the winning member's launch ID once the group resolves. |
| 400 | bad_request | The body is not valid JSON, or a field is missing or has the wrong type. Fix the field named in message and send the request again. |
| 400 | bad_request | A required top-level field is missing, e.g. Solana input_wallet_pubkeys sent to an EVM launch, which expects input_addresses, or the reverse. Send the wallet fields that match the launch chain: input_wallet_pubkeys/output_wallet_pubkeys on Solana, input_addresses/output_addresses on EVM. |
| 500 | internal_error | Solana: the token is still a draft. EVM answers 400 bad_request with token not launched. Launch the token first with Launch a token. |
| 400 | bad_request | EVM: the token is still a draft. The token must be launched before a cleanup starts. Launch the token first with Launch a token. |
| 400 | bad_request | EVM: a Cleanup session is already running for this launch. Solana sends the same message with 500 internal_error. Wait for it to end or stop it with Cancel a Cleanup session first. |
| 400 | bad_request | min_delay_ms is outside 500–300000. Solana sends the same message with 500 internal_error. Set min_delay_ms between 500 and 300000. |
| 400 | bad_request | max_delay_ms is below min_delay_ms or above 300000. Solana sends the same message with 500 internal_error. Set max_delay_ms between min_delay_ms and 300000. |
| 400 | bad_request | EVM: no input wallet holds the token. Solana sends the same message with 500 internal_error. List input wallets that hold the token. |
| 500 | internal_error | Solana: input_wallet_pubkeys is empty. List at least one input wallet. |
| 500 | internal_error | Solana: output_wallet_pubkeys is empty. List at least one output wallet. |
| 500 | internal_error | Solana: double_buy_pct is above 100. Set double_buy_pct between 0 and 100. |
| 500 | internal_error | Solana: an entry of input_wallet_pubkeys is not a valid Solana address. Correct or remove the malformed input address. |
| 500 | internal_error | Solana: an entry of output_wallet_pubkeys is not a valid Solana address. Correct or remove the malformed output address. |
| 500 | internal_error | Solana: an input wallet is neither a launch wallet nor one of the license's wallets. List only wallets of this launch or license. |
| 500 | internal_error | Solana: an output wallet is neither a launch wallet nor one of the license's wallets. List only wallets of this launch or license. |
| 422 | unprocessable | Solana, buyback: every input wallet holding tokens is short of the SOL its sell needs. Fund the input wallets with SOL, then start again. |
| 422 | unprocessable | Solana, buyback: every output wallet is short of the SOL its buy needs. Fund the output wallets with SOL, then start again. |
| 400 | bad_request | EVM: input_addresses is empty. List at least one input wallet. |
| 400 | bad_request | EVM: output_addresses is empty. List at least one output wallet. |
| 400 | bad_request | EVM: method is set to something other than buyback. Omit method or send buyback. |
| 400 | bad_request | EVM: double_buy_pct is above 0. Omit double_buy_pct or send 0. |
| 400 | bad_request | EVM: fake_tip_pct is above 0. Omit fake_tip_pct or send 0. |
| 400 | bad_request | EVM: the launch's platform has no cleanup. Move the tokens with Transfer tokens instead. |
| 400 | bad_request | EVM: a listed address is neither a launch wallet nor one of the license's wallets. List only wallets of this launch or license. |
| 400 | bad_request | EVM: the funder cannot cover the gas top-ups the rounds need plus its own reserve. Nothing was sent. Fund the launch funder with at least the amount named in message, then start again. |
| 400 | bad_request | EVM: after the funder topped up the wallets, some are still short of gas. The top-ups already sent stay on the wallets. Fund the wallets named in message, then start again. |
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.launch.cleanup.runCleanup(launchId, params) src/lib/proxima/endpoints/launch/cleanup.ts
Retrieve Cleanup status
/launch/cleanup/status/{launch_id} Returns the launch's Cleanup session and its progress.
- Token
- Upgraded session token, bound to a license.
- Read-only tokens
- Allowed.
- Retry
- Safe to retry
Path parameters
-
launch_idstring RequiredLaunch ID: the 15-digit chain-encoded ID. Its first three digits name the chain (101Solana,201BSC,202Base,204Ethereum).Example101000000004217
Returns 200 OK · application/json
Returns a Cleanup status object.
-
statusenumSession state. The client also accepts lowercase values.Possible valuesNonePlannedRunningCompletedCancelledFailed -
infoobjectSession details. Absent whenstatusisNone.Child attributes 6
-
paramsobjectThe parameters the session was started with. -
started_atinteger | nullUnix timestamp (seconds) the session started. -
ended_atinteger | nullUnix timestamp (seconds) the session ended. -
status_reasonstring | nullWhy the session ended or failed, when known. -
rounds_completedintegerRounds completed. -
rounds_totalintegerRounds planned.
-
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | launch_id is not a chain-encoded launch ID. Pass the 15-digit chain-encoded launch ID exactly as the API returned it. |
| 404 | not_found | No launch with this ID belongs to the license in your token. Check the launch ID and that your token is upgraded onto the license that owns the launch. |
| 400 | bad_request | launch_id is a multi-launch group container; sessions run on the winning member launch. Call it with the winning member's launch ID once the group resolves. |
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.launch.cleanup.getCleanupStatus(launchId) src/lib/proxima/endpoints/launch/cleanup.ts
Cancel a Cleanup session
/launch/cleanup/cancel/{launch_id} Stops the launch's running Cleanup session.
- Token
- Upgraded session token, bound to a license.
- Read-only tokens
- Refused with
403 read_only_token. - Retry
- Safe to retry Cancelling again has no further effect.
On Solana it answers ok even when there is no session, and marks a finished session Cancelled too. On EVM it answers 404 when the launch has no Cleanup session.
Path parameters
-
launch_idstring RequiredLaunch ID: the 15-digit chain-encoded ID. Its first three digits name the chain (101Solana,201BSC,202Base,204Ethereum).Example101000000004217
Returns 200 OK · application/json
Returns ok and a confirmation message.
-
okbooleanAlwaystrueon success. -
messagestringHuman-readable confirmation.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | launch_id is not a chain-encoded launch ID. Pass the 15-digit chain-encoded launch ID exactly as the API returned it. |
| 404 | not_found | No launch with this ID belongs to the license in your token. Check the launch ID and that your token is upgraded onto the license that owns the launch. |
| 400 | bad_request | launch_id is a multi-launch group container; sessions run on the winning member launch. Call it with the winning member's launch ID once the group resolves. |
| 404 | not_found | EVM: the launch has no Cleanup session. Solana answers ok instead. Check Retrieve Cleanup status; there is nothing to cancel. |
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.launch.cleanup.cancelCleanup(launchId) src/lib/proxima/endpoints/launch/cleanup.ts
Discard a Cleanup session
/launch/cleanup/discard/{launch_id} Clears a finished Cleanup session from the launch.
- Token
- Upgraded session token, bound to a license.
- Read-only tokens
- Refused with
403 read_only_token. - Retry
- Safe to retry Discarding again has no further effect.
Path parameters
-
launch_idstring RequiredLaunch ID: the 15-digit chain-encoded ID. Its first three digits name the chain (101Solana,201BSC,202Base,204Ethereum).Example101000000004217
Returns 200 OK · application/json
Returns ok and a confirmation message.
-
okbooleanAlwaystrueon success. -
messagestringHuman-readable confirmation.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | launch_id is not a chain-encoded launch ID. Pass the 15-digit chain-encoded launch ID exactly as the API returned it. |
| 404 | not_found | No launch with this ID belongs to the license in your token. Check the launch ID and that your token is upgraded onto the license that owns the launch. |
| 400 | bad_request | launch_id is a multi-launch group container; sessions run on the winning member launch. Call it with the winning member's launch ID once the group resolves. |
| 409 | conflict | A Cleanup session is running for this launch. Stop it with Cancel a Cleanup session first, then discard. |
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.launch.cleanup.discardCleanup(launchId) src/lib/proxima/endpoints/launch/cleanup.ts