> ## 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. # Get orderbook depth > Get orderbook snapshot for a trading pair. Supports querying different consensus states. **Weight**: 1 (limit ≤ 100) / 5 (limit 101–500) / 10 (limit 501–1000) / 20 (limit > 1000) ## OpenAPI ````yaml /kuru-exchange/openapi.yaml get /api/v3/depth openapi: 3.0.3 info: title: Kuru Exchange WebSocket Server API description: > # Introduction The Kuru Exchange WebSocket Server provides REST and WebSocket APIs for streaming Kuru Exchange's orderbook data. ## Key Features - **Four-State Orderbook Model**: Reflects Monad's BFT consensus pipeline (Proposed, Voted, Finalized, Committed) - **High Performance**: Low latency orderbook updates directly consuming from Monad's event ring. - **Real-Time Streaming**: WebSocket subscriptions with efficient broadcast ## Monad Consensus States | State | Description | Use Case | |-------|-------------|----------| | **Proposed** | Block execution started, speculative | Lowest latency, highest risk | | **Voted** | Block received quorum certificate | Early confirmation | | **Finalized** | Block finalized (reorg-proof) | Safe for most applications | | **Committed** | State root verified | Maximum safety | ## Base URLs - **REST API**: `https://exchange.kuru.io` - **WebSocket**: `wss://exchange.kuru.io/ws` ## WebSocket Streams Connect to `wss://exchange.kuru.io` and send JSON messages to subscribe/unsubscribe. ### Subscription Format ```json { "method": "SUBSCRIBE", "params": ["mon_usdc@depth", "ethusdc@trade"], "id": 1 } ``` ### Available Stream Types | Stream | Description | Example | |--------|-------------|---------| | `@depth` | Full orderbook updates (committed state) | `mon_usdc@depth` | | `@depth5` | Top 5 levels | `mon_usdc@depth5` | | `@depth10` | Top 10 levels | `mon_usdc@depth10` | | `@depth20` | Top 20 levels | `mon_usdc@depth20` | | `@depth@` | Specific state orderbook | `mon_usdc@depth@proposed` | | `@monadDepth` | All states in one message | `mon_usdc@monadDepth` | | `@trade` | Trade stream | `mon_usdc@trade` | ### State Values - `proposed` - Block execution started - `voted` - Block received QC - `finalized` - Block finalized (reorg-proof) - `committed` - State root verified ## Rate Limits ### REST API The REST API uses a **token bucket** algorithm per IP address. | Parameter | Value | Description | |-----------|-------|-------------| | Refill rate | 1200 req/min (20 req/sec) | Tokens added continuously | | Burst capacity | 100 tokens | Max tokens in the bucket — allows short bursts | | Tracking | Per IP address | Each IP has its own independent bucket | Each request consumes a **weight** from the bucket. Heavier endpoints consume more tokens: | Endpoint | Weight | |----------|--------| | `GET /health` | 1 | | `GET /api/v3/trades` | 1 | | `GET /api/v3/ticker/24hr` | 1 | | `GET /api/v3/exchangeInfo` | 10 | | `GET /api/v3/klines` (limit ≤ 100) | 1 | | `GET /api/v3/klines` (limit 101–500) | 2 | | `GET /api/v3/klines` (limit > 500) | 5 | | `GET /api/v3/depth` (limit ≤ 100) | 1 | | `GET /api/v3/depth` (limit 101–500) | 5 | | `GET /api/v3/depth` (limit 501–1000) | 10 | | `GET /api/v3/depth` (limit > 1000) | 20 | When the bucket is empty the server returns **HTTP 429**. The response includes a `Retry-After` header indicating how many seconds until the next token is available. ### WebSocket | Limit | Value | Description | |-------|-------|-------------| | Connections per IP | 5 | Max concurrent WebSocket connections from a single IP | | Subscriptions per connection | 1024 | Max active stream subscriptions on one connection | | Broadcast buffer | 32,768 messages | Per-channel internal queue before backpressure | Connections that exceed the per-IP limit are rejected at the TCP accept stage. Subscription requests that exceed the per-connection limit are silently ignored — subscribe to fewer streams or open a new connection. version: 1.0.0 contact: name: Kuru Exchange license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html servers: - url: https://exchange.kuru.io description: Exchange server security: [] tags: - name: Market Data description: Market data endpoints (orderbook, trades, tickers) - name: User Data description: User-specific order and trade event endpoints - name: Exchange Info description: Exchange metadata and market information - name: Health description: Health and status endpoints paths: /api/v3/depth: get: tags: - Market Data summary: Get orderbook depth description: > Get orderbook snapshot for a trading pair. Supports querying different consensus states. **Weight**: 1 (limit ≤ 100) / 5 (limit 101–500) / 10 (limit 501–1000) / 20 (limit > 1000) operationId: getDepth parameters: - name: symbol in: query description: Trading pair symbol (e.g., MON_USDC, ETHUSDC) required: true schema: type: string example: MON_USDC - name: limit in: query description: Number of levels to return (default 100, max 5000) required: false schema: type: integer default: 100 minimum: 1 maximum: 5000 example: 100 - name: state in: query description: | Orderbook state to query (Monad-specific). Options: - `proposed`: Block started - `voted`: QC received - `finalized`: Reorg-proof - `committed`: State verified (default) required: false schema: type: string enum: - proposed - voted - finalized - committed default: committed example: committed responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/DepthResponse' example: lastUpdateId: 54467392 E: 1711000000000 T: 1711000000 bids: - - '100.50' - '10.5' - - '100.49' - '5.0' - - '100.48' - '8.3' asks: - - '100.51' - '8.2' - - '100.52' - '12.0' - - '100.53' - '6.5' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' example: code: -1102 msg: Mandatory parameter 'symbol' was not sent. '404': description: Symbol not found content: application/json: schema: $ref: '#/components/schemas/Error' example: code: -1121 msg: Invalid symbol. components: schemas: DepthResponse: type: object description: Orderbook depth response required: - lastUpdateId - E - T - bids - asks properties: lastUpdateId: type: integer format: int64 description: Block number of the snapshot example: 54467392 E: type: integer format: int64 description: >- Block timestamp in milliseconds (T × 1000), sourced from the Monad block header example: 1711000000000 T: type: integer format: int64 description: Block timestamp in Unix seconds, sourced from the Monad block header example: 1711000000 bids: type: array description: List of bid levels [price, quantity] items: type: array items: type: string minItems: 2 maxItems: 2 example: - - '100.50' - '10.5' - - '100.49' - '5.0' asks: type: array description: List of ask levels [price, quantity] items: type: array items: type: string minItems: 2 maxItems: 2 example: - - '100.51' - '8.2' - - '100.52' - '12.0' Error: type: object description: Error response required: - code - msg properties: code: type: integer description: Error code example: -1102 msg: type: string description: Error message example: Mandatory parameter 'symbol' was not sent. ````