# 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.

Base URL: `https://api-mig.proxima.tools`

## Endpoints

- `POST /launch/cleanup/run/{launch_id}`: Start a Cleanup session
- `GET /launch/cleanup/status/{launch_id}`: Retrieve Cleanup status
- `POST /launch/cleanup/cancel/{launch_id}`: Cancel a Cleanup session
- `POST /launch/cleanup/discard/{launch_id}`: Discard a Cleanup session

## The Cleanup status object

The launch's Cleanup session and its progress.

- `status` (enum): Session state. The client also accepts lowercase values. Possible values: `None`, `Planned`, `Running`, `Completed`, `Cancelled`, `Failed`.
- `info` (object): Session details. Absent when `status` is `None`.
  - `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.

```json
{
  "status": "Running",
  "info": {
    "params": {
      "input_wallet_pubkeys": [
        "3pGh8WcR5vTn2YkLz9QmXbE7aDs4FjU6wHrN1tKyPqVe",
        "6rVb2NqT8xK4mWc9HsZpG7eYjD3uLfA5tRnE1kQwXzMh"
      ],
      "output_wallet_pubkeys": [
        "BqW7nR3tY5kP9xC2vM8hL4dJ6sF1aZ3gE7uN5rT2yKpX"
      ],
      "min_delay_ms": 2000,
      "max_delay_ms": 8000,
      "double_buy_pct": 10,
      "method": "buyback"
    },
    "started_at": 1793655010,
    "ended_at": null,
    "status_reason": null,
    "rounds_completed": 3,
    "rounds_total": 8
  }
}
```

### Start a Cleanup session

`POST /launch/cleanup/run/{launch_id}`

Starts moving tokens from the input wallets to the output wallets. (Bearer JWT)

- 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](/reference/cleanup/#get-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.

> Moves tokens between launch wallets on-chain and spends native balances on fees.

#### 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).

#### Body parameters

- `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: `buyback`, `streamflow_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

Returns `ok` and a confirmation `message`.

- `ok` (boolean): Always `true` on success.
- `message` (string): Human-readable confirmation.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `invalid launch id format` | `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` | `launch 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` | `multi-launch container: not available here; use the winner launch once it resolves` | 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` | `invalid body: <path>: <cause>` | 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` | `invalid body: missing field `<field>` at line <line> column <column>` | 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` | `Token not launched` | Solana: the token is still a draft. EVM answers 400 `bad_request` with `token not launched`. | Launch the token first with [Launch a token](/reference/launch-execution/#launch). |
| 400 | `bad_request` | `token not launched` | EVM: the token is still a draft. The token must be launched before a cleanup starts. | Launch the token first with [Launch a token](/reference/launch-execution/#launch). |
| 400 | `bad_request` | `Cleanup task already running` | 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](/reference/cleanup/#cancel-cleanup) first. |
| 400 | `bad_request` | `min_delay_ms must be between 500 and 300000` | `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 must be >= min_delay_ms and <= 300000` | `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` | `No input wallets have tokens to sell` | 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` | `input_wallet_pubkeys cannot be empty` | Solana: `input_wallet_pubkeys` is empty. | List at least one input wallet. |
| 500 | `internal_error` | `output_wallet_pubkeys cannot be empty` | Solana: `output_wallet_pubkeys` is empty. | List at least one output wallet. |
| 500 | `internal_error` | `double_buy_pct must be between 0 and 100` | Solana: `double_buy_pct` is above 100. | Set `double_buy_pct` between 0 and 100. |
| 500 | `internal_error` | `Invalid input wallet pubkey` | Solana: an entry of `input_wallet_pubkeys` is not a valid Solana address. | Correct or remove the malformed input address. |
| 500 | `internal_error` | `Invalid output wallet pubkey` | Solana: an entry of `output_wallet_pubkeys` is not a valid Solana address. | Correct or remove the malformed output address. |
| 500 | `internal_error` | `Some input wallets not found` | 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` | `Some output wallets not found` | 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` | `No input wallet holds enough SOL to pay for its sell` | 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` | `No output wallet holds enough SOL to pay for its buy` | 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` | `input_addresses cannot be empty` | EVM: `input_addresses` is empty. | List at least one input wallet. |
| 400 | `bad_request` | `output_addresses cannot be empty` | EVM: `output_addresses` is empty. | List at least one output wallet. |
| 400 | `bad_request` | `only the buyback method exists on evm launches` | EVM: `method` is set to something other than `buyback`. | Omit `method` or send `buyback`. |
| 400 | `bad_request` | `double_buy_pct is not supported on evm launches` | EVM: `double_buy_pct` is above 0. | Omit `double_buy_pct` or send 0. |
| 400 | `bad_request` | `fake_tip_pct is not supported on evm cleanup` | EVM: `fake_tip_pct` is above 0. | Omit `fake_tip_pct` or send 0. |
| 400 | `bad_request` | `Cleanup is not supported on this platform` | EVM: the launch's platform has no cleanup. | Move the tokens with [Transfer tokens](/reference/launch-trading/#transfer-tokens) instead. |
| 400 | `bad_request` | `Some wallets not found` | 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` | `funder <funder> has <balance> wei but cleanup needs <needed> in top-ups (+reserve <reserve>) — aborting before start` | 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` | `<count> wallet(s) still short of gas after the top-up, cleanup not started: <wallets>` | 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. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/launch/cleanup/run/101000000004217" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "input_wallet_pubkeys": [
    "3pGh8WcR5vTn2YkLz9QmXbE7aDs4FjU6wHrN1tKyPqVe",
    "6rVb2NqT8xK4mWc9HsZpG7eYjD3uLfA5tRnE1kQwXzMh"
  ],
  "output_wallet_pubkeys": [
    "BqW7nR3tY5kP9xC2vM8hL4dJ6sF1aZ3gE7uN5rT2yKpX"
  ],
  "min_delay_ms": 2000,
  "max_delay_ms": 8000,
  "double_buy_pct": 10,
  "fake_tip_pct": 0
}'
```

#### Example response

```json
{
  "ok": true,
  "message": "Cleanup started"
}
```

### Retrieve Cleanup status

`GET /launch/cleanup/status/{launch_id}`

Returns the launch's Cleanup session and its progress. (Bearer JWT)

- 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).

#### Returns 200 OK

Returns a Cleanup status object.

- `status` (enum): Session state. The client also accepts lowercase values. Possible values: `None`, `Planned`, `Running`, `Completed`, `Cancelled`, `Failed`.
- `info` (object): Session details. Absent when `status` is `None`.
  - `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

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `invalid launch id format` | `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` | `launch 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` | `multi-launch container: sessions run on the winner launch once it resolves` | `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. |

#### Example request

```bash
curl "https://api-mig.proxima.tools/launch/cleanup/status/101000000004217" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "status": "Running",
  "info": {
    "params": {
      "input_wallet_pubkeys": [
        "3pGh8WcR5vTn2YkLz9QmXbE7aDs4FjU6wHrN1tKyPqVe",
        "6rVb2NqT8xK4mWc9HsZpG7eYjD3uLfA5tRnE1kQwXzMh"
      ],
      "output_wallet_pubkeys": [
        "BqW7nR3tY5kP9xC2vM8hL4dJ6sF1aZ3gE7uN5rT2yKpX"
      ],
      "min_delay_ms": 2000,
      "max_delay_ms": 8000,
      "double_buy_pct": 10,
      "method": "buyback"
    },
    "started_at": 1793655010,
    "ended_at": null,
    "status_reason": null,
    "rounds_completed": 3,
    "rounds_total": 8
  }
}
```

### Cancel a Cleanup session

`POST /launch/cleanup/cancel/{launch_id}`

Stops the launch's running Cleanup session. (Bearer JWT)

- 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).

