# Volume Bot

> Generate trading volume on a launch with buy-and-sell round trips from its wallets.

The Volume Bot trades the launch's token back and forth from the launch's wallets until it reaches a target volume, either over a fixed duration (`TimeBased`) or with random delays between round trips (`DelayBased`). Targets are set in raw quote units or in micro-USD.

Estimate a configuration first to see its cost and the balance each wallet needs. 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/volume/plan/{launch_id}`: Plan a Volume Bot session
- `POST /launch/volume/run/{launch_id}`: Start a Volume Bot session
- `GET /launch/volume/status/{launch_id}`: Retrieve Volume Bot status
- `POST /launch/volume/estimate/{launch_id}`: Estimate a Volume Bot session
- `POST /launch/volume/cancel/{launch_id}`: Cancel a Volume Bot session
- `POST /launch/volume/discard/{launch_id}`: Discard a Volume Bot session

## The Volume bot status object

The launch's Volume Bot session and its counters.

- `status` (enum): Session state. Possible values: `None`, `Planned`, `Running`, `Completed`, `Cancelled`, `Failed`.
- `info` (object): Session details. Absent when `status` is `None`.
  - `params` (object): The session parameters, as sent to plan or run.
  - `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.
  - `target_volume` (integer | string): Target volume, raw quote units.
  - `volume_generated` (integer | string): Volume generated so far, raw quote units.
  - `net_cost` (integer | string): Net cost so far (fees and slippage), raw quote units.
  - `usd_volume_generated` (integer | string): Volume generated so far, micro-USD.
  - `usd_net_cost` (integer | string): Net cost so far, micro-USD.
  - `round_trips_completed` (integer): Buy-and-sell round trips completed.

```json
{
  "status": "Running",
  "info": {
    "params": {
      "mode": "Organic",
      "end_condition": {
        "TimeBased": {
          "target_volume_usd": "25000000000",
          "duration": 7200
        }
      },
      "wallet_pubkeys": [
        "3pGh8WcR5vTn2YkLz9QmXbE7aDs4FjU6wHrN1tKyPqVe",
        "6rVb2NqT8xK4mWc9HsZpG7eYjD3uLfA5tRnE1kQwXzMh",
        "BqW7nR3tY5kP9xC2vM8hL4dJ6sF1aZ3gE7uN5rT2yKpX"
      ],
      "wave_intensity": 2
    },
    "started_at": 1793655010,
    "ended_at": null,
    "status_reason": null,
    "volume_generated": 61200000000,
    "net_cost": 410000000,
    "usd_volume_generated": 11475000000,
    "usd_net_cost": 76870000,
    "round_trips_completed": 118
  }
}
```

## The Volume estimate object

What a Volume Bot configuration would cost and need, computed without starting it.

- `round_trips` (integer): Round trips the bot would make.
- `cost` (integer | string): Estimated cost, raw native units.
- `quote_cost` (integer | string | null): Estimated cost in the quote token, raw units.
- `min_balance_per_wallet` (integer | string): Native each wallet needs, raw units. On a quote-denominated launch this covers gas only.
- `min_quote_per_wallet` (integer | string | null): Quote each wallet needs to trade, raw units. `null` on a gas-token launch.
- `quote_symbol` (string): Symbol of the quote token.
- `quote_decimals` (integer): Decimals of the quote token.
- `min_duration_secs` (integer): Shortest duration the configuration allows, in seconds.
- `wallets` (array<string>): Wallets the bot would use.

```json
{
  "round_trips": 240,
  "cost": 820000000,
  "quote_cost": null,
  "min_balance_per_wallet": 450000000,
  "min_quote_per_wallet": null,
  "quote_symbol": "SOL",
  "quote_decimals": 9,
  "min_duration_secs": 240,
  "wallets": [
    "3pGh8WcR5vTn2YkLz9QmXbE7aDs4FjU6wHrN1tKyPqVe",
    "6rVb2NqT8xK4mWc9HsZpG7eYjD3uLfA5tRnE1kQwXzMh",
    "BqW7nR3tY5kP9xC2vM8hL4dJ6sF1aZ3gE7uN5rT2yKpX"
  ]
}
```

### Plan a Volume Bot session

`POST /launch/volume/plan/{launch_id}`

Saves a Volume Bot session as `Planned`; on Solana it starts with 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. Planning again replaces the planned configuration. Nothing trades until the session starts.

