- API Reference
- Getting Started
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:
| Situation | Status | Body |
|---|---|---|
| The JSON body is malformed or misses a required field | 400 | Text, 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/json | 400 | Content type error |
| A query parameter has the wrong type | 400 | Text starting with Query deserialize error: |
| A path parameter cannot be parsed, for example a funding job ID that is not a UUID | 404 | Text |
| The route does not exist, or the method is not served on it | 404 | Empty |
| The body is larger than the endpoint accepts | 413 | Text |
To handle them:
- Read the
Content-Typeof every error response before parsing it. When it is notapplication/json, fall back to the HTTP status and keep the text for your logs. - Send
Content-Type: application/jsonand a JSON body on everyPOSTthat 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.
| Endpoint | What a 200 can hide |
|---|---|
| Buy back the token | On Solana, ok is false when every buy failed. |
| Nuke a launch | On EVM chains, ok stays true when every sale failed. Read failed. |
| Sell dividends | Some sales can fail while the call succeeds. |
| Resume a Streamflow airdrop | ok is false when any claim failed. |
| Rescue MEV contracts | A contract whose transfer failed is skipped; the call still answers ok: true. |
| Collect referral fees | Each chain has its own result under results; ok is true only when every chain succeeded. |
| Swap funding to the quote token | On EVM chains, ok is false and message reads Swapped <n> of <m> wallets when some swaps failed. Read swapped and failed. |
| Claim staking rewards | Each 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
422can 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.
message | Raised by |
|---|---|
Token already launched | Plan, funder and script changes after the launch |
Token not launched | Trading and fee endpoints before the launch |
No launch method saved | Launching without a saved plan |
Funding already running | Funding the launch wallets twice |
Funder not found, Cannot remove the last funder | Funder endpoints on Solana |
Wallet not found | Updating a wallet |
Funding delay out of bounds | Funding 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:
| Condition | Solana | EVM chains |
|---|---|---|
| The launch has already happened | 500 | 400 |
| The launch has not happened yet | 500 | 400 or 404 |
| The launch has no saved plan | 404 or 500 | 400 |
| The amount is above the dev wallet’s balance | 422 | 400 |
| The funder does not exist | 500 | 404 |
| Discarding a funding job that is running | 409 | 400 |
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:
- Fund the launch wallets on EVM chains: a repeat can fund the wallets twice.
- Nuke a launch on EVM chains: a repeat runs alongside the first one.
- Start a session on EVM chains: a repeat starts a second session.
- Buy back the token: every call buys again.
- Create a funding draft on Solana: with
funder_pubkeyset to"none"or"fresh", every call creates a new funder. - Update the launch plan: a wallet slot without a
keygets a new wallet on every call.
Stopping automations
Auto Buy, Auto Sell, Volume Bot and Sniper Guard sessions behave differently on Solana and EVM chains when you stop them:
| Call | Solana | EVM chains |
|---|---|---|
| Discard a session that is running | 409: cancel it first | 200, and the session keeps running |
Cancel, pause or resume with an unknown layer_id or mode | 400 | 200, 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:
| Endpoint | Ignored fields |
|---|---|
| Create a launch | host, tracker, zaio, launch_platform |
| Trading endpoints (buyback, sell, nuke…) | fake_tip, fake_tip_pct, terminal, routing |
| Create a funding draft on EVM chains | A funder_pubkey that is not a 0x address: the default funder is used instead |
| Run an activity plan | budgets 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 equivalent | The session-level min_mcap and max_mcap. Set market-cap bounds on each layer instead. |
Unusual response shapes
| Endpoint | Shape |
|---|---|
| Delete wallets | On 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 Shield | A 404 can also mean the read failed. Retry once before treating the resource as missing. |
| Wallet PnL fields | On 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
400withunknown 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_idanswers an empty404. - 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
chainfilter acceptssol,bsc,eth,base,robinhoodandxlayer. Any other value answers400.
Access
- The X tracker (
/tracker/*) and the unscoped datafeed tokens are admin-only for now. Other accounts get403 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
403with “acting on a shared launch needs two-factor authentication on your own account”. - Actions on shared launches can be challenged with the
launch.delegatedlabel. 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.
| Endpoint | Note |
|---|---|
| Create a realtime connection token | GET /auth/ws-token |
| Cashback and Collect cashback | GET /license/cashback, /license/cashback-history, /license/cashback-series and POST /license/collect-cashback |
| List quotes | GET /marketplace/quotes currently answers an empty 404. |