# API

The Tartarus API serves everything the site shows: indexed tokens, trades, candles, quotes and
balances. Base URL:

```
https://api.tartarus.world/v1
```

Responses are JSON. Amounts in **whole units** are JSON numbers, for display. Fields ending in `Raw`
are strings in raw units, for transactions. See [Decimals](/documentation/decimals).

## Protocol

| Endpoint | Returns |
|---|---|
| `GET /protocol` | Addresses, launch configs with floor prices, approved quotes, fee policy, launch-and-buy and holder-rewards wiring, `wsOrigin` |
| `GET /bridge` | The HyperEVM Inbox and Outbox, whether deposits are paused, the estimated withdrawal wait |
| `GET /bridge/withdrawals/:address` | HYPE withdrawn to an address, newest first, at most 50: `status` is `pending`, `ready` or `claimed`, with the `Outbox.executeTransaction` arguments in `claim` when ready |
| `GET /status` | Indexer and keeper health |
| `GET /health` | Liveness |
| `GET /platform` | The platform token, buybacks, burns and protocol analytics |

Read addresses and the fee policy from `GET /protocol` rather than hard-coding them.

## Tokens

| Endpoint | Returns |
|---|---|
| `GET /tokens` | A page of tokens. Filter with `tab`, `category`, `q`, `mcMin`, `mcMax`, `volMin`, `volMax`; page with `page`, `perPage` |
| `GET /tokens/bounds` | Filter ranges for the board |
| `GET /tokens/search` | Search by name, symbol or address |
| `GET /tokens/:id` | One token, including `fees`, `hypercoreStatus`, `bridgeWallet`, `creatorFeeRecipientPending` |
| `GET /tokens/:id/quote` | A trade quote. `side`, `amount` in whole units, `slippageBps` (default 100, at most 5000) |
| `GET /tokens/:id/trades` | Recent trades |
| `GET /tokens/:id/candles` | OHLC candles |
| `GET /tokens/:id/holders` | Holders |

`:id` is the token address. Quotes are limited to 20 per second per IP. Details are in
[Trading](/documentation/trading#quoting).

## Users

| Endpoint | Returns |
|---|---|
| `GET /users/:address` | Positions and `claimable`: escrow balances, unswept fees, holder-reward proofs |
| `GET /me`, `PUT /me` | The signed-in profile. Session required |

## Launching

| Endpoint | Returns |
|---|---|
| `GET /launch/symbol?symbol=` | `available`, and `reason`: `ok`, `invalid`, `reserved` or `taken` |
| `POST /launch/predict` | The token address, pool key, floor price, `expectedEconomics` and fee recipient for a launch. Session required |
| `POST /launch-drafts` | Stores a draft launch. Session required |
| `PUT /tokens/:id/meta` | Sets off-chain metadata such as the category. Session required |
| `POST /uploads/sign`, `POST /uploads/finalize` | Upload a token image. Session required |

`POST /launch/predict` answers `409` with a `reason` when a launch cannot go ahead: `taken`, `reserved`,
`rewardsNotWired` or `saltUsed`. Pick a new salt on `saltUsed`.

## Sessions

Sessions use Sign-In with Ethereum. `POST /auth/nonce` issues a nonce, and `POST /auth/verify` exchanges
the signed message for a session token. Send that token as `authorization: Bearer <token>`.

## JSON-RPC

`POST /rpc` is the Elysium RPC proxy. See [Elysium network](/documentation/network#which-rpc-to-use).

## WebSocket

Live updates come from `wss://ws.tartarus.world`. Use `wsOrigin` from `GET /protocol` rather than
hard-coding it. Server messages share one envelope:

```json
{ "v": 1, "type": "trade", "room": "token:0x…", "data": {}, "ts": 1793921370041 }
```

`ts` is in milliseconds. HTTP responses report `now` in seconds.

Subscribe to up to 32 rooms in one message:

```ts
const ws = new WebSocket(protocol.wsOrigin);
ws.onopen = () => ws.send(JSON.stringify({ type: "subscribe", rooms: ["board", `token:${address}`] }));
ws.onmessage = (e) => handle(JSON.parse(e.data));
```

| Room | Carries |
|---|---|
| `board` | New launches and token updates, for lists |
| `token:<address>` | Trades, candles and updates for one token. Lowercase the address |
| `head` | The latest indexed block |

A join starts with a `snapshot` message, followed by deltas. Other message types are:

| Type | What to do |
|---|---|
| `resync` | The feed restarted. Discard state and refetch over HTTP |
| `closing` | The server is draining. Reconnect after `reconnectAfterMs` |
| `error` | A bad room or request. `data` has `code` and `message` |
| `pong` | The answer to `{ "type": "ping" }` |

Frames carry the same shapes as the HTTP endpoints, so one parser handles both.