#### Returns 200 OK

Returns `ok` and a confirmation `message`.

- `ok` (boolean): Always `true` on success.
- `message` (string): Human-readable confirmation.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `invalid launch id format` | `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` | `launch 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` | `multi-launch container: sessions run on the winner launch once it resolves` | `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` | `no cleanup session` | EVM: the launch has no Cleanup session. Solana answers `ok` instead. | Check [Retrieve Cleanup status](/reference/cleanup/#get-cleanup-status); there is nothing to cancel. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/launch/cleanup/cancel/101000000004217" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "ok": true,
  "message": "Cleanup cancelled"
}
```

### Discard a Cleanup session

`POST /launch/cleanup/discard/{launch_id}`

Clears a finished Cleanup session from the launch. (Bearer JWT)

- 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).

#### Returns 200 OK

Returns `ok` and a confirmation `message`.

- `ok` (boolean): Always `true` on success.
- `message` (string): Human-readable confirmation.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `invalid launch id format` | `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` | `launch 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` | `multi-launch container: sessions run on the winner launch once it resolves` | `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` | `Cannot discard running session` | A Cleanup session is running for this launch. | Stop it with [Cancel a Cleanup session](/reference/cleanup/#cancel-cleanup) first, then discard. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/launch/cleanup/discard/101000000004217" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "ok": true,
  "message": "Cleanup session discarded"
}
```
