> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pariprotocol.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API

> Read tokens, trades and wallet positions over HTTP.

The Pari API is a read-only HTTP API. It serves tokens, trades, wallet positions and protocol data as JSON. It takes no key, and it cannot build or send a transaction. To write, use the [SDK](https://docs.pariprotocol.xyz/build/sdk.md) or the [CLI](https://docs.pariprotocol.xyz/build/cli.md).

Pari is live on Solana and built to run on more chains. The API serves devnet only today.

## Base URL

Every route lives under `https://api.pariprotocol.xyz`. Try it:

```sh theme={null}
curl -s https://api.pariprotocol.xyz/v1/status
```

The examples below use a real token and wallet. Set them once:

```sh theme={null}
export API=https://api.pariprotocol.xyz
export MINT=AgjecsKW5mRCBqRHECFh4iXq6aHzX1hWCCkyFUoWUCVa
export WALLET=CfkTXZyqRSTM3qMQ97tk6B2Wdf39c4wdaSkferaypKPd
```

## Reading the numbers

* Amounts are decimal strings in base units, so they never lose precision.
* Each token states its `quote`: the `mint`, `symbol` and `decimals` of the asset its amounts are in.
* Token balances have 6 decimals.
* Times are Unix seconds.
* USD fields are `null` when no price is known.
* `finalized` is `true` once the data comes from a final slot.

## Paging

List routes return one page:

```json theme={null}
{ "items": [], "next": null }
```

* `limit` sets the page size. The default is 50 and the most is 100. A larger value is lowered to 100.
* `cursor` asks for the next page. Pass the `next` value from the page before.
* `next` is `null` on the last page.
* A cursor is opaque. Do not build or change one.

```sh theme={null}
curl -s "$API/v1/receipts?limit=2"
curl -s "$API/v1/receipts?limit=2&cursor=<next>"
```

## Errors

Every error has the same body:

```json theme={null}
{ "error": "bad_request", "message": "mint is not a valid address" }
```

| Status | `error` | Meaning |
| - | - | - |
| 400 | `bad_request` | A parameter is missing or wrong. `message` says which one. |
| 400 | `bad_cursor` | The cursor did not come from this API. |
| 404 | `not_found` | No such route or record. |
| 405 | `method_not_allowed` | The API only takes `GET`. |
| 429 | `rate_limited` | Too many requests from your IP. Wait for `Retry-After` seconds. |
| 503 | `busy` | The API cannot answer right now. Try again. |

Browsers can only call the API from the Pari site. Call it from your own server or script.

## Data and analytics

| Route | What it returns |
| - | - |
| `GET /v1/status` | The cluster, the program and how far the index has read. |
| `GET /v1/totals` | Global totals: launches, trades, volume and what snipers paid to holders. |
| `GET /v1/protocol` | Stake pool totals, the cooldown and the pause flags. |
| `GET /v1/pairs` | The pairs a launch can use: SOL and each tokenized stock. |
| `GET /v1/verify` | Program authorities, the admin, presets and declared wallets. |
| `GET /v1/receipts` | Sniper receipts of every token, newest first. |
| `GET /v1/rewards/:mint` | Published reward roots of a token. |
| `GET /v1/rewards/:mint/:epoch` | One published reward root. |
| `GET /v1/metrics/origin` | Launches, trades and volume per day and origin. Takes `from`, `to` and `origin`. |
| `GET /v1/integrators` | Registered integrators. |
| `GET /v1/integrators/:authority` | One integrator. |
| `GET /v1/integrators/:authority/launches` | Tokens launched with this integrator. |
| `GET /v1/integrators/:authority/earnings` | Daily bookings and withdrawals of this integrator. |

Tokenized stocks are not offered to US persons.

```sh theme={null}
curl -s "$API/v1/totals"
curl -s "$API/v1/pairs"
curl -s "$API/v1/metrics/origin?limit=5"
```

## Tokens

| Route | What it returns |
| - | - |
| `GET /v1/tokens` | Registered tokens, one page at a time. |
| `GET /v1/tokens/hot` | The tokens traded most in the last hour. `limit` goes from 1 to 20, default 12. |
| `GET /v1/tokens/:mint` | One token: record, preset, fee now, holder window, curve, migration, dev lock and volume. |
| `GET /v1/tokens/:mint/fees` | Fee bookings and payouts, with signatures. |
| `GET /v1/tokens/:mint/lock` | Lock proof: the migrated pool and how much of its liquidity is locked. See [Liquidity lock](https://docs.pariprotocol.xyz/protocol/liquidity-lock.md). |

`GET /v1/tokens` takes these filters:

| Parameter | Values |
| - | - |
| `sort` | `new` (default), `volume`, `holders` or `window` |
| `q` | Start of a name or ticker, 2 to 32 characters |
| `preset` | `light`, `standard` or `strict`. See [Presets](https://docs.pariprotocol.xyz/protocol/presets.md). |
| `migrated` | `true` or `false` |
| `window` | `open` or `closed` |
| `creator` | A wallet address |
| `integrator` | An integrator authority |

```sh theme={null}
curl -s "$API/v1/tokens?sort=volume&limit=5"
curl -s "$API/v1/tokens?q=cx&limit=5"
curl -s "$API/v1/tokens/$MINT"
curl -s "$API/v1/tokens/$MINT/lock"
```

For what the fee data means, see [Fees](https://docs.pariprotocol.xyz/protocol/fees.md).

## Trades

| Route | What it returns |
| - | - |
| `GET /v1/tokens/:mint/trades` | Trades, newest first. `venue` is `dbc` (the curve) or `damm` (the pool after migration). |
| `GET /v1/tokens/:mint/candles` | Price candles of both venues, merged. |
| `GET /v1/tokens/:mint/receipts` | Every trade inside the holder window, with the fee it paid and what holders got. `sniper=true` keeps only trades flagged as snipers. |

`candles` takes these parameters and returns at most 1000 buckets per call:

| Parameter | Values |
| - | - |
| `secs` | Bucket size: `60` (default), `300`, `3600` or `86400` |
| `from` | Start, in Unix seconds |
| `to` | End, in Unix seconds |

```sh theme={null}
curl -s "$API/v1/tokens/$MINT/trades?limit=5"
curl -s "$API/v1/tokens/$MINT/candles?secs=3600"
curl -s "$API/v1/tokens/$MINT/receipts?limit=5"
```

## Wallet positions

| Route | What it returns |
| - | - |
| `GET /v1/wallets/:wallet/tokens` | The Pari tokens a wallet holds, each with its `balance`. |
| `GET /v1/wallets/:wallet/stake` | Staked amount, pending rewards and cooling tickets. |
| `GET /v1/wallets/:wallet/rewards` | Holder rewards, one row per token: `claimable`, `waiting`, `claimed`, the `unit` and the leaf with its `proofUrl`. The totals cover SOL tokens. |
| `GET /v1/wallets/:wallet/rewards/leaves` | A stock token's rewards, leaf by leaf, with a `status` you can filter by. |
| `GET /v1/splits`, `GET /v1/tokens/:mint/splits` | Each fee split the operator's bot recorded, with its shares and any `mismatch`. |

A SOL token's rewards wait in its vault until the holder takes them; the row carries what a claim needs. A stock token's rewards are sent by the protocol, and `status` reports where each leaf is: `waiting`, `queued`, `delivered`, `recommit-pending`, `recommitted` or `cancelled`.

```sh theme={null}
curl -s "$API/v1/wallets/$WALLET/tokens?limit=5"
curl -s "$API/v1/wallets/$WALLET/stake"
curl -s "$API/v1/wallets/$WALLET/rewards?limit=5"
```

## Live feed

`GET /v1/stream` is a live feed of server-sent events. It stays open and sends each event as it happens.

| Parameter | Values |
| - | - |
| `topics` | A comma list, such as `launches,trades,receipts,rewards,splits`. The default is `launches`. |
| `mint` | Keep only this token's trades, receipts and rewards. |
| `after` | Resume after this event id. You can also send the `Last-Event-ID` header. |

```sh theme={null}
curl -sN "$API/v1/stream?topics=launches,trades"
```

Each event has an `event` name, an `id` and JSON `data`. The feed can also send three control events:

* `retract` withdraws earlier events.
* `reset` means you fell too far behind. Fetch the data again.
* `slow` means your client read too slowly. The server then closes the connection, so reconnect with `after`.

The [SDK](https://docs.pariprotocol.xyz/build/sdk.md) reads this feed for you and reconnects when it drops.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.