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.
- POST
/launch/update-launch-plan/{launch_id} - POST
/launch/{chain_id}/{launch_id}/script/validate - POST
/launch/funding/get-expected-funding/{launch_id} - POST
/launch/{launch_id} - GET
/launch/{chain_id}/{launch_id}/script/panel - GET
/launch/{chain_id}/{launch_id}/script/journal - POST
/launch/{chain_id}/{launch_id}/script/control - POST
/launch/{chain_id}/{launch_id}/script/input
Save a script plan
/launch/update-launch-plan/{launch_id} Saves a script and its wallet groups as the launch plan.
- 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 clears the script.
Path parameters
-
launch_idstring RequiredPublic ID of the launch.Example101482937561204
Body parameters application/json
-
scriptobject RequiredThe script. -
groupsobject RequiredWallets 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 overpubkey). -
funderobject RequiredFunder wallet, shaped like a group wallet. -
funding_typeenum RequiredHow the funder spreads native to the wallets.Possible valuesClassicCex -
scheduled_modeboolean OptionalMust befalse: a script plan launches at once.
Returns 200 OK · application/json
Returns the plan as Retrieve a launch reads it back, with the funding each wallet needs.
-
okbooleantruewhen the request succeeded. -
funder_required_nativeintegerNative the funder needs, in base units. -
requirementsobjectPer-group wallet needs:groups[].wallets[]withrank,need_lamportsandgas_lamports, plustotals. -
scriptobjectThe saved script. -
groupsobjectThe group wallets, each{"key": {"pubkey"}}. -
funderobjectThe funder wallet. -
funding_typestringFunding type. -
scheduled_modebooleanAlwaysfalse.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | 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. |
| 400 | bad_request | 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 is true, but a script plan launches at once. Send scheduled_mode as false, or omit it. |
| 400 | bad_request | 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 instead. |
| 400 | script_invalid | The script has errors, all listed in errors (see Validate a script). Check the script with Validate a script, then save it again. |
| 400 | bad_request | 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 | 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 | 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 | Your session has no script access. Call this endpoint from an admin session. |
| 404 | not_found | A wallet given by public key isn't one your license holds. Name only wallets your license holds, as listed by List wallets. |
| 404 | 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 | 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. |
Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role, 403 read_only_token and 429 when rate limited.
Web client proxima.launch.script.savePlan(launchId, body) src/lib/proxima/endpoints/launch/script.ts
Validate a script
/launch/{chain_id}/{launch_id}/script/validate Checks a script against a launch without saving it.
- 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.
Path parameters
-
chain_idenum RequiredChain of the launch.Possible valuessolethbscbaserobinhoodmonadarcxlayer -
launch_idstring RequiredPublic ID of the launch.Example101482937561204
Body parameters application/json
-
scriptobject RequiredScript to check.
Returns 200 OK · application/json
-
okbooleantruewhen the request succeeded. -
errorsarray<object>Errors found.Child attributes 5
-
codestringError code, for examplescript_planorunknown_action. -
pathstringDotted path into the script, such assteps.snipe.params.buys.1.wallet. Empty for plan-level errors. -
positioninteger | nullPosition in the script source. -
featurestring | nullLanguage feature involved. -
messagestringWhat is wrong.
-
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | 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 | 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. |
| 403 | forbidden | Your session has no script access. Call this endpoint from an admin session. |
| 404 | not_found | No launch with this ID exists. Check chain_id and launch_id. |
Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role, 403 read_only_token and 429 when rate limited.
Web client proxima.launch.script.validate(chainId, launchId, script) src/lib/proxima/endpoints/launch/script.ts
Retrieve script plan funding
/launch/funding/get-expected-funding/{launch_id} Returns the funding a saved script plan needs.
- 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.
Path parameters
-
launch_idstring RequiredPublic ID of the launch.Example101482937561204
Returns 200 OK · application/json
-
expected_fundingstringTotal funding needed, in native base units. Number or numeric string. -
expected_supplystring | nullExpected token supply bought. Number or numeric string. -
breakdownobjectFunding split:dev_supply_cost,dev_extra_funding,holder_supply_cost,holder_extra_funding,funding_extra_funding. -
max_lossstring | nullProjected maximum loss. -
estimated_duration_msintegerEstimated duration of the launch, in milliseconds.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | 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. |
| 404 | 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. |
Also the common errors: 401 for a missing or expired session or a base token (license_required), 403 read_only_token and 429 when rate limited.
Web client proxima.launch.script.expectedFunding(launchId) src/lib/proxima/endpoints/launch/script.ts
Launch a script plan
/launch/{launch_id} Starts the stored script plan of a launch, streaming its journal.
- 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 itsstatuswith Retrieve the 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_idstring RequiredPublic ID of the launch.Example101482937561204
Returns 200 OK · text/event-stream
Streams Launch progress events, one data: line each.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | 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. |
| 400 | bad_request | 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. |
| 403 | forbidden | Your session has no script access. Launch it from an admin session. |
| 404 | 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 | The launch is already running. Follow it with Retrieve the script panel. |
| 409 | plan_active | 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. |
| 409 | conflict | The launch wallets don't hold the funding the script needs yet. Fund them with Fund the launch wallets, then launch again. |
| 422 | unprocessable | 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 stored script no longer passes validation; every error is listed in errors. Check it with Validate a script, then save it again. |
| 500 | internal_error | On Solana, the launch has already been deployed. Follow the plan that deployed it with Retrieve the script panel. |
Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role, 403 read_only_token and 429 when rate limited.
Web client proxima.launch.script.launch(launchId) src/lib/proxima/endpoints/launch/script.ts
Retrieve the script panel
/launch/{chain_id}/{launch_id}/script/panel Returns the live state of the launch's script plan: steps, inputs and approvals.
- 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.
Path parameters
-
chain_idenum RequiredChain of the launch.Possible valuessolethbscbaserobinhoodmonadarcxlayer -
launch_idstring RequiredPublic ID of the launch.Example101482937561204
Returns 200 OK · application/json
-
okbooleantruewhen the request succeeded. -
plan_idstringPlan ID (UUID). -
statusstringPlan status, such asrunning,completed,abortedorfailed. -
originstringWhere the script came from, such ascustom. -
versionintegerPlan version. -
running_herebooleanThis API host runs the plan. -
panelobjectPanel state.Child attributes 5
-
planstringPlan ID. -
statusstringPlan status. -
stepsarray<object>Steps withkey,label,form(single,continuous,repeat,for_each),status,epoch,paused_by,verbs,control_seq,skip_nextandui. -
inputsarray<object>Value inputs withname,label,unit,min,max,step,default,value,revision,affectsandui. -
approvalsarray<object>Approval inputs withname,label,ui,approved,closedandby.
-
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | 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 | 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. |
| 403 | forbidden | Your session has no script access. Call this endpoint from an admin session. |
| 404 | not_found | No launch with this ID exists. Check chain_id and launch_id. |
| 404 | not_found | 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. |
Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role and 429 when rate limited.
Web client proxima.launch.script.panel(chainId, launchId) src/lib/proxima/endpoints/launch/script.ts
List script journal lines
/launch/{chain_id}/{launch_id}/script/journal Pages through the journal of the launch's script plan.
- 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.
Path parameters
-
chain_idenum RequiredChain of the launch.Possible valuessolethbscbaserobinhoodmonadarcxlayer -
launch_idstring RequiredPublic ID of the launch.Example101482937561204
Query parameters
-
afterinteger OptionalReturn lines after this sequence number. Start at0.Example0 -
limitinteger OptionalLines per page, 1 to 500. The SDK sends 200.
Returns 200 OK · application/json
-
okbooleantruewhen the request succeeded. -
plan_idstringPlan ID. -
statusstringPlan status. -
linesarray<object>Journal lines.Child attributes 4
-
seqintegerSequence number. -
kindstringLine kind, such asplan.status. -
subjectstringWhat the line is about. -
detailobject | nullDetails.
-
-
next_afterintegerValue ofafterfor the next page. -
morebooleanMore lines are available.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | 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 | 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. |
| 403 | forbidden | Your session has no script access. Call this endpoint from an admin session. |
| 404 | not_found | No launch with this ID exists. Check chain_id and launch_id. |
| 404 | not_found | No script plan has started on this launch. Start one with Launch a script plan. |
Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role and 429 when rate limited.
Web client proxima.launch.script.journal(chainId, launchId, after, limit?) src/lib/proxima/endpoints/launch/script.ts
Control a script step
/launch/{chain_id}/{launch_id}/script/control Cancels, pauses, resumes or skips a step, sets a value input, or grants an approval.
- 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_idenum RequiredChain of the launch.Possible valuessolethbscbaserobinhoodmonadarcxlayer -
launch_idstring RequiredPublic ID of the launch.Example101482937561204
Body parameters application/json
-
verbenum RequiredControl to apply.Possible valuescancelpauseresumeskipset_inputapprove -
groupenum OptionalGroup the step belongs to. Defaults tosteps.Possible valuesstepsfinally -
stepstring OptionalStep key. Required for every verb exceptapproveandset_input. -
inputstring OptionalInput to write. Required forapprove, which grants an approval, andset_input, which sets a value input. -
valuestring Optionalset_inputonly, required: the new value. -
expectinteger Optionalskiponly, required: the step's currentcontrol_seq. -
firesinteger Optionalskiponly: number of firings to skip. -
reasonstring OptionalWhy, kept in the record. -
keystring RequiredIdempotency key.
Returns 200 OK · application/json
-
okbooleantruewhen the request succeeded. -
recordobjectThe control as recorded.Child attributes 5
-
seqintegerSequence number of the record. -
byobjectWho applied it. -
keystringIdempotency key of the call. -
verbstringVerb applied. -
outcomestringOutcome, such asapplied.
-
-
approvedstringName of the approval granted, forapprove.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | 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 | 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. |
| 400 | idempotency_key_required | key is missing or empty. Send a unique key with every control. |
| 400 | invalid_key | key is longer than 128 characters. Send a key of at most 128 characters. |
| 400 | missing_field | 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 one this endpoint takes. Send one of pause, resume, cancel, skip, set_input or approve. |
| 400 | invalid_value | 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 | approve names an input the script doesn't declare. Use an approval name listed under approvals by Retrieve the script panel. |
| 400 | if_match_required | The control needs the step's current control_seq in expect. Send the step's control_seq from Retrieve the script panel as expect. |
| 403 | forbidden | Your session has no script access. Call this endpoint from an admin session. |
| 404 | not_found | No launch with this ID exists. Check chain_id and launch_id. |
| 404 | not_found | No script plan has started on this launch. Start one with Launch a script plan. |
| 409 | hold_refused | This host holds no running action, so pause is refused. Send cancel to stop the step instead. |
| 409 | terminal | The plan is completed, aborted or failed, so it takes no more controls. Check the plan's status with Retrieve the script panel before sending controls. |
| 409 | key_reused | The key was already used for a different call. Send a new key for each distinct control. |
| 409 | role | The script reserves this control to another role. Leave this control to the role the script names. |
| 409 | plan_held_elsewhere | Another host runs the plan. Send the same call again. |
| 409 | plan_gone | 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. |
Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role, 403 read_only_token and 429 when rate limited.
Web client proxima.launch.script.control(chainId, launchId, body) src/lib/proxima/endpoints/launch/script.ts
Write a script input
/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.
- Token
- Upgraded session token, bound to a license.
- Read-only tokens
- Refused with
403 read_only_token. - Retry
- Safe to retry Send the same
keyfor a value input or the sameidfor an event: a repeat answers the first call's record, or comes back withduplicate: 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_idenum RequiredChain of the launch.Possible valuessolethbscbaserobinhoodmonadarcxlayer -
launch_idstring RequiredPublic ID of the launch.Example101482937561204
Body parameters application/json
-
inputstring RequiredName of an input the script declares. -
idstring OptionalEvent input only, required: the arrival's ID, at most 128 bytes. The same ID is taken once. -
valuestring OptionalValue input, required: the new value. Event input: an optional payload for the arrival. -
keystring OptionalValue input only, required: idempotency key, at most 128 characters. -
expectinteger OptionalValue input only: optional, passed to the plan with the write. -
reasonstring OptionalValue input only: why, kept in the record.
Returns 200 OK · application/json
-
okbooleantruewhen the request succeeded. -
recordobjectThe control as recorded.Child attributes 5
-
seqintegerSequence number of the record. -
byobjectWho applied it. -
keystringIdempotency key of the call. -
verbstringVerb applied. -
outcomestringOutcome, such asapplied.
-
-
approvedstringName of the approval granted, forapprove. -
inputstringEvent input: the input the arrival was sent to. -
idstringEvent input: ID of the arrival. -
countintegerEvent input: arrival count reported by the plan. -
duplicatebooleanEvent input:truewhen thisidwas already taken, so nothing new arrived.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | 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 | 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 | 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. |
| 404 | not_found | No launch with this ID exists. Check chain_id and launch_id. |
| 403 | forbidden | 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 | No script plan has started on this launch. Start one with Launch a script plan. |
| 400 | missing_field | input is empty. Send the name of an input listed by Retrieve the script panel. |
| 400 | unknown_input | input names an input the script does not declare. Use an input name listed by Retrieve the script panel. |
| 400 | invalid_value | The input is of a kind this endpoint does not write. Write only approval, value and event inputs. |
| 400 | invalid_value | A value input was sent with an id. Drop id and send a key. |
| 400 | missing_field | A value input was sent without value. Send the new value in value. |
| 400 | idempotency_key_required | 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 longer than 128 characters. Send a key of at most 128 characters. |
| 400 | invalid_value | An approval was sent with an id or a value. Send only input for an approval. |
| 403 | snipe_approval | The launch's owner tried to grant the approval that stands for the launch's snipe. Grant it with Snipe a scheduled launch. |
| 400 | invalid_value | An event input was sent with a key or expect. Drop key and expect and send an id. |
| 400 | missing_field | An event input was sent without an id, or with an empty one. Send a unique id for each arrival. |
| 400 | invalid_value | The event's id is longer than 128 bytes. Send an id of at most 128 bytes. |
| 403 | forbidden | 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. |
| 409 | terminal | The plan is completed, aborted or failed, so it takes no more inputs. Check the plan's status with Retrieve the script panel before writing inputs. |
| 409 | key_reused | 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 host runs the plan. Send the same call again. |
| 409 | plan_gone | 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 | The plan refused the event's arrival. The message is its reason. Check the input in Retrieve the script panel, then send the event again if it still applies. |
Also the common errors: 401 for a missing or expired session or a base token (license_required), 403 read_only_token and 429 when rate limited.
Web client proxima.launch.script.input(chainId, launchId, body) src/lib/proxima/endpoints/launch/script.ts