> For the complete documentation index, see [llms.txt](https://zardoz.gitbook.io/zardoz-docs-1/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://zardoz.gitbook.io/zardoz-docs-1/http-apis-full-reference.md).

# HTTP APIs (full reference)

## HTTP APIs (full reference)

Base URL: **<https://zardoz.fun>**

Most routes accept `?network=mainnet` or `?network=testnet` (see `lib/data/net-param.ts`).

Market data is aggregated from Blockscout, DexScreener, GeckoTerminal, and pad APIs. Treat responses as **best-effort** — verify critical amounts on-chain before signing.

Interactive OpenAPI: **zardoz-api** (GitBook org spec). Source: `docs/openapi/zardoz-api.yaml`.

***

### Common parameters

| Param     | Values               | Used on                  |
| --------- | -------------------- | ------------------------ |
| `network` | `mainnet`, `testnet` | Most GET routes          |
| `limit`   | integer (caps vary)  | List endpoints           |
| `token`   | `0x` address         | candles, trades, holders |

***

### Discover & tokens

#### `GET /api/tokens`

Discover feed — merged token summaries.

| Query     | Default     | Max |
| --------- | ----------- | --- |
| `sort`    | `lastTrade` | —   |
| `limit`   | 500         | 800 |
| `network` | mainnet     | —   |

```bash
curl "https://zardoz.fun/api/tokens?network=mainnet&sort=lastTrade&limit=100"
```

Returns array of token objects: address, name, symbol, logo, price, mcap, liquidity, volume, launchpad, pool hints, timestamps.

***

#### `GET /api/token/{address}`

Single token detail — merges pad metadata, DEX stats, on-chain reads.

```bash
curl "https://zardoz.fun/api/token/0xYourToken?network=mainnet"
```

| Status | Meaning                   |
| ------ | ------------------------- |
| 200    | Token summary             |
| 404    | Unknown / not indexed yet |

***

#### `GET /api/token/{address}/overlap`

Wallet overlap for a token — addresses holding this token that also appear in watchlist / cluster data.

***

#### `GET /api/stats`

Aggregate product / chain stats for dashboards.

```bash
curl "https://zardoz.fun/api/stats?network=mainnet"
```

***

### Launches & creators

#### `GET /api/launches`

**Primary indexer feed** — recent Zardoz Instant `TokenCreated` launches.

| Query     | Default | Max |
| --------- | ------- | --- |
| `limit`   | 80      | 200 |
| `network` | mainnet | —   |

```bash
curl "https://zardoz.fun/api/launches?network=mainnet&limit=80"
```

Response fields: `network`, `chainId`, `factory`, `launchpad`, `count`, `launches[]` with token, creator, pool, feeTier, name, symbol, metadataURI, logoURI, supply fields, blockNumber, timestamp, txHash.

***

#### `GET /api/creator-launches`

Launches by creator wallet.

| Query     | Required     |
| --------- | ------------ |
| `creator` | `0x` address |
| `network` | optional     |

```bash
curl "https://zardoz.fun/api/creator-launches?creator=0x…&network=mainnet"
```

***

#### `POST /api/launches/fee-record`

Record launch fee attribution for analytics. **Requires session.**

Body: launch tx metadata + ref info (JSON).

***

### Charts & market data

#### `GET /api/candles`

OHLCV series for Lite chart.

| Query      | Required | Notes             |
| ---------- | -------- | ----------------- |
| `token`    | yes      | Token address     |
| `interval` | no       | Default `5m`      |
| `pool`     | no       | Pool address hint |
| `network`  | no       | mainnet default   |

```bash
curl "https://zardoz.fun/api/candles?token=0x…&interval=5m&network=mainnet"
```

***

#### `GET /api/trades`

Recent trade tape for a token.

| Query     | Required       |
| --------- | -------------- |
| `token`   | yes            |
| `pair`    | no — pool hint |
| `network` | no             |

```bash
curl "https://zardoz.fun/api/trades?token=0x…&network=mainnet"
```

***

#### `GET /api/holders`

Top holders via Blockscout proxy.

| Query     | Required |
| --------- | -------- |
| `token`   | yes      |
| `network` | no       |

```bash
curl "https://zardoz.fun/api/holders?token=0x…&network=mainnet"
```

***

#### `GET /api/ethusd`

ETH/USD price oracle snapshot for UI conversions.

```bash
curl "https://zardoz.fun/api/ethusd"
```

No params. Short cache.

***

### Signals & watch

#### `GET /api/signals`

Live signals: clusters, heat, new pools, watched-wallet buys.

```bash
curl "https://zardoz.fun/api/signals?network=mainnet"
```

***

#### `GET /api/signals/clusters`

Wallet cluster groups with shared-token overlap scores.

```bash
curl "https://zardoz.fun/api/signals/clusters?network=mainnet"
```

***

#### `GET /api/watch/wallets`

Curated KOL / smart-wallet directory.

| Query  | Values                             |
| ------ | ---------------------------------- |
| `q`    | search substring                   |
| `kind` | `kol`, `smart`, `both`, omit = all |

```bash
curl "https://zardoz.fun/api/watch/wallets?kind=smart&q=whale"
```

***

#### `GET /api/watch/activity`

Recent trades from watched wallets.

| Query     | Default | Max                                  |
| --------- | ------- | ------------------------------------ |
| `limit`   | 80      | 150                                  |
| `wallets` | —       | comma-separated extra `0x` addresses |

```bash
curl "https://zardoz.fun/api/watch/activity?limit=50&wallets=0xabc…,0xdef…"
```

***

### Wallets & portfolio

#### `GET /api/holdings`

ERC-20 holdings for a wallet (Blockscout proxy — avoids browser CORS).

| Query     | Required |
| --------- | -------- |
| `address` | yes      |
| `network` | no       |

```bash
curl "https://zardoz.fun/api/holdings?address=0x…&network=mainnet"
```

Soft-degrades to `{ items: [], degraded: true }` on Blockscout timeout.

***

#### `GET /api/pnl`

PnL summary for a wallet.

| Query     | Required |
| --------- | -------- |
| `address` | yes      |
| `network` | no       |

```bash
curl "https://zardoz.fun/api/pnl?address=0x…&network=mainnet"
```

***

#### `GET /api/wallet`

Google embedded wallet address for signed-in user. **Requires session.**

Returns `{ walletAddress, hasWallet, walletCreatedAt }` — never private key.

***

#### `POST /api/wallet`

Generate or import embedded wallet. **Requires session.**

Body: `{ action: "generate" | "import", privateKey?: string }`

***

#### `PUT /api/wallet`

Update wallet settings. **Requires session.**

***

#### `GET /api/wallet/{address}`

Public wallet profile page data.

***

#### `GET /api/trading-wallets`

List session-linked vault wallets.

#### `POST /api/trading-wallets`

Add vault wallet or generate new.

#### `PUT /api/trading-wallets`

Bulk update labels / DEV tags.

#### `DELETE /api/trading-wallets`

Remove vault by address query param.

All require authenticated session.

***

### Referrals

#### `GET /api/refs`

Ref stats for a wallet.

```
GET /api/refs?wallet=0x…
```

#### `POST /api/refs`

Bind referral code to session account.

***

### Launch & metadata

#### `POST /api/pin`

Pin image and/or JSON metadata via Pinata.

**Multipart:**

| Field      | Type        |
| ---------- | ----------- |
| `logo`     | image file  |
| `metadata` | JSON string |

**JSON body:** metadata object directly.

Requires server `PINATA_JWT`. Returns IPFS / gateway URIs for factory `metadataURI` / `logoURI`.

See Pin API & metadata.

***

### Social & realtime

#### `GET /api/chat/{token}`

Token chat messages.

| Query   | Default     |
| ------- | ----------- |
| `since` | 0 (unix ms) |

#### `POST /api/chat/{token}`

Post chat message (body JSON).

***

#### `GET /api/live/{token}`

Live viewer / stream metadata for token page.

#### `POST /api/live/{token}`

Update live state (creator / admin flows).

***

### IPFS gateway

#### `GET /api/ipfs/{...cid}`

Proxy fetch for IPFS content — avoids mixed-content / CORS in browser.

```
GET /api/ipfs/Qm…/path/to/file
```

***

### Auth

#### `GET/POST /api/auth/[...nextauth]`

NextAuth handlers — Google OAuth session for embedded wallet features.

Not required for public read APIs.

***

### Rate limits & caching

| Behavior      | Detail                                              |
| ------------- | --------------------------------------------------- |
| Cache-Control | Most routes `no-store` or short TTL                 |
| Timeouts      | Upstream Blockscout / DEX calls may soft-fail empty |
| Auth routes   | 401 without session                                 |

***

### Quick copy — indexer bootstrap

```bash
# Latest Instant launches
curl -s "https://zardoz.fun/api/launches?network=mainnet&limit=200" | jq .

# Full discover feed
curl -s "https://zardoz.fun/api/tokens?network=mainnet&limit=800" | jq '[.[] | select(.launchpad=="zardoz")]'

# Token detail
curl -s "https://zardoz.fun/api/token/0xTOKEN?network=mainnet" | jq .
```

Next: Indexer integration · Pin API


---

# 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://zardoz.gitbook.io/zardoz-docs-1/http-apis-full-reference.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.