# Sniper Guard

> Watch a launch for buys from outside wallets and react when they cross a threshold.

Sniper Guard counts the quote that wallets outside the launch spend buying the token. When the total crosses `max_external_quote`, or when an auto-nuke timer runs out, it sells the launch wallets or finalizes the launch early, depending on `trigger_mode`.

A guard is planned for a launch and runs with it. The web app polls its status every 5 seconds.

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

## Endpoints

- `POST /launch/sniper-guard/plan/{launch_id}`: Plan a Sniper Guard
- `GET /launch/sniper-guard/status/{launch_id}`: Retrieve Sniper Guard status
- `POST /launch/sniper-guard/cancel/{launch_id}`: Cancel a Sniper Guard
- `POST /launch/sniper-guard/discard/{launch_id}`: Discard a Sniper Guard session

## The Sniper Guard status object

The launch's Sniper Guard session and, while the guard runs, its live counters.

- `status` (enum): Session state. Possible values: `None`, `Planned`, `Running`, `Completed`, `Failed`, `Cancelled`.
- `is_live` (boolean): `true` while the guard task is running on the server.
- `info` (object): Session details. Absent when `status` is `None`.
  - `params` (object): The configuration saved by the plan call; same fields as its request body.
  - `started_at` (integer | null): Unix timestamp the session started. `0` on Solana and `null` on EVM until it starts.
  - `ended_at` (integer | null): Unix timestamp the session ended. `0` on Solana and `null` on EVM until it ends.
  - `status_reason` (string | null): Why the session ended or failed, when known.
- `live_stats` (object): Live counters, present while the guard runs.
  - `external_quote_bought` (integer | string): Quote bought by external wallets so far, raw units.
  - `max_external_quote` (integer | string): Configured threshold, raw units.
  - `remaining_quote` (integer | string): Quote left before the guard triggers, raw units.
  - `auto_nuke_remaining_secs` (integer | null): Seconds left before an auto-nuke timer fires.
  - `external_sol_bought` (integer | string): Legacy name of `external_quote_bought`.
  - `max_external_sol` (integer | string): Legacy name of `max_external_quote`.
  - `remaining_sol` (integer | string): Legacy name of `remaining_quote`.

```json
{
  "status": "Running",
  "is_live": true,
  "info": {
    "params": {
      "enabled": true,
      "max_external_quote": 2000000000,
      "whitelist": [],
      "trigger_mode": "nuke_keep_dev",
      "end_condition": {
        "timed": {
          "duration_secs": 600
        }
      },
      "auto_nuke_delay_secs": null
    },
    "started_at": 1793655010,
    "ended_at": 0,
    "status_reason": null
  },
  "live_stats": {
    "external_quote_bought": 850000000,
    "max_external_quote": 2000000000,
    "remaining_quote": 1150000000,
    "external_sol_bought": 850000000,
    "max_external_sol": 2000000000,
    "remaining_sol": 1150000000
  }
}
```

### Plan a Sniper Guard

`POST /launch/sniper-guard/plan/{launch_id}`