On Solana the token does not need to be launched yet, and the planned session starts when the launch runs. On EVM the token must already be launched, nothing starts the session automatically, and the next [Start a Volume Bot session](/reference/volume-bot/#run-volume-bot) call runs the planned parameters instead of the ones in its body.

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

- `mode` (enum, required): Trading pattern of the bot. Possible values: `Bundle`, `Organic`.
- `end_condition` (object, required): When the bot stops. Exactly one key is set.
  - `TimeBased` (object, optional): Generate the target volume over a fixed duration.
    - `target_volume` (integer | string, optional): Volume to generate: raw quote units on Solana, native wei on EVM. Send this or `target_volume_usd`.
    - `target_volume_usd` (integer | string, optional): Volume to generate, micro-USD. Send this or `target_volume`.
    - `duration` (integer, required): Duration in seconds, at most 86400.
  - `DelayBased` (object, optional): Generate the target volume with a random delay between round trips.
    - `target_volume` (integer | string, optional): Volume to generate: raw quote units on Solana, native wei on EVM. Send this or `target_volume_usd`.
    - `target_volume_usd` (integer | string, optional): Volume to generate, micro-USD. Send this or `target_volume`.
    - `min_delay` (integer, required): Minimum delay in milliseconds (1000–300000).
    - `max_delay` (integer, required): Maximum delay in milliseconds (1000–300000), at least `min_delay`.
- `min_amount` (integer | string, optional): Smallest trade, raw quote units. Send with `max_amount` to override the computed sizes.
- `max_amount` (integer | string, optional): Largest trade, raw quote units.
- `wallet_pubkeys` (array<string> | null, required): Launch wallets that trade, or `null` for all of them. An empty array is rejected.
- `fee_target` (integer | string, optional): Solana only: fee target, raw native units.
- `wave_intensity` (number, optional): `Organic` mode only: intensity of the volume waves, from `0.0` (tight buy/sell alternation) to `1.0` (long waves).

#### 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` | `Must provide target_volume or target_volume_usd > 0` | `end_condition` sets neither `target_volume` nor `target_volume_usd`, or sets it to 0. EVM answers 500 `internal_error` with `Provide target_volume or target_volume_usd`, `target_volume must be > 0` or `target_volume_usd must be > 0`. | Set exactly one of `target_volume` or `target_volume_usd` to a positive value. |
| 400 | `bad_request` | `Provide either target_volume or target_volume_usd, not both` | `end_condition` sets both `target_volume` and `target_volume_usd`. EVM sends the same message with 500 `internal_error`. | Send only one of the two targets. |
| 400 | `bad_request` | `Invalid duration` | Solana: `TimeBased.duration` is 0 or above 86400 seconds. EVM refuses only 0, with 500 `internal_error` and `duration must be > 0`. | Set `duration` between 1 and 86400 seconds. |
| 400 | `bad_request` | `Duration too short for this volume target. Increase duration or reduce target volume` | Solana: at the largest trade size, the target needs more trades than fit in `duration`, counting at least 8 seconds per trade. | Increase `duration`, lower the target or raise `max_amount`. |
| 400 | `bad_request` | `Too many transactions for this duration. Increase trade amount, reduce target volume, or increase duration` | Solana: with explicit amounts, the target needs more than 60 round trips per minute. | Raise `min_amount` and `max_amount`, lower the target or increase `duration`. |
| 400 | `bad_request` | `Invalid delay range` | Solana: `DelayBased.min_delay` is under 1000 ms or `max_delay` is over 300000 ms. | Keep both delays between 1000 and 300000 ms. |
| 400 | `bad_request` | `min_delay must be <= max_delay` | `DelayBased.min_delay` is greater than `max_delay`. EVM sends the same message with 500 `internal_error`. | Set `min_delay` at or below `max_delay`. |
| 400 | `bad_request` | `DelayBased mode requires min_amount and max_amount` | Solana: a `DelayBased` session omits `min_amount` or `max_amount`. | Send both `min_amount` and `max_amount` with a `DelayBased` end condition. |
| 400 | `bad_request` | `Provide both min_amount and max_amount, or neither` | Only one of `min_amount` and `max_amount` is set. EVM answers 500 `internal_error` with `provide both min_amount and max_amount, or neither`. | Send both amounts, or neither to let the bot size the trades. |
| 400 | `bad_request` | `Trade amount too small` | Solana: `min_amount` or `max_amount` is worth less than 0.0001 SOL (100000 lamports) in the launch quote. | Raise both amounts to at least the equivalent of 0.0001 SOL. |
| 400 | `bad_request` | `min_amount must be <= max_amount` | Solana: `min_amount` is greater than `max_amount`. EVM answers 500 `internal_error` with `require 0 < min_amount <= max_amount`, also when `min_amount` is 0. | Set `min_amount` at or below `max_amount`. |
| 400 | `bad_request` | `wave_intensity must be between 0.0 and 1.0` | `wave_intensity` is outside 0.0–1.0. EVM sends the same message with 500 `internal_error`. | Send a `wave_intensity` between 0 and 1. |
| 400 | `bad_request` | `wallet_pubkeys cannot be empty` | Solana: `wallet_pubkeys` is an empty array. | Send `null` to use every holder wallet, or list at least one wallet. |
| 400 | `bad_request` | `Invalid pubkey` | Solana: an entry of `wallet_pubkeys` is not a valid Solana address. | Correct or remove the malformed address. |
| 404 | `not_found` | `Wallet not found in launch` | Solana: an entry of `wallet_pubkeys` is not one of the launch's wallets. | Add the wallet with [Add wallets to a launch](/reference/launches/#add-launch-wallets), or remove it from the list. |
| 409 | `conflict` | `Task already running` | Solana: a Volume Bot session is running for this launch. | Wait for it to end or stop it with [Cancel a Volume Bot session](/reference/volume-bot/#cancel-volume-bot) first. |
| 422 | `unprocessable` | `No wallets available` | Solana: `wallet_pubkeys` is `null` and the launch has no holder wallets. | Add holder wallets with [Add wallets to a launch](/reference/launches/#add-launch-wallets), or list wallets in `wallet_pubkeys`. |
| 422 | `upstream_failure` | `price_feed api issue: The launch quote has no price right now` | Solana: the launch quote has no price right now, so trade bounds cannot be computed. The body adds `service: "price_feed"`. | Retry in a few seconds. |
| 400 | `bad_request` | `token not launched` | EVM: the token is still a draft. Unlike Solana, EVM only plans a session on a launched token. | Launch the token first with [Launch a token](/reference/launch-execution/#launch). |
| 500 | `internal_error` | `Volume bot already running for this launch` | EVM: a Volume Bot session is already running for this launch. | Wait for it to end or stop it with [Cancel a Volume Bot session](/reference/volume-bot/#cancel-volume-bot) first. |
| 500 | `internal_error` | `wallet_pubkeys provided but none matched launch wallets` | EVM: no entry of `wallet_pubkeys` is a wallet of the launch. | List addresses of the launch's own wallets, or send `null` to use all of them. |
| 500 | `internal_error` | `No wallets available for volume bot` | EVM: `wallet_pubkeys` is an empty array, or the launch holds no usable wallet. | Send `null` to use every launch wallet, or list at least one launch wallet. |
| 500 | `internal_error` | `Bundle mode needs a bundle relay, which this chain has none of` | EVM: `mode` is `Bundle` on a chain that has no bundle relay. | Use `Organic` mode on this chain. |
| 500 | `internal_error` | `target_volume too small (below one trade); send it in wei or use target_volume_usd (micro-USD)` | EVM: the target is smaller than one trade of `max_amount`, typically a target sent in whole units instead of wei. | Send `target_volume` in wei, or `target_volume_usd` in micro-USD. |
| 500 | `internal_error` | `the launch quote cannot be resolved right now, retry in a moment` | EVM: the launch names a quote token that cannot be resolved right now. | Retry in a few seconds. |
| 500 | `internal_error` | `native price unavailable for USD target` | EVM: `target_volume_usd` is set and the chain's native price is unavailable. | Retry in a few seconds, or send `target_volume` in wei instead. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/launch/volume/plan/101000000004217" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "mode": "Organic",
  "end_condition": {
    "TimeBased": {
      "target_volume_usd": "25000000000",
      "duration": 7200
    }
  },
  "wallet_pubkeys": [
    "3pGh8WcR5vTn2YkLz9QmXbE7aDs4FjU6wHrN1tKyPqVe",
    "6rVb2NqT8xK4mWc9HsZpG7eYjD3uLfA5tRnE1kQwXzMh",
    "BqW7nR3tY5kP9xC2vM8hL4dJ6sF1aZ3gE7uN5rT2yKpX"
  ],
  "wave_intensity": 0.6
}'
```

#### Example response

```json
{
  "ok": true,
  "message": "Successfully planned volume bot session"
}
```

### Start a Volume Bot session

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

Starts a Volume Bot session right away on a launched token. (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 Volume Bot status](/reference/volume-bot/#get-volume-bot-status) first: `Running`, or a `started_at` later than your first call, means it went through. A second run is refused while a session runs.

The token must be launched. On Solana, listed wallets that are not launch wallets are looked up among the license's wallets. On EVM, when the launch has a `Planned` session, the planned parameters run and the parameters in this body are ignored.

> Trades from the launch wallets and spends their balances on fees and slippage until the target is reached or the session is cancelled.

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

- `mode` (enum, required): Trading pattern of the bot. Possible values: `Bundle`, `Organic`.
- `end_condition` (object, required): When the bot stops. Exactly one key is set.
  - `TimeBased` (object, optional): Generate the target volume over a fixed duration.
    - `target_volume` (integer | string, optional): Volume to generate: raw quote units on Solana, native wei on EVM. Send this or `target_volume_usd`.
    - `target_volume_usd` (integer | string, optional): Volume to generate, micro-USD. Send this or `target_volume`.
    - `duration` (integer, required): Duration in seconds, at most 86400.
  - `DelayBased` (object, optional): Generate the target volume with a random delay between round trips.
    - `target_volume` (integer | string, optional): Volume to generate: raw quote units on Solana, native wei on EVM. Send this or `target_volume_usd`.
    - `target_volume_usd` (integer | string, optional): Volume to generate, micro-USD. Send this or `target_volume`.
    - `min_delay` (integer, required): Minimum delay in milliseconds (1000–300000).
    - `max_delay` (integer, required): Maximum delay in milliseconds (1000–300000), at least `min_delay`.
- `min_amount` (integer | string, optional): Smallest trade, raw quote units. Send with `max_amount` to override the computed sizes.
- `max_amount` (integer | string, optional): Largest trade, raw quote units.
- `wallet_pubkeys` (array<string> | null, required): Launch wallets that trade, or `null` for all of them. An empty array is rejected.
- `fee_target` (integer | string, optional): Solana only: fee target, raw native units.
- `wave_intensity` (number, optional): `Organic` mode only: intensity of the volume waves, from `0.0` (tight buy/sell alternation) to `1.0` (long waves).

#### Returns 200 OK

Returns `ok` and a confirmation `message`.

- `ok` (boolean): Always `true` on success.
- `message` (string): Human-readable confirmation.
- `session_id` (string): EVM only: ID of the session that started.

#### 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` | `Must provide target_volume or target_volume_usd > 0` | `end_condition` sets neither `target_volume` nor `target_volume_usd`, or sets it to 0. EVM answers 500 `internal_error` with `Provide target_volume or target_volume_usd`, `target_volume must be > 0` or `target_volume_usd must be > 0`. | Set exactly one of `target_volume` or `target_volume_usd` to a positive value. |
| 400 | `bad_request` | `Provide either target_volume or target_volume_usd, not both` | `end_condition` sets both `target_volume` and `target_volume_usd`. EVM sends the same message with 500 `internal_error`. | Send only one of the two targets. |
| 400 | `bad_request` | `Invalid duration` | Solana: `TimeBased.duration` is 0 or above 86400 seconds. EVM refuses only 0, with 500 `internal_error` and `duration must be > 0`. | Set `duration` between 1 and 86400 seconds. |
| 400 | `bad_request` | `Duration too short for this volume target. Increase duration or reduce target volume` | Solana: at the largest trade size, the target needs more trades than fit in `duration`, counting at least 8 seconds per trade. | Increase `duration`, lower the target or raise `max_amount`. |
| 400 | `bad_request` | `Too many transactions for this duration. Increase trade amount, reduce target volume, or increase duration` | Solana: with explicit amounts, the target needs more than 60 round trips per minute. | Raise `min_amount` and `max_amount`, lower the target or increase `duration`. |
| 400 | `bad_request` | `Invalid delay range` | Solana: `DelayBased.min_delay` is under 1000 ms or `max_delay` is over 300000 ms. | Keep both delays between 1000 and 300000 ms. |
| 400 | `bad_request` | `min_delay must be <= max_delay` | `DelayBased.min_delay` is greater than `max_delay`. EVM sends the same message with 500 `internal_error`. | Set `min_delay` at or below `max_delay`. |
| 400 | `bad_request` | `DelayBased mode requires min_amount and max_amount` | Solana: a `DelayBased` session omits `min_amount` or `max_amount`. | Send both `min_amount` and `max_amount` with a `DelayBased` end condition. |
| 400 | `bad_request` | `Provide both min_amount and max_amount, or neither` | Only one of `min_amount` and `max_amount` is set. EVM answers 500 `internal_error` with `provide both min_amount and max_amount, or neither`. | Send both amounts, or neither to let the bot size the trades. |
| 400 | `bad_request` | `Trade amount too small` | Solana: `min_amount` or `max_amount` is worth less than 0.0001 SOL (100000 lamports) in the launch quote. | Raise both amounts to at least the equivalent of 0.0001 SOL. |
| 400 | `bad_request` | `min_amount must be <= max_amount` | Solana: `min_amount` is greater than `max_amount`. EVM answers 500 `internal_error` with `require 0 < min_amount <= max_amount`, also when `min_amount` is 0. | Set `min_amount` at or below `max_amount`. |
| 400 | `bad_request` | `wave_intensity must be between 0.0 and 1.0` | `wave_intensity` is outside 0.0–1.0. EVM sends the same message with 500 `internal_error`. | Send a `wave_intensity` between 0 and 1. |
| 422 | `upstream_failure` | `price_feed api issue: The launch quote has no price right now` | Solana: the launch quote has no price right now, so trade bounds cannot be computed. The body adds `service: "price_feed"`. | Retry in a few seconds. |
| 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). |
| 500 | `internal_error` | `Task already running` | Solana: a Volume Bot session is already running for this launch. | Wait for it to end or stop it with [Cancel a Volume Bot session](/reference/volume-bot/#cancel-volume-bot) first. |
| 500 | `internal_error` | `wallet_pubkeys cannot be empty` | Solana: `wallet_pubkeys` is an empty array. | Send `null` to use every holder wallet, or list at least one wallet. |
| 500 | `internal_error` | `Invalid pubkey` | Solana: an entry of `wallet_pubkeys` is not a valid Solana address. | Correct or remove the malformed address. |
| 500 | `internal_error` | `No wallets available` | Solana: none of the listed wallets belongs to the launch or the license's wallets, or `wallet_pubkeys` is `null` and the launch has no holder wallets. | List wallets of the launch or license, or add holder wallets with [Add wallets to a launch](/reference/launches/#add-launch-wallets). |
| 500 | `internal_error` | `Failed to convert USD target to SOL (price unavailable)` | Solana: `target_volume_usd` is set and the SOL price is unavailable. | Retry in a few seconds, or send `target_volume` instead. |
| 500 | `internal_error` | `No wallet has enough SOL to pay tx fees. Fund wallets with ~0.05 SOL each` | Solana, quote-token launch: no wallet holds the 0.05 SOL it keeps for fees. | Fund the wallets with about 0.05 SOL each. |
| 500 | `internal_error` | `No wallet has enough SOL to trade. Fund your wallets first` | Solana, SOL-quoted launch: no wallet holds more than the 0.05 SOL fee buffer plus the smallest trade. | Fund the wallets, then start the session again. |
| 500 | `internal_error` | `No wallet holds enough of the launch quote to trade. Fund the wallets with it first` | Solana, quote-token launch: no wallet holds enough of the quote token for the smallest trade. | Swap the wallets into the quote token with [Swap funding to the quote token](/reference/launch-funding/#swap-to-quote), then start again. |
| 500 | `internal_error` | `Wallet balances too low for this volume target and duration. Increase wallet funding, reduce target, or increase duration` | Solana: at the size the balances allow, the target needs more trades than fit in `duration`. The session is recorded as `Failed` with this reason. | Fund the wallets, lower the target or increase `duration`. |
| 400 | `bad_request` | `token not launched` | EVM: the token is still a draft. The token must be launched before a session starts. | Launch the token first with [Launch a token](/reference/launch-execution/#launch). |
| 500 | `internal_error` | `Volume bot already running for this launch` | EVM: a Volume Bot session is already running for this launch. | Wait for it to end or stop it with [Cancel a Volume Bot session](/reference/volume-bot/#cancel-volume-bot) first. |
| 500 | `internal_error` | `wallet_pubkeys provided but none matched launch wallets` | EVM: no entry of `wallet_pubkeys` is a wallet of the launch. | List addresses of the launch's own wallets, or send `null` to use all of them. |
| 500 | `internal_error` | `No wallets available for volume bot` | EVM: `wallet_pubkeys` is an empty array, or the launch holds no usable wallet. | Send `null` to use every launch wallet, or list at least one launch wallet. |
| 500 | `internal_error` | `Bundle mode needs a bundle relay, which this chain has none of` | EVM: `mode` is `Bundle` on a chain that has no bundle relay. | Use `Organic` mode on this chain. |
| 500 | `internal_error` | `target_volume too small (below one trade); send it in wei or use target_volume_usd (micro-USD)` | EVM: the target is smaller than one trade of `max_amount`, typically a target sent in whole units instead of wei. | Send `target_volume` in wei, or `target_volume_usd` in micro-USD. |
| 500 | `internal_error` | `the launch quote cannot be resolved right now, retry in a moment` | EVM: the launch names a quote token that cannot be resolved right now. | Retry in a few seconds. |
| 500 | `internal_error` | `native price unavailable for USD target` | EVM: `target_volume_usd` is set and the chain's native price is unavailable. | Retry in a few seconds, or send `target_volume` in wei instead. |
| 500 | `internal_error` | `No wallet holds enough gas to trade. Fund the launch wallets first` | EVM: no wallet holds more native than the gas reserve a round trip needs. | Fund the launch wallets with native gas, then start again. |
| 500 | `internal_error` | `No wallet holds enough to trade. Fund the launch wallets first` | EVM, launch whose quote is paid from the native balance: no wallet can afford `min_amount` after the gas reserve. | Fund the launch wallets, then start again. |
| 500 | `internal_error` | `No wallet holds enough of the launch quote to trade. Swap the wallets into it first` | EVM, quote-token launch: no wallet holds `min_amount` of the quote token. | Swap the wallets into the quote token with [Swap funding to the quote token](/reference/launch-funding/#swap-to-quote), then start again. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/launch/volume/run/101000000004217" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "mode": "Organic",
  "end_condition": {
    "TimeBased": {
      "target_volume_usd": "25000000000",
      "duration": 7200
    }
  },
  "wallet_pubkeys": [
    "3pGh8WcR5vTn2YkLz9QmXbE7aDs4FjU6wHrN1tKyPqVe",
    "6rVb2NqT8xK4mWc9HsZpG7eYjD3uLfA5tRnE1kQwXzMh",
    "BqW7nR3tY5kP9xC2vM8hL4dJ6sF1aZ3gE7uN5rT2yKpX"
  ],
  "wave_intensity": 0.6
}'
```

#### Example response

```json
{
  "ok": true,
  "message": "Successfully started volume bot"
}
```

### Retrieve Volume Bot status

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

Returns the launch's Volume Bot session and its counters. (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 Volume bot status object.

- `status` (enum): Session state. Possible values: `None`, `Planned`, `Running`, `Completed`, `Cancelled`, `Failed`.
- `info` (object): Session details. Absent when `status` is `None`.
  - `params` (object): The session parameters, as sent to plan or run.
  - `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.
  - `target_volume` (integer | string): Typed by the web client, but neither chain sends it.
  - `volume_generated` (integer | string): Volume generated so far, raw quote units.
  - `net_cost` (integer | string): Net cost so far (fees and slippage), raw quote units.
  - `usd_volume_generated` (integer | string): Volume generated so far, micro-USD.
  - `usd_net_cost` (integer | string): Net cost so far, micro-USD.
  - `round_trips_completed` (integer): Buy-and-sell round trips completed.

#### 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/volume/status/101000000004217" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "status": "Running",
  "info": {
    "params": {
      "mode": "Organic",
      "end_condition": {
        "TimeBased": {
          "target_volume_usd": "25000000000",
          "duration": 7200
        }
      },
      "wallet_pubkeys": [
        "3pGh8WcR5vTn2YkLz9QmXbE7aDs4FjU6wHrN1tKyPqVe",
        "6rVb2NqT8xK4mWc9HsZpG7eYjD3uLfA5tRnE1kQwXzMh",
        "BqW7nR3tY5kP9xC2vM8hL4dJ6sF1aZ3gE7uN5rT2yKpX"
      ],
      "wave_intensity": 0.6
    },
    "started_at": 1793655010,
    "ended_at": null,
    "status_reason": null,
    "volume_generated": 61200000000,
    "net_cost": 410000000,
    "usd_volume_generated": 11475000000,
    "usd_net_cost": 76870000,
    "round_trips_completed": 118
  }
}
```

### Estimate a Volume Bot session

`POST /launch/volume/estimate/{launch_id}`

Computes the cost, round trips and per-wallet balance a configuration needs, without starting it. (Bearer JWT)

- 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 saved or sent.

Takes the same body as plan and run. The client returns only the `estimate` object to its callers. On EVM the token must already be launched. On Solana the listed wallets are not checked against the launch.

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

- `mode` (enum, required): Trading pattern of the bot. Possible values: `Bundle`, `Organic`.
- `end_condition` (object, required): When the bot stops. Exactly one key is set.
  - `TimeBased` (object, optional): Generate the target volume over a fixed duration.
    - `target_volume` (integer | string, optional): Volume to generate: raw quote units on Solana, native wei on EVM. Send this or `target_volume_usd`.
    - `target_volume_usd` (integer | string, optional): Volume to generate, micro-USD. Send this or `target_volume`.
    - `duration` (integer, required): Duration in seconds, at most 86400.
  - `DelayBased` (object, optional): Generate the target volume with a random delay between round trips.
    - `target_volume` (integer | string, optional): Volume to generate: raw quote units on Solana, native wei on EVM. Send this or `target_volume_usd`.
    - `target_volume_usd` (integer | string, optional): Volume to generate, micro-USD. Send this or `target_volume`.
    - `min_delay` (integer, required): Minimum delay in milliseconds (1000–300000).
    - `max_delay` (integer, required): Maximum delay in milliseconds (1000–300000), at least `min_delay`.
- `min_amount` (integer | string, optional): Smallest trade, raw quote units. Send with `max_amount` to override the computed sizes.
- `max_amount` (integer | string, optional): Largest trade, raw quote units.
- `wallet_pubkeys` (array<string> | null, required): Launch wallets that trade, or `null` for all of them. An empty array is rejected.
- `fee_target` (integer | string, optional): Solana only: fee target, raw native units.
- `wave_intensity` (number, optional): `Organic` mode only: intensity of the volume waves, from `0.0` (tight buy/sell alternation) to `1.0` (long waves).

#### Returns 200 OK

Returns `ok` and a Volume estimate object under `estimate`.

- `ok` (boolean): Always `true` on success.
- `estimate` (object): The estimate.
  - `round_trips` (integer): Round trips the bot would make.
  - `cost` (integer | string): Estimated cost, raw native units.
  - `quote_cost` (integer | string | null): Typed by the web client, but neither chain sends it.
  - `min_balance_per_wallet` (integer | string): Native each wallet needs, raw units. On a quote-denominated launch this covers gas only.
  - `min_quote_per_wallet` (integer | string | null): EVM only: quote each wallet needs to trade, raw units. `null` on a gas-token launch.
  - `quote_symbol` (string): EVM only: symbol of the quote token.
  - `quote_decimals` (integer): EVM only: decimals of the quote token.
  - `min_duration_secs` (integer): Shortest duration the configuration allows, in seconds.
  - `wallets` (array<string>): Wallets the bot would use.

#### 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` | `Must provide target_volume or target_volume_usd > 0` | `end_condition` sets neither `target_volume` nor `target_volume_usd`, or sets it to 0. EVM answers 500 `internal_error` with `Provide target_volume or target_volume_usd`, `target_volume must be > 0` or `target_volume_usd must be > 0`. | Set exactly one of `target_volume` or `target_volume_usd` to a positive value. |
| 400 | `bad_request` | `Provide either target_volume or target_volume_usd, not both` | `end_condition` sets both `target_volume` and `target_volume_usd`. EVM sends the same message with 500 `internal_error`. | Send only one of the two targets. |
| 400 | `bad_request` | `Invalid duration` | Solana: `TimeBased.duration` is 0 or above 86400 seconds. EVM refuses only 0, with 500 `internal_error` and `duration must be > 0`. | Set `duration` between 1 and 86400 seconds. |
| 400 | `bad_request` | `Duration too short for this volume target. Increase duration or reduce target volume` | Solana: at the largest trade size, the target needs more trades than fit in `duration`, counting at least 8 seconds per trade. | Increase `duration`, lower the target or raise `max_amount`. |
| 400 | `bad_request` | `Too many transactions for this duration. Increase trade amount, reduce target volume, or increase duration` | Solana: with explicit amounts, the target needs more than 60 round trips per minute. | Raise `min_amount` and `max_amount`, lower the target or increase `duration`. |
| 400 | `bad_request` | `Invalid delay range` | Solana: `DelayBased.min_delay` is under 1000 ms or `max_delay` is over 300000 ms. | Keep both delays between 1000 and 300000 ms. |
| 400 | `bad_request` | `min_delay must be <= max_delay` | `DelayBased.min_delay` is greater than `max_delay`. EVM sends the same message with 500 `internal_error`. | Set `min_delay` at or below `max_delay`. |
| 400 | `bad_request` | `DelayBased mode requires min_amount and max_amount` | Solana: a `DelayBased` session omits `min_amount` or `max_amount`. | Send both `min_amount` and `max_amount` with a `DelayBased` end condition. |
| 400 | `bad_request` | `Provide both min_amount and max_amount, or neither` | Only one of `min_amount` and `max_amount` is set. EVM answers 500 `internal_error` with `provide both min_amount and max_amount, or neither`. | Send both amounts, or neither to let the bot size the trades. |
| 400 | `bad_request` | `Trade amount too small` | Solana: `min_amount` or `max_amount` is worth less than 0.0001 SOL (100000 lamports) in the launch quote. | Raise both amounts to at least the equivalent of 0.0001 SOL. |
| 400 | `bad_request` | `min_amount must be <= max_amount` | Solana: `min_amount` is greater than `max_amount`. EVM answers 500 `internal_error` with `require 0 < min_amount <= max_amount`, also when `min_amount` is 0. | Set `min_amount` at or below `max_amount`. |
| 400 | `bad_request` | `wave_intensity must be between 0.0 and 1.0` | `wave_intensity` is outside 0.0–1.0. EVM sends the same message with 500 `internal_error`. | Send a `wave_intensity` between 0 and 1. |
| 422 | `upstream_failure` | `price_feed api issue: The launch quote has no price right now` | Solana: the launch quote has no price right now, so trade bounds cannot be computed. The body adds `service: "price_feed"`. | Retry in a few seconds. |
| 422 | `upstream_failure` | `price_feed api issue: Failed to convert USD target to SOL` | Solana: `target_volume_usd` is set and the SOL price is unavailable. The body adds `service: "price_feed"`. | Retry in a few seconds, or send `target_volume` instead. |
| 400 | `bad_request` | `Average amount would be 0` | Solana: the computed average trade size is 0. EVM answers 500 `internal_error` with `average amount would be 0`. | Raise the target volume, or set `min_amount` and `max_amount` explicitly. |
| 422 | `unprocessable` | `No wallets available` | Solana: `wallet_pubkeys` is an empty array, or it is `null` and the launch has no holder wallets. | Send `null` to use every holder wallet, or add holder wallets with [Add wallets to a launch](/reference/launches/#add-launch-wallets). |
| 400 | `bad_request` | `token not launched` | EVM: the token is still a draft. Unlike Solana, EVM only estimates a session on a launched token. | Launch the token first with [Launch a token](/reference/launch-execution/#launch). |
| 500 | `internal_error` | `wallet_pubkeys provided but none matched launch wallets` | EVM: no entry of `wallet_pubkeys` is a wallet of the launch. | List addresses of the launch's own wallets, or send `null` to use all of them. |
| 500 | `internal_error` | `No wallets available for volume bot` | EVM: `wallet_pubkeys` is an empty array, or the launch holds no usable wallet. | Send `null` to use every launch wallet, or list at least one launch wallet. |
| 500 | `internal_error` | `Bundle mode needs a bundle relay, which this chain has none of` | EVM: `mode` is `Bundle` on a chain that has no bundle relay. | Use `Organic` mode on this chain. |
| 500 | `internal_error` | `target_volume too small (below one trade); send it in wei or use target_volume_usd (micro-USD)` | EVM: the target is smaller than one trade of `max_amount`, typically a target sent in whole units instead of wei. | Send `target_volume` in wei, or `target_volume_usd` in micro-USD. |
| 500 | `internal_error` | `the launch quote cannot be resolved right now, retry in a moment` | EVM: the launch names a quote token that cannot be resolved right now. | Retry in a few seconds. |
| 500 | `internal_error` | `native price unavailable for USD target` | EVM: `target_volume_usd` is set and the chain's native price is unavailable. | Retry in a few seconds, or send `target_volume` in wei instead. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/launch/volume/estimate/101000000004217" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "mode": "Organic",
  "end_condition": {
    "TimeBased": {
      "target_volume_usd": "25000000000",
      "duration": 7200
    }
  },
  "wallet_pubkeys": [
    "3pGh8WcR5vTn2YkLz9QmXbE7aDs4FjU6wHrN1tKyPqVe",
    "6rVb2NqT8xK4mWc9HsZpG7eYjD3uLfA5tRnE1kQwXzMh",
    "BqW7nR3tY5kP9xC2vM8hL4dJ6sF1aZ3gE7uN5rT2yKpX"
  ],
  "wave_intensity": 0.6
}'
```

#### Example response

```json
{
  "ok": true,
  "estimate": {
    "round_trips": 240,
    "wallets": [
      "3pGh8WcR5vTn2YkLz9QmXbE7aDs4FjU6wHrN1tKyPqVe",
      "6rVb2NqT8xK4mWc9HsZpG7eYjD3uLfA5tRnE1kQwXzMh",
      "BqW7nR3tY5kP9xC2vM8hL4dJ6sF1aZ3gE7uN5rT2yKpX"
    ],
    "cost": 820000000,
    "min_balance_per_wallet": 450000000,
    "min_duration_secs": 240
  }
}
```

### Cancel a Volume Bot session

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

Stops the launch's planned or running Volume Bot 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 marks the launch's latest session `Cancelled` whatever its state, including a `Planned` or finished one, and answers `ok` when there is none. On EVM only a `Running` session is cancelled; a `Planned` one stays planned until [discarded](/reference/volume-bot/#discard-volume-bot).

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

#### Example request

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

#### Example response

```json
{
  "ok": true,
  "message": "Volume bot cancelled"
}
```

### Discard a Volume Bot session

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

Clears a planned or finished Volume Bot 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.

On Solana a running session is refused with `409`. On EVM the call answers `ok` and leaves a running session in place.

#### 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` | Solana: a Volume Bot session is running. EVM does not refuse: it answers `ok` and leaves the running session in place. | Stop it with [Cancel a Volume Bot session](/reference/volume-bot/#cancel-volume-bot) first, then discard. |

#### Example request

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

#### Example response

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