Skip to content
API Reference

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

Known Behaviors

Quirks of the current API to plan for, such as plain-text errors, 200 answers that carry a failure and status codes that differ by chain.

This page lists behaviors of the current API that can surprise an integration. Each one is also stated in the reference entry of the endpoint concerned; this page gathers them so you can plan for them in one place.

They describe the API as it runs today, not a contract. Most are rough edges that may be smoothed out later, so write code that tolerates both the current behavior and the documented intent.

Errors that are not JSON

The error object covers every error raised by an endpoint. A few errors are raised before the endpoint runs, by the HTTP framework, and come back as plain text with no code:

SituationStatusBody
The JSON body is malformed or misses a required field400Text, for example Json deserialize error: missing field `launch_id` at line 1 column 2
A POST that expects JSON is sent without a body or without Content-Type: application/json400Content type error
A query parameter has the wrong type400Text starting with Query deserialize error:
A path parameter cannot be parsed, for example a funding job ID that is not a UUID404Text
The route does not exist, or the method is not served on it404Empty
The body is larger than the endpoint accepts413Text

To handle them:

  • Read the Content-Type of every error response before parsing it. When it is not application/json, fall back to the HTTP status and keep the text for your logs.
  • Send Content-Type: application/json and a JSON body on every POST that takes JSON, even when every field is optional. Send {} rather than no body: for example, Deploy a Shield refuses an empty request.

Successful status, failed outcome

Some operations act on several wallets or chains and answer 200 even when part or all of the work failed. On these, a 200 only means the request was processed. Read ok and the per-item results before you report success.

EndpointWhat a 200 can hide
Buy back the tokenOn Solana, ok is false when every buy failed.
Nuke a launchOn EVM chains, ok stays true when every sale failed. Read failed.
Sell dividendsSome sales can fail while the call succeeds.
Resume a Streamflow airdropok is false when any claim failed.
Rescue MEV contractsA contract whose transfer failed is skipped; the call still answers ok: true.
Collect referral feesEach chain has its own result under results; ok is true only when every chain succeeded.
Swap funding to the quote tokenOn EVM chains, ok is false and message reads Swapped <n> of <m> wallets when some swaps failed. Read swapped and failed.
Claim staking rewardsEach claim has its own result in results; the call fails only when every claim failed.

Two calls can also stop halfway with an error after part of the work landed:

  • Swap funding to the quote token on Solana fails as a whole when one wallet fails, after other wallets may already have swapped.
  • Reclaim LP on Solana sends up to three transactions in a row; a 422 can follow a partial withdrawal.

Read balances again before you retry either of them.

Late confirmation

On Solana, the sell, nuke and transfer endpoints can confirm a request that had already been sent, instead of running it again. They answer 200 with this body:

{
"ok": true,
"landed": true,
"request_id": "b7c1e0a4-6f0e-4a4e-9d6e-2a3f0c9b1d55",
"tx_hashes": ["5h3xQ…"],
"message": "landed, its records follow: do not send it again"
}

The transactions landed; the balances and activity events that record them follow shortly. Treat it as a success and do not send the request again.

Refusals sent as 500

Several checks on Solana launches and wallets answer 500 internal_error with a meaningful message, where a 4xx would be expected. They are deterministic: retrying gives the same answer.

messageRaised by
Token already launchedPlan, funder and script changes after the launch
Token not launchedTrading and fee endpoints before the launch
No launch method savedLaunching without a saved plan
Funding already runningFunding the launch wallets twice
Funder not found, Cannot remove the last funderFunder endpoints on Solana
Wallet not foundUpdating a wallet
Funding delay out of boundsFunding drafts

The reference lists every one of them with its exact message. Before retrying a 500, read message: if it matches a documented refusal, fix the request instead.

Status codes that differ by chain

Solana and EVM chains are served by different code paths, and the same condition can come back with a different status:

