# Launch scripts

> Save a launch plan as a script, launch it and steer it while it runs.

A script plan replaces the launch method with a script that states every step of the launch: which wallet groups buy, when, and on what conditions. You save it with its wallet groups, fund it like any plan, launch it, then follow and steer it through its panel.

Script plans are restricted to admin sessions unless the API enables them for every license; other sessions get 403 `forbidden`. Refusals keep their JSON body, with `code`, `message` and, for invalid scripts, an `errors` list.

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

## Endpoints

- `POST /launch/update-launch-plan/{launch_id}`: Save a script plan
- `POST /launch/{chain_id}/{launch_id}/script/validate`: Validate a script
- `POST /launch/funding/get-expected-funding/{launch_id}`: Retrieve script plan funding
- `POST /launch/{launch_id}`: Launch a script plan
- `GET /launch/{chain_id}/{launch_id}/script/panel`: Retrieve the script panel
- `GET /launch/{chain_id}/{launch_id}/script/journal`: List script journal lines
- `POST /launch/{chain_id}/{launch_id}/script/control`: Control a script step
- `POST /launch/{chain_id}/{launch_id}/script/input`: Write a script input

### Save a script plan

`POST /launch/update-launch-plan/{launch_id}`

Saves a script and its wallet groups as the launch plan. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. Saving overwrites the stored plan, so a repeat stores the same plan.

A body that carries `script` is a script plan and carries nothing else of a regular plan: no `dev`, no launch method, no timings. The script declares its wallet groups; send exactly as many wallets per group, in rank order. The whole plan is validated at once.

