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

# Data Source REST API

> Finalized catalogs, trading history, account fee tiers, and account value and PnL snapshots.

The REST method playground defaults to mainnet and offers testnet in its server dropdown:

```text theme={null}
Mainnet (default): https://api.mainnet.kuru.io
Testnet: https://api.testnet.kuru.io
```

It exposes finalized exchange data under `/api/v1`. Catalog resources use a
`feedEpoch: null` envelope because they are not WebSocket replay cuts. Market
and user datasets return the committed `feedEpoch` and the corresponding
`marketSeq` or `globalUserSeq` when a replay cursor is available.

<CardGroup cols={2}>
  <Card title="Markets" icon="store" href="/api/data-source/reference/markets">
    Browse spot markets and trailing 24-hour summaries.
  </Card>

  <Card title="Market details" icon="circle-info" href="/api/data-source/reference/market">
    Read one market's tokens and trading configuration.
  </Card>

  <Card title="Market trades" icon="chart-line" href="/api/data-source/reference/market-trades">
    Read finalized fills and obtain the market WebSocket join cursor.
  </Card>

  <Card title="Tokens" icon="coins" href="/api/data-source/reference/tokens">
    Browse supported token metadata.
  </Card>

  <Card title="Token details" icon="coin" href="/api/data-source/reference/token">
    Read one supported token.
  </Card>

  <Card title="Candles" icon="chart-candlestick" href="/api/data-source/reference/candles">
    Query historical OHLCV candles.
  </Card>

  <Card title="Resolve user" icon="address-card" href="/api/data-source/reference/resolve-user">
    Resolve a wallet address to its Kuru user ID.
  </Card>

  <Card title="User open orders" icon="list" href="/api/data-source/reference/user-orders">
    Read a finalized open-order snapshot and its user cursor.
  </Card>

  <Card title="User balances" icon="wallet" href="/api/data-source/reference/user-balances">
    Read all finalized balances or select one token.
  </Card>

  <Card title="User trades" icon="receipt" href="/api/data-source/reference/user-trades">
    Read finalized maker and taker trades with fees and PnL.
  </Card>

  <Card title="Order events" icon="clock-rotate-left" href="/api/data-source/reference/order-events">
    Read finalized order creation, cancellation, and RAB reduction history.
  </Card>
</CardGroup>

<CardGroup cols={2}>
  <Card title="User fee tier" icon="receipt" href="/api/data-source/reference/user-fee-tier">
    Read the root account's assigned maker and taker fee rates.
  </Card>

  <Card title="Account value and PnL snapshots" icon="chart-line" href="/api/data-source/reference/account-value-snapshots">
    Read hourly USDC account value and cumulative PnL history.
  </Card>
</CardGroup>

Fee tiers and account-value snapshots return `feedEpoch` as a decimal string
(or `null` before initialization), without a replay sequence. An epoch of `"0"`
is valid for a fresh feed. These endpoints are not WebSocket replay bootstraps.

## REST to WebSocket handoff

For market trades, pair `feedEpoch` with `marketSeq` and subscribe to the
matching finalized market stream. For user orders, balances, or trades, pair
`feedEpoch` with `globalUserSeq` and subscribe to the matching finalized user
stream. Install the REST data first, then request replay from that exact cursor.

Both cursor fields may be `null` before the current feed epoch has materialized
that scope. In that case the response remains valid finalized data, but it is
not a WebSocket replay bootstrap.

## Response envelopes

Catalog collections return:

```json theme={null}
{"feedEpoch":null,"data":[],"pagination":{"nextCursor":null}}
```

Catalog resources and candles return:

```json theme={null}
{"feedEpoch":null,"data":{}}
```

Errors include a request ID for support and tracing:

```json theme={null}
{
  "feedEpoch": null,
  "error": {"code": "BadRequest", "message": "invalid request"},
  "requestId": "01J..."
}
```


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