> For the complete documentation index, see [llms.txt](https://docs.surged.fun/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.surged.fun/integration/api.md).

# API

A public, read-only HTTP api over the indexed launchpad. No key, no sign-up, no rate limit you will notice from one client.

```
https://api.surged.fun
```

Every response is JSON and every route is cached for a few seconds, so hammering it gains you nothing. For anything that must be immediate, use the [realtime feed](/integration/api/realtime.md) instead of polling.

## Why not read the chain

You can, and for a single balance you should. But everything a listing needs, price history, volume, holders and who traded what, is spread across thousands of events. Reconstructing it means running an indexer. This api is that indexer, already run.

Two things it does that are worth knowing:

* **Aggregates are computed on write, never on read.** Candles, volume and market cap are updated as each trade is indexed, so a listing is a single lookup.
* **Amounts are decimal strings**, not numbers. They do not fit in a JavaScript number. Parse them as `bigint`, and use `curveStateFromApi` from the SDK for the ones the formula needs.

## The routes

| Route                           | What it gives you                                                                                                            |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `GET /health`                   | Chain head, indexed block and lag. Use `head` to price a buy.                                                                |
| `GET /config`                   | Launch fee, launch configurations, snipe terms, fee policy, addresses.                                                       |
| `GET /launches`                 | The listing. Sort by `recent`, `volume`, `active`, `gainers`, `marketcap` or `graduated`; search by name, symbol or address. |
| `GET /launches/{token}`         | One launch in full: terms, curve state, fees, graduation.                                                                    |
| `GET /launches/{token}/trades`  | Trades, newest first, paged with `before={block}`.                                                                           |
| `GET /launches/{token}/candles` | One-minute OHLCV between two timestamps.                                                                                     |
| `GET /rankings`                 | Who leads each ranking right now.                                                                                            |
| `GET /ws`                       | The realtime feed.                                                                                                           |

Field by field, with the units, in the [reference](/integration/api/reference.md).

## Pagination

`GET /launches` pages with `limit` and `page`. Trades page by block instead, because new ones arrive while you read: pass the oldest `blockNumber` you have as `before` and you will never skip or repeat one.

## A worked read

Everything a token page needs, in three calls:

```ts
const [launch, trades, candles] = await Promise.all([
  fetch(`${API}/launches/${token}`).then((r) => r.json()),
  fetch(`${API}/launches/${token}/trades?limit=50`).then((r) => r.json()),
  fetch(`${API}/launches/${token}/candles?from=${from}&to=${to}`).then((r) => r.json()),
])
```

Then subscribe to `token:{address}` on the websocket and you never poll again.

## Stability

The routes above are the public surface and will not change shape without a version. Anything not listed here, in particular anything under `/admin`, `/rpc`, `/images` or `/webhooks`, is internal: it needs a secret or an admin wallet, it is left out of the reference on purpose, and it can change at any time.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.surged.fun/integration/api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.