# API reference

The baselaunch public API is a free, keyless HTTP and WebSocket interface to the coins launched on baselaunch on Base: reads of coins, trades, holders and claimable credits, quotes, unsigned transactions to launch, buy, sell and claim, and a live feed. This page lists every operation with its parameters, request body, response fields and errors.

The base URL is `https://api.baselaunch.app/v1`. There is no API key. The machine-readable description of everything on this page is the OpenAPI document at `https://api.baselaunch.app/v1/openapi.json`, and this page is generated from it. For a guided start with code to copy, read [the Public API section of the docs](https://baselaunch.app/docs#public-api).

## Conventions

Free, keyless access to coins launched on baselaunch (Base, chainId 8453): the newest launches, one coin with its bonding-curve progress and market data, its trades and holders, and platform stats, plus unsigned transaction builders and quotes for launching, buying and selling. Reads are served from the indexer's database, not from a node, so they trail the chain by a few seconds. Only public on-chain data is exposed.

**Conventions.** Every amount of a token or of the quote asset is a decimal string in raw units (wei for 18-decimal tokens), never a JSON number, so it survives JavaScript. Addresses in responses are lowercase; addresses in requests are accepted in any case. Prices, market caps and percentages are plain JSON numbers (price is quote asset per whole token). Timestamps are unix seconds. Coin and trade lists are newest first and paged with the opaque `next` value of the previous page, passed back as `before`. A page can be empty: `next` is non-null whenever a page is full, so stop when `next` is null, not when a page is short. The holders list is ranked by balance and not paged. `limit` defaults to 50 and is clamped to 100; an invalid `limit` is replaced by the default rather than rejected.

**Rate limits.** Reads are limited to 120 requests per minute per client IP, and the builders and quotes (`/prepare/*` and `/quote`) to 30 requests per minute per client IP, counted separately. Beyond that the API answers 429 with `{"error":"rate_limited"}`; wait for the minute to roll over. CORS is open (`access-control-allow-origin: *`), so browsers can call it directly. Reads accept GET and HEAD, `/prepare/*` accepts POST with a JSON body of at most 32 KB, `/quote` accepts GET, and OPTIONS is answered everywhere (405 otherwise).

**Builders.** They never hold keys or funds and never send anything: each returns an unsigned `tx` (`to`, `data`, `value` in wei, `chainId`) for the caller's wallet to sign. When the input token needs an allowance first, `approval` is the `tx` to send before it (skip it when the wallet already has that allowance), and a graduated coin additionally returns `permit2`, the Permit2 step the router needs. Curve quotes are computed from the reserves the indexer last stored (`quote.asOf`, unix seconds, says how fresh they are) and `minAmountOut` is the slippage floor of the call (`slippageBps` defaults to 100). A graduated coin is priced with the Uniswap V4 quoter, cached for 2 seconds and limited globally, so a quote can answer 503 when that capacity is used; retry shortly. `launchFee` and `expectedEconomics` of a launch are read from the launch factory by the caller. Pass any address as `referrer` (and, on a launch, as `interface`): a trade on a coin launched on launcher 2.1.0 pays the referrer a share of the fee and `referrerPaid` is true, then `fallback` is the same action without the referrer, to send if the first one reverts. A coin launched on launcher 2.0 cannot pay a referrer: its call carries none and `referrerPaid` is false. A launch with no opening buy ignores the referrer.

**Fees and referrers.** A coin carries the `interface` and `launchReferrer` that were set at launch, and each trade carries the `referrer` and `referrerAmount` it paid out. Referral and interface fees accrue as ETH credits that the recipient claims on chain. Integrator warning: a contract used as a referrer or interface recipient must implement `receive()`. A contract without `receive()` cannot accept ETH, so it can never claim its credits.

**Launch tax.** A coin carries a decaying early-buy tax for a short window after launch: a buy of a coin on its curve returns `launchTax` with `bps` (the tax in basis points a wallet not exempted at launch pays if the buy lands now; the creator, its fee recipient and declared bundle wallets are exempt) and `endsAt` (unix second the window closes, `bps` is 0 from then on). It is computed from the indexed launch time with the contract's own decay and cap, so a caller can warn the buyer or wait instead of being refused.

**Claims.** Referral, interface and creator credits sit in the fee escrow of the launcher set that earned them (`set` v20 or v21; the two escrows are separate). `GET /wallets/{address}/claimable` lists, per escrow and asset, what the wallet can claim (ETH is the zero address; assets are never merged), and `POST /prepare/claim` returns one unsigned claim per escrow and asset. The escrow pays whoever sends the claim, so only the `claimant` wallet itself can claim: sign and send from that wallet. Amounts are the indexed balance and can trail the chain by a few seconds; the claim always pays the full on-chain balance. A contract that cannot receive ETH (no `receive()`) can never claim its ETH credits.

## Launched coins, their trades and holders

### Newest coins first

GET`/v1/coins/new`

Lists launched coins by launch time, newest first. Pass the returned `next` as `before` to get the following page.

#### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `limit` query | `integer` | Page size. Default 50, at most 100; an invalid value falls back to the default. (1 to 100, default 50) |
| `before` query | `string` | The `next` value of the previous page. |

#### Response 200

A page of coins.

| Field | Type | Description |
| --- | --- | --- |
| `chainId` required | `8453` |  |
| `coins` required | `object[]` |  |
| `coins[].chainId` required | `8453` |  |
| `coins[].address` required | `address` | Lowercase 20-byte hex address. |
| `coins[].name` required | `string` |  |
| `coins[].ticker` required | `string` |  |
| `coins[].logo` required | `stringnull` | Image URI (https or ipfs), null when none. |
| `coins[].description` required | `string` |  |
| `coins[].socials` required | `object` | Link per network, for example x, telegram, website. |
| `coins[].set` required | `"v20" \| "v21"` | The launcher contract generation that created the coin. |
| `coins[].phase` required | `"curve" \| "graduating" \| "graduated"` | curve: trading on the bonding curve. graduating: swept off the curve, pool not open yet. graduated: trading on the pool. |
| `coins[].curve` required | `address` | Lowercase 20-byte hex address. |
| `coins[].creator` required | `address` | Lowercase 20-byte hex address. |
| `coins[].feeRecipient` required | `address` | Receives the creator's share of trading fees; equals creator unless changed. |
| `coins[].creatorFeeBps` required | `integer` | Creator fee in basis points. |
| `coins[].interface` required | `address or null` | Interface recipient set at launch, null when none. Must implement receive() if it is a contract. |
| `coins[].launchReferrer` required | `address or null` | Referrer of the launch, null when none. Must implement receive() if it is a contract. |
| `coins[].pair` required | `object` | The quote asset the coin trades against. |
| `coins[].pair.quote` required | `address` | Lowercase 20-byte hex address. |
| `coins[].pair.symbol` required | `string` |  |
| `coins[].pair.decimals` required | `integer` |  |
| `coins[].launchedAt` required | `integer` | Unix seconds. |
| `coins[].launchBlock` required | `integer` |  |
| `coins[].poolId` required | `stringnull` | Pool id, only once graduated. |
| `coins[].graduation` required | `object` |  |
| `coins[].graduation.threshold` required | `amount` | Quote reserve, in raw quote units, at which the coin graduates. |
| `coins[].graduation.reserve` required | `amount or null` | Current quote reserve in raw quote units; null once off the curve or before the first refresh. |
| `coins[].graduation.progress` required | `number` | 0 to 1; 1 once the coin left the curve. (0 to 1) |
| `coins[].market` required | `object` | Market data. Quote figures are in whole quote-asset units as JSON numbers; USD figures are null until a USD price is known. |
| `coins[].market.price` required | `number` | Quote asset per whole token. |
| `coins[].market.marketCapQuote` required | `number` |  |
| `coins[].market.volume24hQuote` required | `number` |  |
| `coins[].market.marketCapUsd` required | `numbernull` |  |
| `coins[].market.volume24hUsd` required | `numbernull` |  |
| `coins[].market.change24h` required | `number` | Price change over 24 hours as a fraction (0.1 is +10%). |
| `next` required | `stringnull` | Pass as `before` for the next page; null on the last page. |

GET /v1/coins/new responsejson

```
{
  "chainId": 8453,
  "coins": [
    {
      "chainId": 8453,
      "address": "0x1111111111111111111111111111111111111111",
      "name": "Example Coin",
      "ticker": "EXC",
      "logo": "ipfs://bafyexample",
      "description": "An example coin.",
      "socials": {
        "x": "https://x.com/example"
      },
      "set": "v21",
      "phase": "curve",
      "curve": "0xc111111111111111111111111111111111111111",
      "creator": "0x9999999999999999999999999999999999999999",
      "feeRecipient": "0x9999999999999999999999999999999999999999",
      "creatorFeeBps": 100,
      "interface": null,
      "launchReferrer": null,
      "pair": {
        "quote": "0x0000000000000000000000000000000000000000",
        "symbol": "ETH",
        "decimals": 18
      },
      "launchedAt": 1760000000,
      "launchBlock": 38000000,
      "poolId": null,
      "graduation": {
        "threshold": "1000000000000000000",
        "reserve": "250000000000000000",
        "progress": 0.25
      },
      "market": {
        "price": 5e-7,
        "marketCapQuote": 500,
        "volume24hQuote": 3,
        "marketCapUsd": null,
        "volume24hUsd": null,
        "change24h": 0.1
      }
    }
  ],
  "next": "1760000000:0x1111111111111111111111111111111111111111"
}
```

#### Errors

`400 bad_cursor``429 rate_limited`

### One coin

GET`/v1/coins/{address}`

The coin with its holder and trade counts. Holders exclude protocol contracts (the coin's curve, the pool manager and the launcher contracts).

#### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `address` path, required | `string` | The coin's token address, any case. |

#### Response 200

The coin.

| Field | Type | Description |
| --- | --- | --- |
| `chainId` required | `8453` |  |
| `address` required | `address` | Lowercase 20-byte hex address. |
| `name` required | `string` |  |
| `ticker` required | `string` |  |
| `logo` required | `stringnull` | Image URI (https or ipfs), null when none. |
| `description` required | `string` |  |
| `socials` required | `object` | Link per network, for example x, telegram, website. |
| `set` required | `"v20" \| "v21"` | The launcher contract generation that created the coin. |
| `phase` required | `"curve" \| "graduating" \| "graduated"` | curve: trading on the bonding curve. graduating: swept off the curve, pool not open yet. graduated: trading on the pool. |
| `curve` required | `address` | Lowercase 20-byte hex address. |
| `creator` required | `address` | Lowercase 20-byte hex address. |
| `feeRecipient` required | `address` | Receives the creator's share of trading fees; equals creator unless changed. |
| `creatorFeeBps` required | `integer` | Creator fee in basis points. |
| `interface` required | `address or null` | Interface recipient set at launch, null when none. Must implement receive() if it is a contract. |
| `launchReferrer` required | `address or null` | Referrer of the launch, null when none. Must implement receive() if it is a contract. |
| `pair` required | `object` | The quote asset the coin trades against. |
| `pair.quote` required | `address` | Lowercase 20-byte hex address. |
| `pair.symbol` required | `string` |  |
| `pair.decimals` required | `integer` |  |
| `launchedAt` required | `integer` | Unix seconds. |
| `launchBlock` required | `integer` |  |
| `poolId` required | `stringnull` | Pool id, only once graduated. |
| `graduation` required | `object` |  |
| `graduation.threshold` required | `amount` | Quote reserve, in raw quote units, at which the coin graduates. |
| `graduation.reserve` required | `amount or null` | Current quote reserve in raw quote units; null once off the curve or before the first refresh. |
| `graduation.progress` required | `number` | 0 to 1; 1 once the coin left the curve. (0 to 1) |
| `market` required | `object` | Market data. Quote figures are in whole quote-asset units as JSON numbers; USD figures are null until a USD price is known. |
| `market.price` required | `number` | Quote asset per whole token. |
| `market.marketCapQuote` required | `number` |  |
| `market.volume24hQuote` required | `number` |  |
| `market.marketCapUsd` required | `numbernull` |  |
| `market.volume24hUsd` required | `numbernull` |  |
| `market.change24h` required | `number` | Price change over 24 hours as a fraction (0.1 is +10%). |
| `counts` required | `object` |  |
| `counts.holders` required | `integer` |  |
| `counts.trades` required | `integer` |  |

GET /v1/coins/{address} responsejson

```
{
  "chainId": 8453,
  "address": "0x1111111111111111111111111111111111111111",
  "name": "Example Coin",
  "ticker": "EXC",
  "logo": "ipfs://bafyexample",
  "description": "An example coin.",
  "socials": {
    "x": "https://x.com/example"
  },
  "set": "v21",
  "phase": "graduated",
  "curve": "0xc111111111111111111111111111111111111111",
  "creator": "0x9999999999999999999999999999999999999999",
  "feeRecipient": "0x9999999999999999999999999999999999999999",
  "creatorFeeBps": 100,
  "interface": "0xdddddddddddddddddddddddddddddddddddddddd",
  "launchReferrer": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
  "pair": {
    "quote": "0x0000000000000000000000000000000000000000",
    "symbol": "ETH",
    "decimals": 18
  },
  "launchedAt": 1760000000,
  "launchBlock": 38000000,
  "poolId": "0x00000000000000000000000000000000000000000000000000000000000000aa",
  "graduation": {
    "threshold": "1000000000000000000",
    "reserve": null,
    "progress": 1
  },
  "market": {
    "price": 5e-7,
    "marketCapQuote": 500,
    "volume24hQuote": 3,
    "marketCapUsd": 1500000,
    "volume24hUsd": 9000,
    "change24h": 0.1
  },
  "counts": {
    "holders": 42,
    "trades": 310
  }
}
```

#### Errors

`400 bad_address``404 not_found``429 rate_limited`

### Trades of a coin, newest first

GET`/v1/coins/{address}/trades`

Buys and sells on the curve and, after graduation, on the pool. Pass the returned `next` as `before` for the following page.

#### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `address` path, required | `string` | The coin's token address, any case. |
| `limit` query | `integer` | Page size. Default 50, at most 100; an invalid value falls back to the default. (1 to 100, default 50) |
| `before` query | `string` | The `next` value of the previous page. |

#### Response 200

A page of trades.

| Field | Type | Description |
| --- | --- | --- |
| `chainId` required | `8453` |  |
| `trades` required | `object[]` |  |
| `trades[].tx` required | `string` |  |
| `trades[].logIndex` required | `integer` |  |
| `trades[].side` required | `"buy" \| "sell"` |  |
| `trades[].venue` required | `"curve" \| "pool"` | Where it executed. curve: the bonding curve. pool: the Uniswap v4 pool after graduation. |
| `trades[].quoteAmount` required | `amount` | Quote asset moved, raw quote units. |
| `trades[].tokenAmount` required | `amount` | Coin moved, wei. |
| `trades[].price` required | `number` | Quote asset per whole token. |
| `trades[].wallet` required | `address` | Lowercase 20-byte hex address. |
| `trades[].block` required | `integer` |  |
| `trades[].timestamp` required | `integer` | Unix seconds. |
| `trades[].referrer` required | `address or null` |  |
| `trades[].referrerAmount` required | `amount or null` | Referrer credit from this trade, raw units. |
| `next` required | `stringnull` |  |

GET /v1/coins/{address}/trades responsejson

```
{
  "chainId": 8453,
  "trades": [
    {
      "tx": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "logIndex": 3,
      "side": "buy",
      "venue": "curve",
      "quoteAmount": "100000000000000000",
      "tokenAmount": "200000000000000000000000",
      "price": 5e-7,
      "wallet": "0x9999999999999999999999999999999999999999",
      "block": 38000100,
      "timestamp": 1760000200,
      "referrer": "0xdddddddddddddddddddddddddddddddddddddddd",
      "referrerAmount": "400000000000000"
    }
  ],
  "next": "1760000200:38000100:3"
}
```

#### Errors

`400 bad_address``400 bad_cursor``404 not_found``429 rate_limited`

### Top holders of a coin

GET`/v1/coins/{address}/holders`

Wallets with a positive balance, largest first. Protocol contracts are excluded. This list is not paged: `limit` caps it at 100.

#### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `address` path, required | `string` | The coin's token address, any case. |
| `limit` query | `integer` | Page size. Default 50, at most 100; an invalid value falls back to the default. (1 to 100, default 50) |

#### Response 200

Ranked holders.

| Field | Type | Description |
| --- | --- | --- |
| `chainId` required | `8453` |  |
| `holders` required | `object[]` |  |
| `holders[].rank` required | `integer` |  |
| `holders[].wallet` required | `address` | Lowercase 20-byte hex address. |
| `holders[].balance` required | `amount` | Non-negative decimal string in raw units. |

GET /v1/coins/{address}/holders responsejson

```
{
  "chainId": 8453,
  "holders": [
    {
      "rank": 1,
      "wallet": "0xabababababababababababababababababababab",
      "balance": "900000000000000000000"
    },
    {
      "rank": 2,
      "wallet": "0xcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd",
      "balance": "50000000000000000000"
    }
  ]
}
```

#### Errors

`400 bad_address``404 not_found``429 rate_limited`

### Price candles of a coin

GET`/v1/coins/{address}/candles`

OHLC candles of the coin from the stored trades, oldest first, at most 1000 (the newest ones when the range holds more). Prices are quote asset per whole token and `v` is the quote volume in whole quote units. An interval without trades has no candle. `from` and `to` are inclusive unix seconds on the candle start time.

#### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `address` path, required | `string` | The coin's token address, any case. |
| `interval` query, required | `"1m" \| "5m" \| "1h" \| "1d"` | Candle size. |
| `from` query | `integer` | First candle start time to include, unix seconds. |
| `to` query | `integer` | Last candle start time to include, unix seconds; not before `from`. |

#### Response 200

The candles.

| Field | Type | Description |
| --- | --- | --- |
| `chainId` required | `8453` |  |
| `interval` required | `"1m" \| "5m" \| "1h" \| "1d"` |  |
| `candles` required | `object[]` |  |
| `candles[].t` required | `integer` | Candle start, unix seconds. |
| `candles[].o` required | `number` | Open price, quote asset per whole token. |
| `candles[].h` required | `number` |  |
| `candles[].l` required | `number` |  |
| `candles[].c` required | `number` | Close price. |
| `candles[].v` required | `number` | Volume in whole quote units. |

GET /v1/coins/{address}/candles responsejson

```
{
  "chainId": 8453,
  "interval": "5m",
  "candles": [
    {
      "t": 1760000100,
      "o": 5e-7,
      "h": 6e-7,
      "l": 5e-7,
      "c": 6e-7,
      "v": 0.3
    },
    {
      "t": 1760000400,
      "o": 6e-7,
      "h": 6e-7,
      "l": 5.5e-7,
      "c": 5.5e-7,
      "v": 0.1
    }
  ]
}
```

#### Errors

`400 bad_address``400 bad_interval``400 bad_range``404 not_found``429 rate_limited`

## What a wallet can claim

### What a wallet can claim

GET`/v1/wallets/{address}/claimable`

The credits the wallet holds in each fee escrow, one row per escrow and asset, from the indexed escrow events: ETH (the zero address) first, then ERC-20 assets by address. Zero balances are left out and assets are never merged. The two launcher sets have separate escrows. Only the wallet itself can claim (the escrow pays the sender), and a contract without `receive()` can never claim its ETH credits.

#### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `address` path, required | `string` | The wallet address, any case. |

#### Response 200

The claimable balances.

| Field | Type | Description |
| --- | --- | --- |
| `chainId` required | `8453` |  |
| `wallet` required | `address` | Lowercase 20-byte hex address. |
| `claimable` required | `object[]` |  |
| `claimable[].set` required | `"v20" \| "v21"` | The launcher set whose escrow holds the credit. |
| `claimable[].escrow` required | `address` | Lowercase 20-byte hex address. |
| `claimable[].asset` required | `address` | The zero address for ETH, else the ERC-20. |
| `claimable[].amount` required | `amount` | Raw units of the asset. |

GET /v1/wallets/{address}/claimable responsejson

```
{
  "chainId": 8453,
  "wallet": "0x9999999999999999999999999999999999999999",
  "claimable": [
    {
      "set": "v20",
      "escrow": "0x3333333333333333333333333333333333333333",
      "asset": "0x0000000000000000000000000000000000000000",
      "amount": "505"
    },
    {
      "set": "v21",
      "escrow": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
      "asset": "0x0000000000000000000000000000000000000000",
      "amount": "70000000000000"
    },
    {
      "set": "v21",
      "escrow": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
      "asset": "0xcccccccccccccccccccccccccccccccccccccccc",
      "amount": "9000000"
    }
  ]
}
```

#### Errors

`400 bad_address``429 rate_limited`

### Unsigned claims of a wallet's credits

POST`/v1/prepare/claim`

One unsigned claim per escrow and asset the wallet is owed (the same rows as `/wallets/{address}/claimable`): `claim()` for ETH and `claimToken(asset)` for an ERC-20, sent to that row's escrow, each paying the full on-chain balance. The escrow pays whoever sends it, so `claimant` must be the wallet that signs and sends. `claims` is empty when nothing is owed. A contract without `receive()` can never claim its ETH credits.

#### Request body (JSON)

| Field | Type | Description |
| --- | --- | --- |
| `wallet` required | `string` | The wallet that holds the credits and will send the claims. Not the zero address. |

POST /v1/prepare/claim requestjson

```
{
  "wallet": "0x9999999999999999999999999999999999999999"
}
```

#### Response 200

The unsigned claims.

| Field | Type | Description |
| --- | --- | --- |
| `chainId` required | `8453` |  |
| `claimant` required | `address` | The wallet that must sign and send the claims: the escrow pays its caller. |
| `claims` required | `object[]` |  |
| `claims[].set` required | `"v20" \| "v21"` | The launcher set whose escrow holds the credit. |
| `claims[].escrow` required | `address` | Lowercase 20-byte hex address. |
| `claims[].asset` required | `address` | The zero address for ETH, else the ERC-20. |
| `claims[].amount` required | `amount` | Raw units of the asset. |
| `claims[].tx` required | `object` | An unsigned transaction for the caller's wallet to sign and send. |
| `claims[].tx.to` required | `address` | Lowercase 20-byte hex address. |
| `claims[].tx.data` required | `string` | Calldata, lowercase hex. |
| `claims[].tx.value` required | `amount` | Wei to send. |
| `claims[].tx.chainId` required | `8453` |  |
| `claims[].tx.gas` | `amount` | Gas limit to use, present only on a buy that fills the curve (so graduation runs inside the same transaction); otherwise let the wallet estimate. |

POST /v1/prepare/claim responsejson

```
{
  "chainId": 8453,
  "claimant": "0x9999999999999999999999999999999999999999",
  "claims": [
    {
      "set": "v21",
      "escrow": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
      "asset": "0x0000000000000000000000000000000000000000",
      "amount": "70000000000000",
      "tx": {
        "to": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
        "data": "0x4e71d92d",
        "value": "0",
        "chainId": 8453
      }
    }
  ]
}
```

#### Errors

`400 bad_wallet``400 bad_json``400 bad_params``413 too_large``429 rate_limited`

## Platform counters

### Platform counters

GET`/v1/stats`

Totals over all coins launched through baselaunch. `volume24hUsd` is a number, 0 when no volume has a USD price yet.

#### Response 200

Counters.

| Field | Type | Description |
| --- | --- | --- |
| `chainId` required | `8453` |  |
| `coins` required | `integer` |  |
| `onCurve` required | `integer` |  |
| `graduated` required | `integer` | Coins that left the curve (graduating or graduated). |
| `trades` required | `integer` |  |
| `coins24h` required | `integer` |  |
| `trades24h` required | `integer` |  |
| `volume24hUsd` required | `number` |  |

GET /v1/stats responsejson

```
{
  "chainId": 8453,
  "coins": 120,
  "onCurve": 95,
  "graduated": 25,
  "trades": 5400,
  "coins24h": 7,
  "trades24h": 310,
  "volume24hUsd": 18250.5
}
```

#### Errors

`429 rate_limited`

## Unsigned transactions and quotes

### Unsigned launch transaction

POST`/v1/prepare/launch`

Encodes the router launch of a new coin, with an optional opening buy. `interface` is registered as the coin's launch interface and earns a share of its fees; `referrer` is paid on the opening buy and ignored when `buyAmount` is 0. The factory's `launchFee` and the `expectedEconomics` hash are read on chain by the caller. `value` is the launch fee plus the opening buy for an ETH pair. Launching must be enabled on the factory for the transaction to succeed.

#### Request body (JSON)

| Field | Type | Description |
| --- | --- | --- |
| `name` required | `string` | 1 to 64 UTF-8 bytes. |
| `symbol` required | `string` | 1 to 16 UTF-8 bytes. |
| `logo` | `string` | At most 512 UTF-8 bytes. |
| `description` | `string` | At most 2048 UTF-8 bytes. |
| `socials` | `object` | Each link at most 256 UTF-8 bytes. |
| `socials.twitter` | `string` |  |
| `socials.telegram` | `string` |  |
| `socials.discord` | `string` |  |
| `socials.website` | `string` |  |
| `socials.farcaster` | `string` |  |
| `creatorFeeRecipient` | `string` | Required and non-zero, except in holders mode, where it must be omitted or the zero address (the router refuses anything else). |
| `creatorFeeBps` | `integer` | (0 to 10000, default 0) |
| `buybackEnabled` | `boolean` | (default false) |
| `expectedEconomics` required | `string` | The economics hash the factory's previewLaunchEconomics returns; the launch reverts if the config changed since. |
| `salt` | `string` | Optional 32-byte salt of the coin's address; random when omitted. |
| `pair` | `string` | The pair asset: the zero address or omitted for ETH. |
| `launchFee` required | `string` | The factory's launchFee in wei, read on chain by the caller. |
| `buyAmount` | `string` | Opening buy in the pair's raw units. Default 0. |
| `minTokensOut` | `string` | Slippage floor of the opening buy; required (above 0) when buyAmount is above 0. |
| `holders` | `boolean` | Holders mode: the creator's fee share goes to a holders distributor. Requires no creatorFeeRecipient (or the zero address) and buybackEnabled false. (default false) |
| `interface` | `string` | Optional launch interface that earns a share of the coin's fees. A contract must implement receive(). |
| `referrer` | `string` | Optional referrer of the opening buy; ignored when buyAmount is 0. |

POST /v1/prepare/launch requestjson

```
{
  "name": "Example Coin",
  "symbol": "EXC",
  "logo": "ipfs://bafyexample",
  "description": "An example coin.",
  "socials": {
    "twitter": "https://x.com/example"
  },
  "creatorFeeRecipient": "0x9999999999999999999999999999999999999999",
  "creatorFeeBps": 100,
  "expectedEconomics": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
  "salt": "0x5555555555555555555555555555555555555555555555555555555555555555",
  "launchFee": "2000000000000000",
  "buyAmount": "100000000000000000",
  "minTokensOut": "54000000000000000000000000",
  "interface": "0x7777777777777777777777777777777777777777",
  "referrer": "0x8888888888888888888888888888888888888888"
}
```

#### Response 200

The unsigned launch.

| Field | Type | Description |
| --- | --- | --- |
| `chainId` required | `8453` |  |
| `coin` required | `address or null` | The coin traded; null for a launch. |
| `side` required | `"buy" \| "sell" \| "launch"` |  |
| `launchTax` | `object` | Present on a buy of an existing coin: the early-buy tax if the transaction landed now, so the caller can warn instead of being refused. |
| `launchTax.bps` required | `integer` | Basis points taken from the spend, with the contract's decay and cap; 0 once the window is over, and always 0 on a graduated coin. (0 to 9900) |
| `launchTax.endsAt` required | `integer` | Unix second the window closes. Equals the launch time for a coin with no window. |
| `route` required | `"curve" \| "pool" \| "router"` | curve: the bonding curve. pool: the graduated pool through the Universal Router. router: the launch router. |
| `payee` | `address` | The address that receives the output of a trade: the recipient on the curve, the sender (equal to the recipient) on a graduated coin. Absent on a launch. |
| `referrerPaid` required | `boolean` | True when the referrer will be paid: a 2.1.0 coin (or a launch with an opening buy) and a referrer the contracts accept. False for a 2.0 coin, which takes no referrer. |
| `quote` required | `object or null` | Null for a launch. |
| `quote.amountIn` required | `amount` | Non-negative decimal string in raw units. |
| `quote.amountOut` required | `amount` | Coins received on a buy, pair asset received on a sell. |
| `quote.minAmountOut` required | `amount` | The slippage floor in the transaction. |
| `quote.source` required | `"indexed" \| "quoter"` | indexed: the curve reserves the indexer stored. quoter: the Uniswap V4 quoter. |
| `quote.asOf` required | `integer` | Unix seconds of the state the quote was computed from. |
| `quote.spent` | `amount` | Buy on the curve: the pair asset the curve keeps (less than amountIn when the buy fills the curve and the rest is refunded). |
| `quote.refund` | `amount` | Buy on the curve: the part of amountIn sent back. |
| `quote.fee` | `amount` | Curve trades: the base trade fee in pair units. |
| `quote.creatorFee` | `amount` | Curve trades: the creator fee in pair units. |
| `quote.snipeTax` | `amount` | Curve buy: the early-buy tax a wallet not exempted at launch pays right now, in pair units. |
| `quote.willGraduate` | `boolean` | Curve buy: true when this buy fills the curve and graduates the coin. |
| `tx` required | `object` | An unsigned transaction for the caller's wallet to sign and send. |
| `tx.to` required | `address` | Lowercase 20-byte hex address. |
| `tx.data` required | `string` | Calldata, lowercase hex. |
| `tx.value` required | `amount` | Wei to send. |
| `tx.chainId` required | `8453` |  |
| `tx.gas` | `amount` | Gas limit to use, present only on a buy that fills the curve (so graduation runs inside the same transaction); otherwise let the wallet estimate. |
| `approval` | `object` | An ERC-20 allowance to send before the main transaction; skip it when the wallet already has this allowance. Curve trades approve exactly the trade amount to the curve; a graduated coin approves Permit2 once for any amount, as the baselaunch site does, and the permit2 step then allows the router exactly the trade amount. |
| `approval.token` required | `address` | Lowercase 20-byte hex address. |
| `approval.spender` required | `address` | Lowercase 20-byte hex address. |
| `approval.amount` required | `amount` | Non-negative decimal string in raw units. |
| `approval.tx` required | `object` | An unsigned transaction for the caller's wallet to sign and send. |
| `approval.tx.to` required | `address` | Lowercase 20-byte hex address. |
| `approval.tx.data` required | `string` | Calldata, lowercase hex. |
| `approval.tx.value` required | `amount` | Wei to send. |
| `approval.tx.chainId` required | `8453` |  |
| `approval.tx.gas` | `amount` | Gas limit to use, present only on a buy that fills the curve (so graduation runs inside the same transaction); otherwise let the wallet estimate. |
| `permit2` | `object` | The Permit2 step a graduated coin's swap needs after the ERC-20 approval: Permit2 lets the router pull `amount` of `token` until `expiration`. |
| `permit2.token` required | `address` | Lowercase 20-byte hex address. |
| `permit2.spender` required | `address` | The Universal Router. |
| `permit2.amount` required | `amount` | Non-negative decimal string in raw units. |
| `permit2.expiration` required | `integer` | Unix seconds. |
| `permit2.tx` required | `object` | An unsigned transaction for the caller's wallet to sign and send. |
| `permit2.tx.to` required | `address` | Lowercase 20-byte hex address. |
| `permit2.tx.data` required | `string` | Calldata, lowercase hex. |
| `permit2.tx.value` required | `amount` | Wei to send. |
| `permit2.tx.chainId` required | `8453` |  |
| `permit2.tx.gas` | `amount` | Gas limit to use, present only on a buy that fills the curve (so graduation runs inside the same transaction); otherwise let the wallet estimate. |
| `fallback` | `object` | The same action without the referrer (present when referrerPaid is true). Send it if `tx` reverts, for example because an ERC-20 pair token turned fee-on-transfer or paused. |
| `fallback.to` required | `address` | Lowercase 20-byte hex address. |
| `fallback.data` required | `string` | Calldata, lowercase hex. |
| `fallback.value` required | `amount` | Wei to send. |
| `fallback.chainId` required | `8453` |  |
| `fallback.gas` | `amount` | Gas limit to use, present only on a buy that fills the curve (so graduation runs inside the same transaction); otherwise let the wallet estimate. |

POST /v1/prepare/launch responsejson

```
{
  "chainId": 8453,
  "coin": null,
  "side": "launch",
  "route": "router",
  "referrerPaid": true,
  "quote": null,
  "tx": {
    "to": "0x32e6c9c592c9082c6f6a205fc3b38fecdc1be5d5",
    "data": "0x393b008d00000000000000000000000000000000000000000000000000000000000001200000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004c0000000000000000000000000000000000000000000000000016345785d8a00000000000000000000000000000000000000000000002caaf1dd9f3a1ff60000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000777777777777777777777777777777777777777700000000000000000000000088888888888888888888888888888888888888880000000000000000000000000000000000000000000000000000000000000140000000000000000000000000000000000000000000000000000000000000018000000000000000000000000000000000000000000000000000000000000001c000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000240000000000000000000000000999999999999999999999999999999999999999900000000000000000000000000000000000000000000000000000000000000640000000000000000000000000000000000000000000000000000000000000000eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee5555555555555555555555555555555555555555555555555555555555555555000000000000000000000000000000000000000000000000000000000000000c4578616d706c6520436f696e0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000345584300000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000012697066733a2f2f626166796578616d706c6500000000000000000000000000000000000000000000000000000000000000000000000000000000000000000010416e206578616d706c6520636f696e2e0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000000e0000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000001200000000000000000000000000000000000000000000000000000000000000140000000000000000000000000000000000000000000000000000000000000001568747470733a2f2f782e636f6d2f6578616d706c65000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
    "value": "102000000000000000",
    "chainId": 8453
  }
}
```

#### Errors

`400 bad_json``400 bad_params``413 too_large``429 rate_limited``503 launch_unavailable`

### Unsigned buy transaction

POST`/v1/prepare/buy`

Buys `amountIn` of the pair asset (wei for ETH) worth of the coin. The coins go to `payee` (the response field): `recipient` on the curve; on a graduated coin the swap pays the wallet that sends the transaction, so `sender` is required there and must equal `recipient` (400 `sender_required` or `recipient_unsupported` otherwise). A coin on its curve is bought from the curve (`route` curve), a graduated coin through the Universal Router on its own pool (`route` pool). For an ERC-20 pair `value` is 0 and `approval` is the pair allowance to send first.

#### Request body (JSON)

| Field | Type | Description |
| --- | --- | --- |
| `coin` required | `string` | The coin's token address, any case. |
| `amountIn` required | `string` | Raw units, a positive decimal string: the pair asset for a buy, the coin for a sell. |
| `slippageBps` | `integer` | (0 to 9999, default 100) |
| `recipient` required | `string` | Receives the coins (buy) or the pair asset (sell) on a coin on its curve. Not the zero address. On a graduated coin the swap pays the wallet that sends the transaction, so the recipient must be that wallet; pass `sender` to have a different recipient refused. |
| `sender` | `string` | The wallet that will send the transaction. Required on a graduated coin (400 sender_required) and must equal recipient (400 recipient_unsupported); ignored on the curve. |
| `referrer` | `string` | Optional. Paid a share of the fee on a 2.1.0 coin. A contract referrer must implement receive() or it can never claim. |

POST /v1/prepare/buy requestjson

```
{
  "coin": "0x1111111111111111111111111111111111111111",
  "amountIn": "100000000000000000",
  "slippageBps": 100,
  "recipient": "0x9999999999999999999999999999999999999999",
  "referrer": "0x8888888888888888888888888888888888888888"
}
```

#### Response 200

The unsigned buy.

The same fields as [Unsigned launch transaction](#prepareLaunch).

POST /v1/prepare/buy responsejson

```
{
  "chainId": 8453,
  "coin": "0x1111111111111111111111111111111111111111",
  "side": "buy",
  "route": "curve",
  "payee": "0x9999999999999999999999999999999999999999",
  "referrerPaid": true,
  "quote": {
    "amountIn": "100000000000000000",
    "amountOut": "55118110236220472440944881",
    "minAmountOut": "54566929133858267716535432",
    "source": "indexed",
    "asOf": 1759999990,
    "spent": "100000000000000000",
    "refund": "0",
    "fee": "1000000000000000",
    "creatorFee": "1000000000000000",
    "snipeTax": "0",
    "willGraduate": false
  },
  "tx": {
    "to": "0xc111111111111111111111111111111111111111",
    "data": "0x82b2a559000000000000000000000000000000000000000000000000016345785d8a00000000000000000000000000000000000000000000002d22ff27d7feef3f22448800000000000000000000000099999999999999999999999999999999999999990000000000000000000000008888888888888888888888888888888888888888",
    "value": "100000000000000000",
    "chainId": 8453
  },
  "fallback": {
    "to": "0xc111111111111111111111111111111111111111",
    "data": "0x59a87bc1000000000000000000000000000000000000000000000000016345785d8a00000000000000000000000000000000000000000000002d22ff27d7feef3f2244880000000000000000000000009999999999999999999999999999999999999999",
    "value": "100000000000000000",
    "chainId": 8453
  }
}
```

#### Errors

`400 bad_address``400 bad_amount``400 bad_slippage``400 bad_recipient``400 bad_sender``400 sender_required``400 recipient_unsupported``400 bad_referrer``400 bad_json``400 bad_params``404 not_found``409 not_tradable``413 too_large``422 quote_failed``429 rate_limited``503 state_unavailable``503 quote_unavailable``503 pool_unavailable`

### Unsigned sell transaction

POST`/v1/prepare/sell`

Sells `amountIn` of the coin (raw token units) for the pair asset. The pair asset goes to `payee` (the response field): `recipient` on the curve; on a graduated coin the swap pays the wallet that sends the transaction, so `sender` is required there and must equal `recipient` (400 `sender_required` or `recipient_unsupported` otherwise). `approval` is the coin allowance to send first (to the curve, or to Permit2 for a graduated coin).

#### Request body (JSON)

| Field | Type | Description |
| --- | --- | --- |
| `coin` required | `string` | The coin's token address, any case. |
| `amountIn` required | `string` | Raw units, a positive decimal string: the pair asset for a buy, the coin for a sell. |
| `slippageBps` | `integer` | (0 to 9999, default 100) |
| `recipient` required | `string` | Receives the coins (buy) or the pair asset (sell) on a coin on its curve. Not the zero address. On a graduated coin the swap pays the wallet that sends the transaction, so the recipient must be that wallet; pass `sender` to have a different recipient refused. |
| `sender` | `string` | The wallet that will send the transaction. Required on a graduated coin (400 sender_required) and must equal recipient (400 recipient_unsupported); ignored on the curve. |
| `referrer` | `string` | Optional. Paid a share of the fee on a 2.1.0 coin. A contract referrer must implement receive() or it can never claim. |

POST /v1/prepare/sell requestjson

```
{
  "coin": "0x1111111111111111111111111111111111111111",
  "amountIn": "27824620573355817875210792",
  "slippageBps": 100,
  "recipient": "0x9999999999999999999999999999999999999999",
  "referrer": "0x8888888888888888888888888888888888888888"
}
```

#### Response 200

The unsigned sell.

The same fields as [Unsigned launch transaction](#prepareLaunch).

POST /v1/prepare/sell responsejson

```
{
  "chainId": 8453,
  "coin": "0x1111111111111111111111111111111111111111",
  "side": "sell",
  "route": "curve",
  "payee": "0x9999999999999999999999999999999999999999",
  "referrerPaid": true,
  "quote": {
    "amountIn": "27824620573355817875210792",
    "amountOut": "49898404163052905",
    "minAmountOut": "49399420121422375",
    "source": "indexed",
    "asOf": 1759999990,
    "fee": "509167389418907",
    "creatorFee": "509167389418907"
  },
  "tx": {
    "to": "0xc111111111111111111111111111111111111111",
    "data": "0x4f8f0218000000000000000000000000000000000000000000170417b4266522128b022800000000000000000000000000000000000000000000000000af8082c8729a2700000000000000000000000099999999999999999999999999999999999999990000000000000000000000008888888888888888888888888888888888888888",
    "value": "0",
    "chainId": 8453
  },
  "fallback": {
    "to": "0xc111111111111111111111111111111111111111",
    "data": "0xd04c6983000000000000000000000000000000000000000000170417b4266522128b022800000000000000000000000000000000000000000000000000af8082c8729a270000000000000000000000009999999999999999999999999999999999999999",
    "value": "0",
    "chainId": 8453
  },
  "approval": {
    "token": "0x1111111111111111111111111111111111111111",
    "spender": "0xc111111111111111111111111111111111111111",
    "amount": "27824620573355817875210792",
    "tx": {
      "to": "0x1111111111111111111111111111111111111111",
      "data": "0x095ea7b3000000000000000000000000c111111111111111111111111111111111111111000000000000000000000000000000000000000000170417b4266522128b0228",
      "value": "0",
      "chainId": 8453
    }
  }
}
```

#### Errors

`400 bad_address``400 bad_amount``400 bad_slippage``400 bad_recipient``400 bad_sender``400 sender_required``400 recipient_unsupported``400 bad_referrer``400 bad_json``400 bad_params``404 not_found``409 not_tradable``413 too_large``422 quote_failed``429 rate_limited``503 state_unavailable``503 quote_unavailable``503 pool_unavailable`

### Quote a trade

GET`/v1/quote`

What `amountIn` buys or sells right now, with the slippage floor, without building a transaction. A coin on its curve is quoted from the indexed reserves; a graduated coin from the pool quoter (cached 2 seconds, limited globally).

#### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `coin` query, required | `string` | The coin's token address, any case. |
| `side` query, required | `"buy" \| "sell"` | buy: amountIn is the pair asset. sell: amountIn is the coin. |
| `amountIn` query, required | `string` | Raw units, a positive decimal string. |
| `slippageBps` query | `integer` | Slippage in basis points for minAmountOut, 0 to 9999. Default 100. (0 to 9999, default 100) |

#### Response 200

The quote.

| Field | Type | Description |
| --- | --- | --- |
| `chainId` required | `8453` |  |
| `coin` required | `address` | Lowercase 20-byte hex address. |
| `side` required | `"buy" \| "sell"` |  |
| `route` required | `"curve" \| "pool"` |  |
| `quote` required | `object` |  |
| `quote.amountIn` required | `amount` | Non-negative decimal string in raw units. |
| `quote.amountOut` required | `amount` | Coins received on a buy, pair asset received on a sell. |
| `quote.minAmountOut` required | `amount` | The slippage floor in the transaction. |
| `quote.source` required | `"indexed" \| "quoter"` | indexed: the curve reserves the indexer stored. quoter: the Uniswap V4 quoter. |
| `quote.asOf` required | `integer` | Unix seconds of the state the quote was computed from. |
| `quote.spent` | `amount` | Buy on the curve: the pair asset the curve keeps (less than amountIn when the buy fills the curve and the rest is refunded). |
| `quote.refund` | `amount` | Buy on the curve: the part of amountIn sent back. |
| `quote.fee` | `amount` | Curve trades: the base trade fee in pair units. |
| `quote.creatorFee` | `amount` | Curve trades: the creator fee in pair units. |
| `quote.snipeTax` | `amount` | Curve buy: the early-buy tax a wallet not exempted at launch pays right now, in pair units. |
| `quote.willGraduate` | `boolean` | Curve buy: true when this buy fills the curve and graduates the coin. |

GET /v1/quote responsejson

```
{
  "chainId": 8453,
  "coin": "0x1111111111111111111111111111111111111111",
  "side": "buy",
  "route": "curve",
  "quote": {
    "amountIn": "100000000000000000",
    "amountOut": "55118110236220472440944881",
    "minAmountOut": "54566929133858267716535432",
    "source": "indexed",
    "asOf": 1759999990,
    "spent": "100000000000000000",
    "refund": "0",
    "fee": "1000000000000000",
    "creatorFee": "1000000000000000",
    "snipeTax": "0",
    "willGraduate": false
  }
}
```

#### Errors

`400 bad_address``400 bad_amount``400 bad_slippage``400 bad_side``404 not_found``409 not_tradable``422 quote_failed``429 rate_limited``503 state_unavailable``503 quote_unavailable``503 pool_unavailable`

## This document

### This document

GET`/v1/openapi.json`

The OpenAPI 3.1 description of this API, as JSON.

#### Response 200

The OpenAPI document.

GET /v1/openapi.json responsejson

```
{
  "openapi": "3.1.0",
  "info": {
    "title": "baselaunch public API",
    "version": "1.0.0"
  },
  "paths": {}
}
```

#### Errors

`429 rate_limited`

## Live feed

### Live feed

`wss://api.baselaunch.app/v1/ws`

Push feed at the url below. Open a WebSocket, then send JSON text messages (at most 4096 bytes) to subscribe. Every server message is {"type", "data"}. A request is acknowledged with `subscribed`, or refused whole with `error`; a refused request changes nothing. There is no unsubscribe message: close the socket. A message over 4096 bytes closes the connection (close code 1009) instead of getting a reply. Limits: 20 subscriptions per client (each coin in a trade or curve request counts as one), 2000 clients in total (503 on upgrade beyond that), 10 connections per client IP (429 on upgrade beyond that). Each socket may send at most 100 messages per minute; a socket that sends more is closed with code 1008 (policy violation) and no reply. The server pings every 30 seconds; a client that does not answer is dropped, so use a library that answers pings. The feed carries live events only and never replays history; use the REST routes to backfill, and reconnect with a fresh subscription after a drop.

#### Requests a client sends

subscribe newCoin

Every new launch, as the Coin shape of the REST API.

subscribe newCoinjson

```
{
  "sub": "newCoin"
}
```

subscribe graduation

Sent when a coin leaves the curve (phase graduating) and again when its pool opens (phase graduated).

subscribe graduationjson

```
{
  "sub": "graduation"
}
```

subscribe trade

Trades of the listed coins, or of every coin with "all".

subscribe tradejson

```
{
  "sub": "trade",
  "coins": [
    "0x1111111111111111111111111111111111111111"
  ]
}
```

subscribe wallet

Every trade by one of the listed wallets, on any coin, as {type: wallet, data: Trade plus coin}. Like the coin lists: at most 20 wallets per request, each counting toward the 20 subscriptions of the client.

subscribe walletjson

```
{
  "sub": "wallet",
  "wallets": [
    "0x9999999999999999999999999999999999999999"
  ]
}
```

subscribe curve

Curve progress and market data of the listed coins, after each live trade of the coin and on its phase changes. The reserve is read from stored state and can trail a trade by one refresh.

subscribe curvejson

```
{
  "sub": "curve",
  "coins": [
    "0x1111111111111111111111111111111111111111"
  ]
}
```

#### Messages the server sends

subscribed

Acknowledges an accepted request, also a repeat of one already held.

subscribed messagejson

```
{
  "type": "subscribed",
  "data": {
    "sub": "trade",
    "coins": [
      "0x1111111111111111111111111111111111111111"
    ]
  }
}
```

error

Refuses a request: bad_message (not valid JSON, an unknown request, or a coins list that is empty or longer than 20 for trade or curve, or such a wallets list for wallet), bad_address (an entry that is not an address), too_many_subs (the request would take the client past 20 subscriptions).

error messagejson

```
{
  "type": "error",
  "data": {
    "error": "too_many_subs"
  }
}
```

newCoin

A new launch; data is the Coin shape.

newCoin messagejson

```
{
  "type": "newCoin",
  "data": {
    "chainId": 8453,
    "address": "0x1111111111111111111111111111111111111111",
    "name": "Example Coin",
    "ticker": "EXC",
    "logo": null,
    "description": "",
    "socials": {},
    "set": "v21",
    "phase": "curve",
    "curve": "0xc111111111111111111111111111111111111111",
    "creator": "0x9999999999999999999999999999999999999999",
    "feeRecipient": "0x9999999999999999999999999999999999999999",
    "creatorFeeBps": 100,
    "interface": null,
    "launchReferrer": null,
    "pair": {
      "quote": "0x0000000000000000000000000000000000000000",
      "symbol": "ETH",
      "decimals": 18
    },
    "launchedAt": 1760000000,
    "launchBlock": 38000000,
    "poolId": null,
    "graduation": {
      "threshold": "1000000000000000000",
      "reserve": null,
      "progress": 0
    },
    "market": {
      "price": 0,
      "marketCapQuote": 0,
      "volume24hQuote": 0,
      "marketCapUsd": null,
      "volume24hUsd": null,
      "change24h": 0
    }
  }
}
```

trade

A trade; data is the Trade shape plus the coin address.

trade messagejson

```
{
  "type": "trade",
  "data": {
    "coin": "0x1111111111111111111111111111111111111111",
    "tx": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "logIndex": 3,
    "side": "buy",
    "venue": "curve",
    "quoteAmount": "100000000000000000",
    "tokenAmount": "200000000000000000000000",
    "price": 5e-7,
    "wallet": "0x9999999999999999999999999999999999999999",
    "block": 38000100,
    "timestamp": 1760000200,
    "referrer": null,
    "referrerAmount": null
  }
}
```

wallet

A trade by a subscribed wallet; data is the Trade shape plus the coin address. Sent once per trade.

wallet messagejson

```
{
  "type": "wallet",
  "data": {
    "coin": "0x1111111111111111111111111111111111111111",
    "tx": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "logIndex": 3,
    "side": "sell",
    "venue": "curve",
    "quoteAmount": "100000000000000000",
    "tokenAmount": "200000000000000000000000",
    "price": 5e-7,
    "wallet": "0x9999999999999999999999999999999999999999",
    "block": 38000100,
    "timestamp": 1760000200,
    "referrer": null,
    "referrerAmount": null
  }
}
```

graduation

A coin left the curve or opened its pool; data is the Coin shape and data.phase says which.

graduation messagejson

```
{
  "type": "graduation",
  "data": {
    "chainId": 8453,
    "address": "0x1111111111111111111111111111111111111111",
    "name": "Example Coin",
    "ticker": "EXC",
    "logo": null,
    "description": "",
    "socials": {},
    "set": "v21",
    "phase": "graduating",
    "curve": "0xc111111111111111111111111111111111111111",
    "creator": "0x9999999999999999999999999999999999999999",
    "feeRecipient": "0x9999999999999999999999999999999999999999",
    "creatorFeeBps": 100,
    "interface": null,
    "launchReferrer": null,
    "pair": {
      "quote": "0x0000000000000000000000000000000000000000",
      "symbol": "ETH",
      "decimals": 18
    },
    "launchedAt": 1760000000,
    "launchBlock": 38000000,
    "poolId": null,
    "graduation": {
      "threshold": "1000000000000000000",
      "reserve": null,
      "progress": 1
    },
    "market": {
      "price": 5e-7,
      "marketCapQuote": 500,
      "volume24hQuote": 3,
      "marketCapUsd": null,
      "volume24hUsd": null,
      "change24h": 0.1
    }
  }
}
```

curve

Curve progress of a subscribed coin.

curve messagejson

```
{
  "type": "curve",
  "data": {
    "address": "0x1111111111111111111111111111111111111111",
    "phase": "curve",
    "graduation": {
      "threshold": "1000000000000000000",
      "reserve": "250000000000000000",
      "progress": 0.25
    },
    "market": {
      "price": 5e-7,
      "marketCapQuote": 500,
      "volume24hQuote": 3,
      "marketCapUsd": null,
      "volume24hUsd": null,
      "change24h": 0.1
    }
  }
}
```

## Errors

Every error is a JSON object with an `error` code and sometimes a short `detail`. Every error code the API returns, by status:

| Status | Error codes | When |
| --- | --- | --- |
| `400` | `bad_address``bad_cursor``bad_interval``bad_range``bad_wallet``bad_amount``bad_slippage``bad_recipient``bad_sender``sender_required``recipient_unsupported``bad_referrer``bad_side``bad_json``bad_params` | A malformed address, cursor or builder field. |
| `404` | `not_found` | No such coin or route. |
| `405` | `method` | The HTTP method is not allowed for the route. |
| `409` | `not_tradable` | The coin cannot be traded right now: it is moving from its curve to its pool. |
| `413` | `too_large` | The request body is over 32 KB. |
| `422` | `quote_failed` | The contract would refuse this trade (for example it is too small to buy anything); `detail` names the reason. |
| `429` | `rate_limited` | More requests in a minute from this client IP than its limit: 120 for reads, 30 for builders and quotes. |
| `500` | `server_error` | The server failed; try again later. |
| `503` | `state_unavailable``quote_unavailable``pool_unavailable``launch_unavailable` | The curve reserves are not indexed yet, the pool quote capacity is used up or the quoter failed, the coin's pool is not buildable, or launching is not available. Retry shortly; `retry-after` is sent. |

13 operations and a live feed. Guided examples are in the [docs](https://baselaunch.app/docs).

How the fees are split is on [fees](https://baselaunch.app/fees), what the owner can and cannot change is on [security](https://baselaunch.app/security), and short answers are in the [FAQ](https://baselaunch.app/faq).

Meme coins are highly speculative and most lose their value. Nothing here is financial advice.

Last updated 2026-10-21.

Canonical page: https://baselaunch.app/docs/api