Saves a Sniper Guard configuration for the launch as `Planned`. (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 overwrites the saved configuration of the `Planned` guard. While the guard runs, a repeat answers `409`.

Calling it again before the guard runs replaces the saved configuration. The backend rejects an enabled guard with neither a positive `max_external_quote` nor an `auto_nuke_delay_secs`, an `auto_nuke_delay_secs` of 0, and `complete_early` combined with an auto-nuke timer.

> When it triggers, the guard can sell launch wallets and finalize the launch without further confirmation.

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

- `enabled` (boolean, required): Whether the guard is active. A disabled guard skips every other check.
- `max_external_quote` (integer | string, optional): Quote amount external wallets may buy before the guard triggers, raw quote units (lamports on SOL-quoted launches). Must be greater than 0 when enabled, unless `auto_nuke_delay_secs` is set.
- `max_external_sol` (integer | string, optional): Legacy name of `max_external_quote`, still accepted.
- `trigger_mode` (enum, optional, default "nuke"): What the guard does when it triggers. `nuke` sells every launch wallet including the dev and finalizes the launch; `nuke_keep_dev` sells all but the dev; `nuke_dev_only` sells the dev only and finalizes; `nuke_dev_only_continue` sells the dev only and keeps the launch running; `complete_early` stops holder buys and finalizes without selling. Possible values: `nuke`, `nuke_keep_dev`, `nuke_dev_only`, `nuke_dev_only_continue`, `complete_early`.
- `whitelist` (array<string>, optional): Additional wallets whose buys are not counted as external. The launch's own wallets are always excluded.
- `end_condition` (object | string, optional, default "until_complete"): When monitoring stops: `"until_complete"` (until the launch finishes) or `{ "timed": { "duration_secs": N } }`.
- `auto_nuke_delay_secs` (integer | null, optional): Triggers after this many seconds instead of watching external buys. Must be greater than 0, and cannot be combined with `complete_early`.

#### 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` | `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` | `max_external_quote must be greater than 0 when enabled` | EVM launches and launch groups: `enabled` is `true` with no `auto_nuke_delay_secs` and a `max_external_quote` of 0 or missing. | Send a positive `max_external_quote`, or set `auto_nuke_delay_secs` instead. |
| 400 | `bad_request` | `auto_nuke_delay_secs must be greater than 0` | EVM launches and launch groups: `auto_nuke_delay_secs` is 0. | Send a positive `auto_nuke_delay_secs`, or `null` to watch external buys instead. |
| 400 | `bad_request` | `complete_early trigger mode is not allowed with auto-nuke timer` | EVM launches and launch groups: `trigger_mode` is `complete_early` together with an `auto_nuke_delay_secs`. | Pick another `trigger_mode`, or drop `auto_nuke_delay_secs`. |
| 500 | `internal_error` | `max_external_quote must be greater than 0 when enabled` | Solana: the same three validation rules fail. Solana answers them with `500` and the same messages: `max_external_quote must be greater than 0 when enabled`, `auto_nuke_delay_secs must be greater than 0`, `complete_early trigger mode is not allowed with auto-nuke timer`. | Fix the parameter named in `message`; do not retry the same body. |
| 409 | `conflict` | `Sniper guard task already running` | The launch's guard is already running (EVM: also when its saved session is `Running`). | Leave the running guard as it is, or stop it with [Cancel a Sniper Guard](/reference/sniper-guard/#cancel-sniper-guard) before planning a new one. |
| 400 | `bad_request` | `launch group plan can only be edited while draft` | `launch_id` is a multi-launch group container whose plan is no longer a draft. | Plan the guard before the group launches; once it resolves, plan it on the winning member's launch ID. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/launch/sniper-guard/plan/101000000004217" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": true,
  "max_external_quote": "2000000000",
  "trigger_mode": "nuke_keep_dev",
  "whitelist": [],
  "end_condition": {
    "timed": {
      "duration_secs": 600
    }
  }
}'
```

#### Example response

```json
{
  "ok": true,
  "message": "Successfully planned sniper guard"
}
```

### Retrieve Sniper Guard status

`GET /launch/sniper-guard/status/{launch_id}`

Returns the launch's Sniper Guard session and its live 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 Sniper Guard status object.

- `status` (enum): Session state. Possible values: `None`, `Planned`, `Running`, `Completed`, `Failed`, `Cancelled`.
- `is_live` (boolean): `true` while the guard task is running on the server.
- `info` (object): Session details. Absent when `status` is `None`.
  - `params` (object): The configuration saved by the plan call; same fields as its request body.
  - `started_at` (integer | null): Unix timestamp the session started. `0` on Solana and `null` on EVM until it starts.
  - `ended_at` (integer | null): Unix timestamp the session ended. `0` on Solana and `null` on EVM until it ends.
  - `status_reason` (string | null): Why the session ended or failed, when known.
- `live_stats` (object): Live counters, present while the guard runs.
  - `external_quote_bought` (integer | string): Quote bought by external wallets so far, raw units.
  - `max_external_quote` (integer | string): Configured threshold, raw units.
  - `remaining_quote` (integer | string): Quote left before the guard triggers, raw units.
  - `auto_nuke_remaining_secs` (integer | null): Seconds left before an auto-nuke timer fires.
  - `external_sol_bought` (integer | string): Legacy name of `external_quote_bought`.
  - `max_external_sol` (integer | string): Legacy name of `max_external_quote`.
  - `remaining_sol` (integer | string): Legacy name of `remaining_quote`.

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

#### Example response

```json
{
  "status": "Running",
  "is_live": true,
  "info": {
    "params": {
      "enabled": true,
      "max_external_quote": 2000000000,
      "whitelist": [],
      "trigger_mode": "nuke_keep_dev",
      "end_condition": {
        "timed": {
          "duration_secs": 600
        }
      },
      "auto_nuke_delay_secs": null
    },
    "started_at": 1793655010,
    "ended_at": 0,
    "status_reason": null
  },
  "live_stats": {
    "external_quote_bought": 850000000,
    "max_external_quote": 2000000000,
    "remaining_quote": 1150000000,
    "external_sol_bought": 850000000,
    "max_external_sol": 2000000000,
    "remaining_sol": 1150000000
  }
}
```

### Cancel a Sniper Guard

`POST /launch/sniper-guard/cancel/{launch_id}`

Stops the launch's planned or running Sniper Guard. (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 leaves the guard `Cancelled` and stops nothing more.

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

#### Example response

```json
{
  "ok": true,
  "message": "Sniper guard successfully cancelled"
}
```

### Discard a Sniper Guard session

`POST /launch/sniper-guard/discard/{launch_id}`

Clears a finished Sniper Guard 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 finds nothing to clear and answers `200`.

#### 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. |
| 409 | `conflict` | `Cannot discard running session` | Solana: the guard task is still running. | Stop the guard with [Cancel a Sniper Guard](/reference/sniper-guard/#cancel-sniper-guard) first, then discard. |
| 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/sniper-guard/discard/101000000004217" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "ok": true,
  "message": "Successfully discarded sniper guard session status"
}
```
