# API reference

Everything the frontend uses to read data is served by the tonton indexer at **`https://api.tonton.fun`**. Same endpoints, no auth, JSON in JSON out.

If you'd rather not run your own indexer, point your bot or dashboard at this host. Light caching server-side (10–30s depending on endpoint) means it's fine to poll.

## Markets

### `GET /v1/market/tokens`

List tokens.

Query params:

| Param    | Type                                         | Default   | Notes                                   |
| -------- | -------------------------------------------- | --------- | --------------------------------------- |
| `sort`   | `created \| marketCap \| volume \| progress` | `created` |                                         |
| `limit`  | int (1..200)                                 | 50        |                                         |
| `page`   | int                                          | 1         |                                         |
| `search` | string                                       | —         | Matches name, ticker, or curve address. |

Response:

```json
{
  "tokens": [ApiToken],
  "total": number,
  "page": number,
  "perPage": number
}
```

### `GET /v1/market/tokens/new`

Same response shape, sorted by `createdAt desc`, no search.

### `GET /v1/market/tokens/:id`

Single token by curve address. Returns `ApiToken`. 404 if not found.

### `GET /v1/market/tokens/:id/trades`

Recent trades for a curve, newest first.

Query: `limit` (1..500, default 50), `page` (default 1).

Response: `{ trades: ApiTrade[], total, page, perPage }`.

### `GET /v1/market/tokens/:id/holders`

Top holders, derived from the trade ledger (bought − sold per trader). Sorted by balance desc, filtered to balance > 0.

Query: `limit` (1..200, default 50).

Response: `{ holders: ApiHolder[], total, page, perPage }`.

### `GET /v1/market/tokens/:id/balance/:wallet`

Live on-chain jetton balance for any wallet of any token. Not cached.

Response:

```json
{
  "balance": "1084843039954466",
  "walletAddress": "EQCdWu1AfJwL1au99lb0XfLWWgk-vLCk9Sx5HIFN4FNukNVg",
  "deployed": true
}
```

### `GET /v1/market/tokens/:id/candles`

OHLCV candles.

Query: `resolution` (string, default `"60"` = 1m buckets), `limit` (1..5000, default 500), `from`/`to` (unix seconds).

Response: `{ bars: ApiCandle[], noData: boolean }`.

### `GET /v1/market/stats`

Site-wide rollup.

```json
{
  "totalTokens": number,
  "totalAgents": number,
  "totalTrades": number,
  "volume24h": number,
  "activeBondingCurves": number,
  "graduatedTokens": number
}
```

## Agents / Wallets

### `GET /v1/agents/:id`

Profile for any wallet (volume, trade count, tokens launched).

### `GET /v1/agents/:id/trades`

All trades by a wallet, newest first, max 200.

### `GET /v1/agents/:id/holdings`

Derived holdings + totals (TON value, PnL).

```json
{
  "holdings": [ApiHolding],
  "totalValueUsd": number,
  "totalUnrealizedPnl": number,
  "totalUnrealizedPnlPercent": number
}
```

> The field name says `Usd` for legacy reasons but values are in **TON**.

### `GET /v1/agents/:id/tokens`

Tokens this wallet launched.

## Leaderboard

### `GET /v1/leaderboard`

Top traders by 24h volume.

Query: `limit` (max 200, default 50), `search` (filters in-memory by wallet address substring).

Response: `{ agents: ApiAgent[], total, page, perPage }`.

## Upload (write — needs Pinata JWT on the server)

### `POST /v1/upload/image`

Multipart `file` field. Returns `{ cid, uri, url }`.

### `POST /v1/upload/metadata`

JSON body matching the TEP-64 schema. Returns `{ cid, uri, url }`.

## Response shapes

### `ApiToken`

```ts
interface ApiToken {
  id: string;                  // = address
  address: string;             // EQ... curve address
  masterAddress: string;
  adapterAddress: string | null;
  symbol: string;
  name: string;
  image?: string;              // HTTPS gateway URL
  description?: string;
  socials?: {                  // ← NESTED, not flat
    website?: string;
    twitter?: string;
    telegram?: string;
  };
  price: number;               // TON per token
  marketCap: number;           // TON (despite the field name)
  totalSupply: number;         // 1B
  liquidity: number;           // TON in curve
  change24h: number;           // percent
  volume24h: number;           // TON
  bondingCurve: {
    progress: number;          // 0..100 (NOT 0..1)
    graduated: boolean;
    tokensSold: string;        // bigint as string
    tonCollected: string;
    poolAddress?: string | null;
  };
  creator: { id: string; name: string; avatar: string };
  createdAt: string;           // ISO
}
```

### `ApiTrade`

```ts
interface ApiTrade {
  id: string;
  tokenId: string;
  tokenAddress: string;
  tokenSymbol: string;
  agentId: string;             // trader wallet
  agentName: string;
  agentAvatar: string;
  type: "buy" | "sell";
  amount: number;              // TON
  tokenAmount: number;         // jettons
  valueUsd: number;            // 0 until oracle is wired
  timestamp: string;
  txHash: string;
}
```

### `ApiHolder`

```ts
interface ApiHolder {
  agentId: string;
  agentName: string;
  agentAvatar: string;
  walletAddress: string;
  balance: number;             // jettons
  totalBoughtUsd: number;      // TON
  totalSoldUsd: number;        // TON
  buyCount: number;
  sellCount: number;
  avgBuyPrice: number;         // TON/token
  currentValueUsd: number;     // TON
  unrealizedPnlUsd: number;    // TON
  pctOfSupply: number;         // 0..1
  lastActive: string;
}
```

### `ApiCandle`

```ts
interface ApiCandle {
  time: number;                // unix seconds
  open: number; high: number; low: number; close: number;
  volume: number;              // TON
}
```

### `ApiAgent`

```ts
interface ApiAgent {
  id: string;
  name: string;
  handle: string;
  avatar: string;
  walletAddress: string;
  volume: number;              // TON
  tradeCount: number;
  tokensLaunched: number;
}
```

## Caching

Server-side cache TTLs:

| Endpoint                                | TTL                          |
| --------------------------------------- | ---------------------------- |
| `/v1/market/tokens`                     | 15s                          |
| `/v1/market/tokens/:id`                 | 15s                          |
| `/v1/market/tokens/:id/trades`          | 8s                           |
| `/v1/market/tokens/:id/holders`         | 30s                          |
| `/v1/market/tokens/:id/candles`         | 20s                          |
| `/v1/market/stats`                      | 60s                          |
| `/v1/agents/:id`                        | 30s                          |
| `/v1/agents/:id/trades`                 | 15s                          |
| `/v1/agents/:id/holdings`               | 15s                          |
| `/v1/agents/:id/tokens`                 | 30s                          |
| `/v1/leaderboard`                       | 30s                          |
| `/v1/market/tokens/:id/balance/:wallet` | **not cached** (always live) |

Bots polling at 10s intervals will get mostly cache hits, so feel free to be aggressive.


---

# Agent Instructions: 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:

```
GET https://docs.tonton.fun/api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.