Skip to content
API Reference

Search is only available in production builds. Try building and previewing the site to test it out locally.

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.

Save a script plan

Admin JWT internal
POST /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_id string Required
    Public ID of the launch.
    Example101482937561204

Body parameters application/json

  • 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 ClassicCex
  • scheduled_mode boolean Optional
    Must be false: 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.

  • 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

StatusCodeWhen 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

Admin JWT internal
POST /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_id enum Required
    Chain of the launch.
    Possible values solethbscbaserobinhoodmonadarcxlayer
  • launch_id string Required
    Public ID of the launch.
    Example101482937561204

Body parameters application/json

  • script object Required
    Script to check.

Returns 200 OK · application/json

  • ok boolean
    true when the request succeeded.
  • errors array<object>
    Errors found.
    Child attributes 5
    • 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

StatusCodeWhen 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

POST /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_id string Required
    Public ID of the launch.
    Example101482937561204

Returns 200 OK · application/json

  • 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

StatusCodeWhen 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

Admin JWT internal
POST /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 its status with 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_id string Required
    Public ID of the launch.
    Example101482937561204

Returns 200 OK · text/event-stream

Streams Launch progress events, one data: line each.

Errors

StatusCodeWhen 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

Admin JWT internal
GET /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_id enum Required
    Chain of the launch.
    Possible values solethbscbaserobinhoodmonadarcxlayer
  • launch_id string Required
    Public ID of the launch.
    Example101482937561204

Returns 200 OK · application/json

  • 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.
    Child attributes 5
    • 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

StatusCodeWhen 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

Admin JWT internal
GET /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_id enum Required
    Chain of the launch.
    Possible values solethbscbaserobinhoodmonadarcxlayer
  • launch_id string Required
    Public ID of the launch.
    Example101482937561204

Query parameters

  • after integer Optional Default 0
    Return lines after this sequence number. Start at 0.
    Example0
  • limit integer Optional Default 100
    Lines per page, 1 to 500. The SDK sends 200.

Returns 200 OK · application/json

  • ok boolean
    true when the request succeeded.
  • plan_id string
    Plan ID.
  • status string
    Plan status.
  • lines array<object>
    Journal lines.
    Child attributes 4
    • 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

StatusCodeWhen 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

Admin JWT internal
POST /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_id enum Required
    Chain of the launch.
    Possible values solethbscbaserobinhoodmonadarcxlayer
  • launch_id string Required
    Public ID of the launch.
    Example101482937561204

Body parameters application/json

  • verb enum Required
    Control to apply.
    Possible values cancelpauseresumeskipset_inputapprove
  • group enum Optional
    Group the step belongs to. Defaults to steps.
    Possible values stepsfinally
  • 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 · application/json

  • ok boolean
    true when the request succeeded.
  • record object
    The control as recorded.
    Child attributes 5
    • 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

StatusCodeWhen 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

Bearer JWT internal
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.

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 solethbscbaserobinhoodmonadarcxlayer
  • launch_id string Required
    Public ID of the launch.
    Example101482937561204

Body parameters application/json

  • 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 · application/json

  • ok boolean
    true when the request succeeded.
  • record object
    The control as recorded.
    Child attributes 5
    • 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

StatusCodeWhen 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