ConditionSolanaEVM chains
The launch has already happened500400
The launch has not happened yet500400 or 404
The launch has no saved plan404 or 500400
The amount is above the dev wallet’s balance422400
The funder does not exist500404
Discarding a funding job that is running409400

The messages can differ too, for example Subs funding not completed on Solana and Holder funding not completed on EVM chains. Branch on the status class and code, and use the reference entry of each endpoint for the exact pairs.

Repeats that are not refused

Most money operations refuse a repeat while the first is running (lane_pending or a 409). A few do not. Each one is marked Check before retrying in its Requirements box:

Stopping automations

Auto Buy, Auto Sell, Volume Bot and Sniper Guard sessions behave differently on Solana and EVM chains when you stop them:

CallSolanaEVM chains
Discard a session that is running409: cancel it first200, and the session keeps running
Cancel, pause or resume with an unknown layer_id or mode400200, nothing changes

To stop a session on any chain, cancel it, read its status until it is no longer running, then discard it.

On EVM chains, Start an Auto Sell session and its Auto Buy and Volume Bot equivalents save the session as planned before the engine accepts it. When the engine refuses, the planned session stays behind; discard it before you plan again. When a planned session already exists, its saved parameters win over the request body.

Fields the API ignores

These request fields are accepted without error but have no effect:

EndpointIgnored fields
Create a launchhost, tracker, zaio, launch_platform
Trading endpoints (buyback, sell, nuke…)fake_tip, fake_tip_pct, terminal, routing
Create a funding draft on EVM chainsA funder_pubkey that is not a 0x address: the default funder is used instead
Run an activity planbudgets on any EVM chain other than the first one in chains: each EVM wallet only takes the budget of that first chain
Plan an Auto Sell session and its Auto Buy equivalentThe session-level min_mcap and max_mcap. Set market-cap bounds on each layer instead.

Unusual response shapes

EndpointShape
Delete walletsOn Solana, when no wallet matches, a bare JSON string: "No matching wallets found".
Remove watch wallets{ "removed": 2 }, with no ok field.
Retrieve the license, Retrieve the ShieldA 404 can also mean the read failed. Retry once before treating the resource as missing.
Wallet PnL fieldsOn Solana, pnl_native, pnl_usd and pnl_usd_total read 0 for a loss. On EVM chains, pnl_native keeps its sign and pnl_usd always reads 0.

Amounts follow the conventions, with one gap: some totals are JSON numbers on Solana and strings on EVM chains. Parse both.

Chains

  • Monad is no longer served. Chain-scoped routes answer 400 with unknown chain_id: monad. The value can still appear in older records and in some enums.
  • Quote tokens are only served for Solana: List quote tokens with any other chain_id answers an empty 404.
  • Lesgo launches are being withdrawn. Recent API builds no longer serve Prepare a Lesgo config and the other /launch/sol/lesgo/* routes.
  • The activity history chain filter accepts sol, bsc, eth, base, robinhood and xlayer. Any other value answers 400.

Access

  • The X tracker (/tracker/*) and the unscoped datafeed tokens are admin-only for now. Other accounts get 403 forbidden.
  • On a launch shared with you, every action other than a read needs two-factor authentication enabled on your own account. Without it, the API answers 403 with “acting on a shared launch needs two-factor authentication on your own account”.
  • Actions on shared launches can be challenged with the launch.delegated label. It does not appear in the list of protected actions and cannot be turned off. Answer it like any other challenge.

Sessions

Revoking a session takes effect at once on the server that handles the call. Other servers can keep accepting the session’s tokens for up to 30 seconds. Do not rely on a revoked token being refused immediately.

Endpoints documented from the web client

The web client calls these endpoints, but they are not in the API source this reference was checked against. Their reference entries are written from the web client alone: the requests are what it sends and the responses are what it reads, and their errors are not documented.

EndpointNote
Create a realtime connection tokenGET /auth/ws-token
Cashback and Collect cashbackGET /license/cashback, /license/cashback-history, /license/cashback-series and POST /license/collect-cashback
List quotesGET /marketplace/quotes currently answers an empty 404.