Skip to content
API Reference

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

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 launch's Cleanup session and its progress.

Attributes

  • status enum
    Session state. The client also accepts lowercase values.
    Possible values NonePlannedRunningCompletedCancelledFailed
  • info object
    Session details. Absent when status is None.
    Child attributes 6
    • params object
      The parameters the session was started with.
    • started_at integer | null
      Unix timestamp (seconds) the session started.
    • ended_at integer | null
      Unix timestamp (seconds) the session ended.
    • status_reason string | null
      Why the session ended or failed, when known.
    • rounds_completed integer
      Rounds completed.
    • rounds_total integer
      Rounds planned.
POST /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: Running means 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_id string Required
    Launch ID: the 15-digit chain-encoded ID. Its first three digits name the chain (101 Solana, 201 BSC, 202 Base, 204 Ethereum).
    Example101000000004217

Body parameters application/json

  • input_wallet_pubkeys array<string> Optional
    Solana: wallets whose tokens are moved out (sellers). Required on Solana.
  • output_wallet_pubkeys array<string> Optional
    Solana: wallets that receive the tokens (buyers). Required on Solana.
  • input_addresses array<string> Optional
    EVM: wallets whose tokens are moved out. Required on EVM chains.
  • output_addresses array<string> Optional
    EVM: wallets that receive the tokens. Required on EVM chains.
  • min_delay_ms integer Required
    Minimum delay between rounds in milliseconds (500–300000).
  • max_delay_ms integer Required
    Maximum delay between rounds in milliseconds, at least min_delay_ms and at most 300000.
  • method enum Optional Default buyback
    Solana: how tokens move. buyback sells input tokens to the output wallets through an on-chain buyback; streamflow_airdrop distributes them through a Streamflow airdrop. EVM accepts only buyback.
    Possible values buybackstreamflow_airdrop
  • double_buy_pct integer Optional
    Solana, buyback only: double-buy percentage, 0–100. EVM refuses any value other than 0.
  • fake_tip_pct integer Optional
    Typed 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.

  • ok boolean
    Always true on success.
  • message string
    Human-readable confirmation.

Errors

StatusCodeWhen 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

GET /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_id string Required
    Launch ID: the 15-digit chain-encoded ID. Its first three digits name the chain (101 Solana, 201 BSC, 202 Base, 204 Ethereum).
    Example101000000004217

Returns 200 OK · application/json

Returns a Cleanup status object.

  • status enum
    Session state. The client also accepts lowercase values.
    Possible values NonePlannedRunningCompletedCancelledFailed
  • info object
    Session details. Absent when status is None.
    Child attributes 6
    • params object
      The parameters the session was started with.
    • started_at integer | null
      Unix timestamp (seconds) the session started.
    • ended_at integer | null
      Unix timestamp (seconds) the session ended.
    • status_reason string | null
      Why the session ended or failed, when known.
    • rounds_completed integer
      Rounds completed.
    • rounds_total integer
      Rounds planned.

Errors

StatusCodeWhen 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

POST /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_id string Required
    Launch ID: the 15-digit chain-encoded ID. Its first three digits name the chain (101 Solana, 201 BSC, 202 Base, 204 Ethereum).
    Example101000000004217

Returns 200 OK · application/json

Returns ok and a confirmation message.

  • ok boolean
    Always true on success.
  • message string
    Human-readable confirmation.

Errors

StatusCodeWhen 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

POST /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_id string Required
    Launch ID: the 15-digit chain-encoded ID. Its first three digits name the chain (101 Solana, 201 BSC, 202 Base, 204 Ethereum).
    Example101000000004217

Returns 200 OK · application/json

Returns ok and a confirmation message.

  • ok boolean
    Always true on success.
  • message string
    Human-readable confirmation.

Errors

StatusCodeWhen 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