Saving a regular plan with [Update the launch plan](/reference/launches/#update-launch-plan) clears the script.

#### Path parameters

- `launch_id` (string, required): Public ID of the launch.

#### Body parameters

- `script` (object, required): The script.
- `groups` (object, required): Wallets of each group the script declares, keyed by group name, in rank order. Each wallet is `{"key": "None"}` (generated), `{"key": {"pubkey"}}` (aged) or `{"key": {"secret"}}` (a managed key, which wins over `pubkey`).
- `funder` (object, required): Funder wallet, shaped like a group wallet.
- `funding_type` (enum, required): How the funder spreads native to the wallets. Possible values: `Classic`, `Cex`.
- `scheduled_mode` (boolean, optional): Must be `false`: a script plan launches at once.

#### Returns 200 OK

Returns the plan as Retrieve a launch reads it back, with the funding each wallet needs.

- `ok` (boolean): `true` when the request succeeded.
- `funder_required_native` (integer): Native the funder needs, in base units.
- `requirements` (object): Per-group wallet needs: `groups[].wallets[]` with `rank`, `need_lamports` and `gas_lamports`, plus `totals`.
- `script` (object): The saved script.
- `groups` (object): The group wallets, each `{"key": {"pubkey"}}`.
- `funder` (object): The funder wallet.
- `funding_type` (string): Funding type.
- `scheduled_mode` (boolean): Always `false`.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `invalid launch id format` | `launch_id` is not a valid launch ID. | Pass the `launch_id` returned when the launch was created, as listed by [List the license's launches](/reference/licenses/#list-mints). |
| 400 | `bad_request` | `<field>: a script plan's request carries only script, groups, funder, funding_type and scheduled_mode; the script states the rest, its creator among its groups` | The body carries a field of a regular plan. A script plan's body carries only `script`, `groups`, `funder`, `funding_type` and `scheduled_mode`. | Send only those fields, and state the rest in the script. |
| 400 | `bad_request` | `scheduled_mode: a script plan launches at once` | `scheduled_mode` is `true`, but a script plan launches at once. | Send `scheduled_mode` as `false`, or omit it. |
| 400 | `bad_request` | `script: a script plan runs a pump.fun create of the launch's own` | The launch can't take a script plan. It must create its own token: on Solana on pump.fun, quoted in SOL; on EVM on four.meme, Flap or Knot on BSC. Ansem and allowlist launches can't take one. | Save a regular plan with [Update the launch plan](/reference/launches/#update-launch-plan) instead. |
| 400 | `script_invalid` | `script: <path>: <message>; ...` | The script has errors, all listed in `errors` (see [Validate a script](#validate-script)). | Check the script with [Validate a script](/reference/launch-scripts/#validate-script), then save it again. |
| 400 | `bad_request` | `groups.<group>: the script declares <count> wallets, <n> given` | A group has the wrong number of wallets, or names a group the script doesn't declare. | Send exactly as many wallets per group as the script declares, in rank order. |
| 400 | `bad_request` | `script: tokens.a.create.params.creator: the creator is not a wallet of the groups given` | The script's creator is not one of the wallets in `groups`. | Name as creator a wallet from one of the groups you send. |
| 400 | `bad_request` | `One of <what> keys is invalid` | A key in `groups` or `funder` is invalid or repeated, is an EVM address on a Solana launch, or is a secret key your license may not set. | Send each wallet once, as a valid key for the launch's chain. |
| 403 | `forbidden` | `admin role required` | Your session has no script access. | Call this endpoint from an admin session. |
| 404 | `not_found` | `Secret not found for pubkey: <pubkey>` | A wallet given by public key isn't one your license holds. | Name only wallets your license holds, as listed by [List wallets](/reference/wallets/#list-wallets). |
| 404 | `not_found` | `launch not found` | No launch with this ID belongs to your license. | Check the ID, and that your token is upgraded onto the license that owns the launch. |
| 500 | `internal_error` | `Token already launched` | On Solana, the launch has already been deployed, so its plan can't change. | Save script plans only on launches that have not been deployed. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/launch/update-launch-plan/101482937561204" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "script": {
    "version": 1,
    "wallets": {
      "dev": {
        "count": 1
      },
      "holders": {
        "count": 2
      }
    },
    "steps": {}
  },
  "groups": {
    "dev": [
      {
        "key": "None"
      }
    ],
    "holders": [
      {
        "key": "None"
      },
      {
        "key": {
          "pubkey": "GwjXHJRZCrZjmRTzfuBCFkeuMmy6PxNMET4cPSmsvahJ"
        }
      }
    ]
  },
  "funder": {
    "key": {
      "pubkey": "EpvJTvDWrKDjJcVw3DrMPM4vvZA1mQfo8NdUTsuzwjkq"
    }
  },
  "funding_type": "Classic",
  "scheduled_mode": false
}'
```

#### Example response

```json
{
  "ok": true,
  "funder_required_native": 412000000,
  "requirements": {
    "groups": [
      {
        "name": "holders",
        "count": 2,
        "wallets": [
          {
            "rank": 0,
            "need_lamports": 205000000,
            "gas_lamports": 5000000
          },
          {
            "rank": 1,
            "need_lamports": 155000000,
            "gas_lamports": 5000000
          }
        ]
      }
    ],
    "totals": {}
  },
  "script": {
    "version": 1,
    "wallets": {
      "dev": {
        "count": 1
      },
      "holders": {
        "count": 2
      }
    },
    "steps": {}
  },
  "groups": {
    "dev": [
      {
        "key": {
          "pubkey": "BZJTwe2bzzTQBwy5VQwwrhbzbMUbQoBZ59F9g3fUUtZU"
        }
      }
    ],
    "holders": [
      {
        "key": {
          "pubkey": "HBwqDp7Qpmzos1wZhr5ZpwfsedZFGHubfdibhHBeH47Z"
        }
      },
      {
        "key": {
          "pubkey": "GwjXHJRZCrZjmRTzfuBCFkeuMmy6PxNMET4cPSmsvahJ"
        }
      }
    ]
  },
  "funder": {
    "key": {
      "pubkey": "EpvJTvDWrKDjJcVw3DrMPM4vvZA1mQfo8NdUTsuzwjkq"
    }
  },
  "funding_type": "Classic",
  "scheduled_mode": false
}
```

### Validate a script

`POST /launch/{chain_id}/{launch_id}/script/validate`

Checks a script against a launch without saving it. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. Validation saves nothing and sends nothing.

Answers 200 with every error found; `ok` is `false` when there is any, including unfinished funding of a draft.

> Not called by the current web app.

#### Path parameters

- `chain_id` (enum, required): Chain of the launch. Possible values: `sol`, `eth`, `bsc`, `base`, `robinhood`, `monad`, `arc`, `xlayer`.
- `launch_id` (string, required): Public ID of the launch.

#### Body parameters

- `script` (object, required): Script to check.

#### Returns 200 OK

- `ok` (boolean): `true` when the request succeeded.
- `errors` (array<object>): Errors found.
  - `code` (string): Error code, for example `script_plan` or `unknown_action`.
  - `path` (string): Dotted path into the script, such as `steps.snipe.params.buys.1.wallet`. Empty for plan-level errors.
  - `position` (integer | null): Position in the script source.
  - `feature` (string | null): Language feature involved.
  - `message` (string): What is wrong.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `unknown chain "<chain>"` | `chain_id` is not a known chain, or `launch_id` belongs to another chain (`this launch id belongs to another chain`). | Pass the launch's own chain, such as `sol` or `bsc`, with its `launch_id`. |
| 400 | `bad_request` | `invalid launch id format` | `launch_id` is not a valid launch ID. | Pass the `launch_id` returned when the launch was created, as listed by [List the license's launches](/reference/licenses/#list-mints). |
| 403 | `forbidden` | `admin role required` | Your session has no script access. | Call this endpoint from an admin session. |
| 404 | `not_found` | `launch not found` | No launch with this ID exists. | Check `chain_id` and `launch_id`. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/launch/sol/101482937561204/script/validate" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "script": {
    "version": 1,
    "wallets": {
      "dev": {
        "count": 1
      }
    },
    "steps": {
      "a": {
        "product": {
          "name": "nope",
          "params": {}
        }
      }
    }
  }
}'
```

#### Example response

```json
{
  "ok": false,
  "errors": [
    {
      "code": "unknown_action",
      "path": "steps.a.product",
      "position": null,
      "feature": null,
      "message": "no product verb nope is registered"
    }
  ]
}
```

### Retrieve script plan funding

`POST /launch/funding/get-expected-funding/{launch_id}`

Returns the funding a saved script plan needs. (Bearer JWT)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. It only reads the stored plan.

For a script plan the body is not read: the stored script states the plan. Projections such as `max_loss` and market caps are `null`.

> Same route as [Retrieve expected funding](/reference/launch-funding/#get-expected-funding) for regular plans.

#### Path parameters

- `launch_id` (string, required): Public ID of the launch.

#### Returns 200 OK

- `expected_funding` (string): Total funding needed, in native base units. Number or numeric string.
- `expected_supply` (string | null): Expected token supply bought. Number or numeric string.
- `breakdown` (object): Funding split: `dev_supply_cost`, `dev_extra_funding`, `holder_supply_cost`, `holder_extra_funding`, `funding_extra_funding`.
- `max_loss` (string | null): Projected maximum loss.
- `estimated_duration_ms` (integer): Estimated duration of the launch, in milliseconds.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `invalid launch id format` | `launch_id` is not a valid launch ID. | Pass the `launch_id` returned when the launch was created, as listed by [List the license's launches](/reference/licenses/#list-mints). |
| 404 | `not_found` | `launch not found` | No launch with this ID belongs to your license. | Check the ID, and that your token is upgraded onto the license that owns the launch. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/launch/funding/get-expected-funding/101482937561204" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Example response

```json
{
  "expected_funding": "412000000",
  "expected_supply": null,
  "breakdown": {
    "dev_supply_cost": "200000000",
    "dev_extra_funding": "30000000",
    "holder_supply_cost": "160000000",
    "holder_extra_funding": "10000000",
    "funding_extra_funding": "12000000"
  },
  "max_loss": null
}
```

### Launch a script plan

`POST /launch/{launch_id}`

Starts the stored script plan of a launch, streaming its journal. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Check before retrying. A plan still open refuses a repeat with 409 `plan_active`, but one that ended before deploying starts again. Read its `status` with [Retrieve the script panel](/reference/launch-scripts/#retrieve-script-panel) before retrying.

Send no body. The answer is the usual launch stream: the plan's journal as `data: {step, total, message, ok}` events until the plan ends. Follow and steer it with the panel and control routes.

#### Path parameters

- `launch_id` (string, required): Public ID of the launch.

#### Returns 200 OK

Streams Launch progress events, one `data:` line each.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `invalid launch id format` | `launch_id` is not a valid launch ID. | Pass the `launch_id` returned when the launch was created, as listed by [List the license's launches](/reference/licenses/#list-mints). |
| 400 | `bad_request` | `Launch script refused: <reason>` | On EVM, the stored script doesn't state a mode the launch can run. | Correct the script, then save it again with [Save a script plan](/reference/launch-scripts/#save-script-plan). |
| 403 | `forbidden` | `admin role required: this launch's plan is a script` | Your session has no script access. | Launch it from an admin session. |
| 404 | `not_found` | `launch not found` | No launch with this ID belongs to your license. | Check the ID, and that your token is upgraded onto the license that owns the launch. |
| 409 | `launch_running` | `a launch task is already running for this launch` | The launch is already running. | Follow it with [Retrieve the script panel](/reference/launch-scripts/#retrieve-script-panel). |
| 409 | `plan_active` | `this launch has a plan that has not ended` | A plan is already active for this launch. The body adds its `plan_id` and `status`. | Follow or stop that plan with [Control a script step](/reference/launch-scripts/#control-script-step). |
| 409 | `conflict` | `Funding not completed` | The launch wallets don't hold the funding the script needs yet. | Fund them with [Fund the launch wallets](/reference/launch-execution/#fund-launch-wallets), then launch again. |
| 422 | `unprocessable` | `a script plan's launch options are its script's: send none` | Launch query options are refused: the script states them. | Send the request without `block1`, `exact_buyback`, `direct_buyback` or cadence options. |
| 422 | `script_invalid` | `the script has errors` | The stored script no longer passes validation; every error is listed in `errors`. | Check it with [Validate a script](/reference/launch-scripts/#validate-script), then save it again. |
| 500 | `internal_error` | `Token already launched` | On Solana, the launch has already been deployed. | Follow the plan that deployed it with [Retrieve the script panel](/reference/launch-scripts/#retrieve-script-panel). |

#### Example request

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

#### Example response

```text
[
  {
    "step": 1,
    "total": 3,
    "ok": true,
    "message": "deploy landed"
  },
  {
    "step": 2,
    "total": 3,
    "ok": true,
    "message": "snipe landed"
  }
]
```

### Retrieve the script panel

`GET /launch/{chain_id}/{launch_id}/script/panel`

Returns the live state of the launch's script plan: steps, inputs and approvals. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: allowed.
- Retry: Safe to retry.

Describes the launch's open plan, else its newest. `verbs` lists what you may apply to each step now, and `control_seq` is the `expect` value of a `skip`. The app polls it every 2 seconds while visible (10 seconds hidden) until the plan is `completed`, `aborted` or `failed`.

> `ui` objects are free-form display hints the plan never reads.

#### Path parameters

- `chain_id` (enum, required): Chain of the launch. Possible values: `sol`, `eth`, `bsc`, `base`, `robinhood`, `monad`, `arc`, `xlayer`.
- `launch_id` (string, required): Public ID of the launch.

#### Returns 200 OK

- `ok` (boolean): `true` when the request succeeded.
- `plan_id` (string): Plan ID (UUID).
- `status` (string): Plan status, such as `running`, `completed`, `aborted` or `failed`.
- `origin` (string): Where the script came from, such as `custom`.
- `version` (integer): Plan version.
- `running_here` (boolean): This API host runs the plan.
- `panel` (object): Panel state.
  - `plan` (string): Plan ID.
  - `status` (string): Plan status.
  - `steps` (array<object>): Steps with `key`, `label`, `form` (`single`, `continuous`, `repeat`, `for_each`), `status`, `epoch`, `paused_by`, `verbs`, `control_seq`, `skip_next` and `ui`.
  - `inputs` (array<object>): Value inputs with `name`, `label`, `unit`, `min`, `max`, `step`, `default`, `value`, `revision`, `affects` and `ui`.
  - `approvals` (array<object>): Approval inputs with `name`, `label`, `ui`, `approved`, `closed` and `by`.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `unknown chain "<chain>"` | `chain_id` is not a known chain, or `launch_id` belongs to another chain (`this launch id belongs to another chain`). | Pass the launch's own chain, such as `sol` or `bsc`, with its `launch_id`. |
| 400 | `bad_request` | `invalid launch id format` | `launch_id` is not a valid launch ID. | Pass the `launch_id` returned when the launch was created, as listed by [List the license's launches](/reference/licenses/#list-mints). |
| 403 | `forbidden` | `admin role required` | Your session has no script access. | Call this endpoint from an admin session. |
| 404 | `not_found` | `launch not found` | No launch with this ID exists. | Check `chain_id` and `launch_id`. |
| 404 | `not_found` | `this launch has no script plan` | No script plan has started on this launch. The app's panel hook, not the SDK, turns this into `null`. | Start one with [Launch a script plan](/reference/launch-scripts/#launch-script-plan). |

#### Example request

```bash
curl "https://api-mig.proxima.tools/launch/sol/101482937561204/script/panel" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "ok": true,
  "plan_id": "84ac09e4-2eaa-42b8-9236-d5c07d2efffb",
  "status": "running",
  "origin": "custom",
  "version": 4,
  "running_here": true,
  "panel": {
    "plan": "84ac09e4-2eaa-42b8-9236-d5c07d2efffb",
    "status": "running",
    "steps": [
      {
        "key": "snipe",
        "label": "Snipe",
        "form": "single",
        "status": "landed",
        "epoch": 1,
        "paused_by": [],
        "verbs": [],
        "control_seq": 0
      },
      {
        "key": "stagger",
        "label": "Stagger buys",
        "form": "repeat",
        "status": "running",
        "epoch": 1,
        "paused_by": [],
        "verbs": [
          "cancel",
          "skip"
        ],
        "control_seq": 2
      }
    ],
    "inputs": [
      {
        "name": "size",
        "label": "Buy size",
        "unit": "SOL",
        "min": "0.05",
        "max": "1",
        "step": "0.05",
        "default": "0.2",
        "value": "0.25",
        "revision": 1
      }
    ],
    "approvals": [
      {
        "name": "stop",
        "label": "Stop the stagger",
        "ui": {
          "color": "#d64545"
        },
        "approved": false,
        "closed": false,
        "by": [
          "OWNER"
        ]
      }
    ]
  }
}
```

### List script journal lines

`GET /launch/{chain_id}/{launch_id}/script/journal`

Pages through the journal of the launch's script plan. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: allowed.
- Retry: Safe to retry.

Pass `next_after` as the next `after` while `more` is `true`.

> Not called by the current web app.

#### Path parameters

- `chain_id` (enum, required): Chain of the launch. Possible values: `sol`, `eth`, `bsc`, `base`, `robinhood`, `monad`, `arc`, `xlayer`.
- `launch_id` (string, required): Public ID of the launch.

#### Query parameters

- `after` (integer, optional, default "0"): Return lines after this sequence number. Start at `0`.
- `limit` (integer, optional, default "100"): Lines per page, 1 to 500. The SDK sends 200.

#### Returns 200 OK

- `ok` (boolean): `true` when the request succeeded.
- `plan_id` (string): Plan ID.
- `status` (string): Plan status.
- `lines` (array<object>): Journal lines.
  - `seq` (integer): Sequence number.
  - `kind` (string): Line kind, such as `plan.status`.
  - `subject` (string): What the line is about.
  - `detail` (object | null): Details.
- `next_after` (integer): Value of `after` for the next page.
- `more` (boolean): More lines are available.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `unknown chain "<chain>"` | `chain_id` is not a known chain, or `launch_id` belongs to another chain (`this launch id belongs to another chain`). | Pass the launch's own chain, such as `sol` or `bsc`, with its `launch_id`. |
| 400 | `bad_request` | `invalid launch id format` | `launch_id` is not a valid launch ID. | Pass the `launch_id` returned when the launch was created, as listed by [List the license's launches](/reference/licenses/#list-mints). |
| 403 | `forbidden` | `admin role required` | Your session has no script access. | Call this endpoint from an admin session. |
| 404 | `not_found` | `launch not found` | No launch with this ID exists. | Check `chain_id` and `launch_id`. |
| 404 | `not_found` | `this launch has no script plan` | No script plan has started on this launch. | Start one with [Launch a script plan](/reference/launch-scripts/#launch-script-plan). |

#### Example request

```bash
curl "https://api-mig.proxima.tools/launch/sol/101482937561204/script/journal?after=0" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "ok": true,
  "plan_id": "84ac09e4-2eaa-42b8-9236-d5c07d2efffb",
  "status": "running",
  "lines": [
    {
      "seq": 1,
      "kind": "plan.status",
      "subject": "plan",
      "detail": {}
    }
  ],
  "next_after": 1,
  "more": false
}
```

### Control a script step

`POST /launch/{chain_id}/{launch_id}/script/control`

Cancels, pauses, resumes or skips a step, sets a value input, or grants an approval. (Admin JWT · internal)

- Token: Upgraded session token of an account with admin rights.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. Send the same `key`: a repeat answers the first call's record instead of applying it again.

Every call carries an idempotency `key`: the same key with the same call answers the same record. Refusals answer `{ok: false, code, message, record}`.

#### Path parameters

- `chain_id` (enum, required): Chain of the launch. Possible values: `sol`, `eth`, `bsc`, `base`, `robinhood`, `monad`, `arc`, `xlayer`.
- `launch_id` (string, required): Public ID of the launch.

#### Body parameters

- `verb` (enum, required): Control to apply. Possible values: `cancel`, `pause`, `resume`, `skip`, `set_input`, `approve`.
- `group` (enum, optional): Group the step belongs to. Defaults to `steps`. Possible values: `steps`, `finally`.
- `step` (string, optional): Step key. Required for every verb except `approve` and `set_input`.
- `input` (string, optional): Input to write. Required for `approve`, which grants an approval, and `set_input`, which sets a value input.
- `value` (string, optional): `set_input` only, required: the new value.
- `expect` (integer, optional): `skip` only, required: the step's current `control_seq`.
- `fires` (integer, optional): `skip` only: number of firings to skip.
- `reason` (string, optional): Why, kept in the record.
- `key` (string, required): Idempotency key.

#### Returns 200 OK

- `ok` (boolean): `true` when the request succeeded.
- `record` (object): The control as recorded.
  - `seq` (integer): Sequence number of the record.
  - `by` (object): Who applied it.
  - `key` (string): Idempotency key of the call.
  - `verb` (string): Verb applied.
  - `outcome` (string): Outcome, such as `applied`.
- `approved` (string): Name of the approval granted, for `approve`.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `unknown chain "<chain>"` | `chain_id` is not a known chain, or `launch_id` belongs to another chain (`this launch id belongs to another chain`). | Pass the launch's own chain, such as `sol` or `bsc`, with its `launch_id`. |
| 400 | `bad_request` | `invalid launch id format` | `launch_id` is not a valid launch ID. | Pass the `launch_id` returned when the launch was created, as listed by [List the license's launches](/reference/licenses/#list-mints). |
| 400 | `idempotency_key_required` | `key is required: the same key repeats the same answer` | `key` is missing or empty. | Send a unique `key` with every control. |
| 400 | `invalid_key` | `key is at most 128 characters` | `key` is longer than 128 characters. | Send a `key` of at most 128 characters. |
| 400 | `missing_field` | `a verb names its step in `step`` | A field the verb needs is missing: `step` for a step verb, `input` for `approve` and `set_input`, and `value` for `set_input`. | Send the fields the verb needs. |
| 400 | `verb_not_offered` | `"<verb>" is not offered here: pause, resume, cancel, skip, set_input or approve` | `verb` is not one this endpoint takes. | Send one of `pause`, `resume`, `cancel`, `skip`, `set_input` or `approve`. |
| 400 | `invalid_value` | `group is steps or finally, not "<group>"` | `group` is neither `steps` nor `finally`, `fires` is too large, or `approve` names a value input. | Correct the field the message names. |
| 400 | `unknown_input` | `the script declares no input <input>` | `approve` names an input the script doesn't declare. | Use an approval name listed under `approvals` by [Retrieve the script panel](/reference/launch-scripts/#retrieve-script-panel). |
| 400 | `if_match_required` | `skip names the control_seq it read, in `expect`` | The control needs the step's current `control_seq` in `expect`. | Send the step's `control_seq` from [Retrieve the script panel](/reference/launch-scripts/#retrieve-script-panel) as `expect`. |
| 403 | `forbidden` | `admin role required` | Your session has no script access. | Call this endpoint from an admin session. |
| 404 | `not_found` | `launch not found` | No launch with this ID exists. | Check `chain_id` and `launch_id`. |
| 404 | `not_found` | `this launch has no script plan` | No script plan has started on this launch. | Start one with [Launch a script plan](/reference/launch-scripts/#launch-script-plan). |
| 409 | `hold_refused` | `this host holds no running action: pause is refused, cancel stops the step` | This host holds no running action, so `pause` is refused. | Send `cancel` to stop the step instead. |
| 409 | `terminal` | `the plan has ended` | The plan is `completed`, `aborted` or `failed`, so it takes no more controls. | Check the plan's `status` with [Retrieve the script panel](/reference/launch-scripts/#retrieve-script-panel) before sending controls. |
| 409 | `key_reused` | `this idempotency key carried another call` | The `key` was already used for a different call. | Send a new `key` for each distinct control. |
| 409 | `role` | `this role may not do this` | The script reserves this control to another role. | Leave this control to the role the script names. |
| 409 | `plan_held_elsewhere` | `another process runs this plan: ask again` | Another host runs the plan. | Send the same call again. |
| 409 | `plan_gone` | `the plan's runner stopped before it answered` | The process running the plan stopped before it answered, so the control may not have been applied. | Send the same call with the same `key` again. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/launch/sol/101482937561204/script/control" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "verb": "skip",
  "step": "stagger",
  "expect": 2,
  "key": "ops-2026-10-28-skip-1",
  "reason": "skip one round"
}'
```

#### Example response

```json
{
  "ok": true,
  "record": {
    "seq": 3,
    "by": {
      "role": "operator"
    },
    "key": "ops-2026-10-28-skip-1",
    "verb": "skip",
    "outcome": "applied"
  }
}
```

### Write a script input

`POST /launch/{chain_id}/{launch_id}/script/input`

Grants an approval, sets a value input or sends an event to an input the running script declares. (Bearer JWT · internal)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. Send the same `key` for a value input or the same `id` for an event: a repeat answers the first call's record, or comes back with `duplicate: true`. A second approval changes nothing.

What the body carries depends on the input's kind: an approval names its input alone, a value input carries `value` and an idempotency `key`, and an event input carries an arrival `id` and an optional `value`. An admin acts as the plan's operator; the license that owns the launch acts as its owner and cannot grant the launch's snipe approval.

#### Path parameters

- `chain_id` (enum, required): Chain of the launch. Possible values: `sol`, `eth`, `bsc`, `base`, `robinhood`, `monad`, `arc`, `xlayer`.
- `launch_id` (string, required): Public ID of the launch.

#### Body parameters

- `input` (string, required): Name of an input the script declares.
- `id` (string, optional): Event input only, required: the arrival's ID, at most 128 bytes. The same ID is taken once.
- `value` (string, optional): Value input, required: the new value. Event input: an optional payload for the arrival.
- `key` (string, optional): Value input only, required: idempotency key, at most 128 characters.
- `expect` (integer, optional): Value input only: optional, passed to the plan with the write.
- `reason` (string, optional): Value input only: why, kept in the record.

#### Returns 200 OK

- `ok` (boolean): `true` when the request succeeded.
- `record` (object): The control as recorded.
  - `seq` (integer): Sequence number of the record.
  - `by` (object): Who applied it.
  - `key` (string): Idempotency key of the call.
  - `verb` (string): Verb applied.
  - `outcome` (string): Outcome, such as `applied`.
- `approved` (string): Name of the approval granted, for `approve`.
- `input` (string): Event input: the input the arrival was sent to.
- `id` (string): Event input: ID of the arrival.
- `count` (integer): Event input: arrival count reported by the plan.
- `duplicate` (boolean): Event input: `true` when this `id` was already taken, so nothing new arrived.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `invalid body: <path>: <cause>` | The body is not valid JSON, `input` is missing, a field has the wrong type, or the body has a field this endpoint does not take. | Send only `input`, `id`, `value`, `key`, `expect` and `reason`, with the types listed above. |
| 400 | `bad_request` | `unknown chain "<chain>"` | `chain_id` is not a known chain, or `launch_id` belongs to another chain (`this launch id belongs to another chain`). | Pass the launch's own chain, such as `sol` or `bsc`, with its `launch_id`. |
| 400 | `bad_request` | `invalid launch id format` | `launch_id` is not a valid launch ID. | Pass the `launch_id` returned when the launch was created, as listed by [List the license's launches](/reference/licenses/#list-mints). |
| 404 | `not_found` | `launch not found` | No launch with this ID exists. | Check `chain_id` and `launch_id`. |
| 403 | `forbidden` | `admin role or the launch's own license required` | Your session is neither an admin's nor that of the license that owns the launch. | Call it from an admin session or with a token of the license that owns the launch. |
| 404 | `not_found` | `this launch has no script plan` | No script plan has started on this launch. | Start one with [Launch a script plan](/reference/launch-scripts/#launch-script-plan). |
| 400 | `missing_field` | `input names the input the script declares` | `input` is empty. | Send the name of an input listed by [Retrieve the script panel](/reference/launch-scripts/#retrieve-script-panel). |
| 400 | `unknown_input` | `the script declares no input <input>` | `input` names an input the script does not declare. | Use an input name listed by [Retrieve the script panel](/reference/launch-scripts/#retrieve-script-panel). |
| 400 | `invalid_value` | `<input> is an input of kind <kind>, which this route does not take` | The input is of a kind this endpoint does not write. | Write only approval, value and event inputs. |
| 400 | `invalid_value` | `a value input is written under `key`, not an `id`` | A value input was sent with an `id`. | Drop `id` and send a `key`. |
| 400 | `missing_field` | `a value input carries its new value in `value`` | A value input was sent without `value`. | Send the new value in `value`. |
| 400 | `idempotency_key_required` | `key is required: the same key repeats the same answer` | A value input was sent without a `key`, or with an empty one. | Send a unique `key` with every write. |
| 400 | `invalid_key` | `key is at most 128 characters` | `key` is longer than 128 characters. | Send a `key` of at most 128 characters. |
| 400 | `invalid_value` | `an approval carries neither an id nor a value` | An approval was sent with an `id` or a `value`. | Send only `input` for an approval. |
| 403 | `snipe_approval` | `<input> is this launch's snipe: POST /snipe/{ext_id} grants it` | The launch's owner tried to grant the approval that stands for the launch's snipe. | Grant it with [Snipe a scheduled launch](/reference/launch-execution/#snipe-launch). |
| 400 | `invalid_value` | `an event arrives under its own `id`: it takes no key or expect` | An event input was sent with a `key` or `expect`. | Drop `key` and `expect` and send an `id`. |
| 400 | `missing_field` | `an event arrives under its own `id`: the same id is taken once` | An event input was sent without an `id`, or with an empty one. | Send a unique `id` for each arrival. |
| 400 | `invalid_value` | `an arrival's id is at most 128 bytes` | The event's `id` is longer than 128 bytes. | Send an `id` of at most 128 bytes. |
| 403 | `forbidden` | `this share does not grant automation.script` | The call comes through a launch share whose grant does not include `automation.script`. | Ask the launch's owner to add `automation.script` to the grant with [Update a grant](/reference/launch-sharing/#update-grant). |
| 409 | `terminal` | `the plan has ended` | The plan is `completed`, `aborted` or `failed`, so it takes no more inputs. | Check the plan's `status` with [Retrieve the script panel](/reference/launch-scripts/#retrieve-script-panel) before writing inputs. |
| 409 | `key_reused` | `this idempotency key carried another call` | A value input's `key` was already used for a different call. | Send a new `key` for each distinct write. |
| 409 | `plan_held_elsewhere` | `another process runs this plan: ask again` | Another host runs the plan. | Send the same call again. |
| 409 | `plan_gone` | `the plan's runner stopped before it answered` | The process running the plan stopped before it answered, so the input may not have been written. | Send the same call with the same `key` or `id` again. |
| 409 | `input_refused` | `<reason>` | The plan refused the event's arrival. The message is its reason. | Check the input in [Retrieve the script panel](/reference/launch-scripts/#retrieve-script-panel), then send the event again if it still applies. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/launch/sol/101482937561204/script/input" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "input": "size",
  "value": "0.3",
  "key": "ops-2026-10-28-size-2"
}'
```

#### Example response

```json
{
  "ok": true
}
```
