> ## 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 user order events > Lightweight endpoint designed for market makers. Returns order-related events only: `order-created`, `order-canceled`, and `trade`. Events are sorted by `blockTimestamp` in descending order. Cursoring guidance for high-volume market makers: - use timestamp windows (`fromTimestamp`, `toTimestamp`) as the primary cursor mechanism - persist the last processed event timestamp and query the next window using `fromTimestamp` - use `limit` only to cap payload size per request - avoid offset-based deep pagination for continuous polling on accounts with large event volume - when multiple events share the same second-level timestamp, re-query with a small overlap window and de-duplicate by (`transactionHash`, `eventType`, event-specific identifier) Timestamp validation: - `fromTimestamp` and `toTimestamp` must be non-negative integers - when both are provided, `fromTimestamp` must be strictly less than `toTimestamp` Cache behavior: - responses are cached in Redis with a 2-second TTL per unique parameter combination to minimize staleness for latency-sensitive consumers Base-denomination convention: - computed amount fields (`baseDeposited`, `baseFilled`, `basePositionValue`) are always expressed in base token terms, regardless of `isBuy` - buy orders are normalized to base-equivalent position size Response field denominations: - `size`, `orderSize`, `filledSize`, `remainingSize`, `updatedSize` — size precision units; divide by `sizePrecision` for human-readable base amount - `baseDeposited`, `baseFilled`, `basePositionValue` — raw base token units; divide by `10^decimal` (base token) for human-readable amount - `price` (order-created, order-canceled) — price precision units; divide by `pricePrecision` for human-readable price - `fillPrice` (trade) — 1e18 precision; divide by 1e18 for human-readable price - `*InUsd` fields (`baseDepositedInUsd`, `baseFilledInUsd`, `basePositionValueInUsd`) — 1e18 precision; divide by 1e18 for USD value ## OpenAPI ````yaml /kuru-exchange/openapi.yaml get /api/v3/{userAddress}/user/order-events 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/{userAddress}/user/order-events: get: tags: - User Data summary: Get user order events description: > Lightweight endpoint designed for market makers. Returns order-related events only: `order-created`, `order-canceled`, and `trade`. Events are sorted by `blockTimestamp` in descending order. Cursoring guidance for high-volume market makers: - use timestamp windows (`fromTimestamp`, `toTimestamp`) as the primary cursor mechanism - persist the last processed event timestamp and query the next window using `fromTimestamp` - use `limit` only to cap payload size per request - avoid offset-based deep pagination for continuous polling on accounts with large event volume - when multiple events share the same second-level timestamp, re-query with a small overlap window and de-duplicate by (`transactionHash`, `eventType`, event-specific identifier) Timestamp validation: - `fromTimestamp` and `toTimestamp` must be non-negative integers - when both are provided, `fromTimestamp` must be strictly less than `toTimestamp` Cache behavior: - responses are cached in Redis with a 2-second TTL per unique parameter combination to minimize staleness for latency-sensitive consumers Base-denomination convention: - computed amount fields (`baseDeposited`, `baseFilled`, `basePositionValue`) are always expressed in base token terms, regardless of `isBuy` - buy orders are normalized to base-equivalent position size Response field denominations: - `size`, `orderSize`, `filledSize`, `remainingSize`, `updatedSize` — size precision units; divide by `sizePrecision` for human-readable base amount - `baseDeposited`, `baseFilled`, `basePositionValue` — raw base token units; divide by `10^decimal` (base token) for human-readable amount - `price` (order-created, order-canceled) — price precision units; divide by `pricePrecision` for human-readable price - `fillPrice` (trade) — 1e18 precision; divide by 1e18 for human-readable price - `*InUsd` fields (`baseDepositedInUsd`, `baseFilledInUsd`, `basePositionValueInUsd`) — 1e18 precision; divide by 1e18 for USD value operationId: getUserOrderEvents parameters: - name: userAddress in: path required: true description: Ethereum address of the user (case-insensitive) schema: type: string example: 0xabc123... - name: limit in: query required: false description: >- Maximum number of events to return in this window (payload cap, not a cursor) schema: type: integer default: 100 minimum: 1 example: 50 - name: offset in: query required: false description: >- Number of events to skip (legacy pagination; not recommended for high-volume market-maker polling) deprecated: true schema: type: integer default: 0 minimum: 0 example: 0 - name: marketAddress in: query required: false description: Filter to a specific market contract address schema: type: string example: 0x111... - name: fromTimestamp in: query required: false description: >- Unix epoch in seconds; include events at or after this time (recommended cursor start) schema: type: integer minimum: 0 example: 1706400000 - name: toTimestamp in: query required: false description: >- Unix epoch in seconds; include events at or before this time (recommended cursor end) schema: type: integer minimum: 0 example: 1706486400 - name: eventType in: query required: false description: Filter to a single event type schema: type: string enum: - order-created - order-canceled - trade example: trade responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/UserOrderEventsResponse' example: data: data: - eventType: trade transactionHash: 0xdef456... blockTimestamp: '2024-01-28T12:00:00.000Z' eventData: orderId: 0xabc... marketAddress: 0x111... marketId: 3 owner: 0xabc123... orderSize: '1000000000000000000' filledSize: '500000000000000000' fillPrice: '49998000000000000000000' updatedSize: '500000000000000000' isBuy: false sizePrecision: '1000000000000000000' pricePrecision: '10000' baseFilled: '500000000000000000' baseFilledInUsd: '24999000000000000000000' baseToken: address: 0x... name: Chog symbol: CHOG decimal: 18 logoUrl: https://... quoteToken: address: 0x... name: USD Coin symbol: USDC decimal: 6 logoUrl: https://... pagination: total: 1 page: 1 pageSize: 50 '400': description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/UserOrderEventsError' example: error: >- Invalid eventType: "swap". Must be one of: order-created, order-canceled, trade '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/UserOrderEventsError' example: error: Internal database or server error servers: - url: https://api.kuru.io description: Dedicated user events API server components: schemas: UserOrderEventsResponse: type: object required: - data properties: data: $ref: '#/components/schemas/UserOrderEventsData' UserOrderEventsError: type: object required: - error properties: error: type: string example: >- Invalid eventType: "swap". Must be one of: order-created, order-canceled, trade UserOrderEventsData: type: object required: - data - pagination properties: data: type: array items: $ref: '#/components/schemas/UserOrderEvent' pagination: $ref: '#/components/schemas/UserOrderEventsPagination' UserOrderEvent: type: object required: - eventType - transactionHash - blockTimestamp - eventData properties: eventType: type: string enum: - order-created - order-canceled - trade transactionHash: type: string example: 0xdef456... blockTimestamp: type: string format: date-time example: '2024-01-28T12:00:00.000Z' eventData: oneOf: - $ref: '#/components/schemas/OrderCreatedEventData' - $ref: '#/components/schemas/OrderCanceledEventData' - $ref: '#/components/schemas/TradeOrderEventData' UserOrderEventsPagination: type: object required: - total - page - pageSize properties: total: type: integer description: Number of events returned in this page example: 12 page: type: integer example: 1 pageSize: type: integer example: 100 OrderCreatedEventData: type: object required: - orderId - marketAddress - marketId - owner - size - price - isBuy - remainingSize - sizePrecision - pricePrecision - baseDeposited - baseDepositedInUsd - baseToken - quoteToken properties: orderId: type: string marketAddress: type: string marketId: type: integer owner: type: string size: type: string description: Size precision units price: type: string description: Price precision units isBuy: type: boolean remainingSize: type: string description: Size precision units sizePrecision: type: string pricePrecision: type: string baseDeposited: type: string description: Raw base token units baseDepositedInUsd: type: string description: 1e18 precision USD value baseToken: $ref: '#/components/schemas/TokenInfo' quoteToken: $ref: '#/components/schemas/TokenInfo' OrderCanceledEventData: type: object required: - orderId - marketAddress - marketId - owner - size - price - isBuy - remainingSize - sizePrecision - pricePrecision - basePositionValue - basePositionValueInUsd - baseToken - quoteToken properties: orderId: type: string marketAddress: type: string marketId: type: integer owner: type: string size: type: string description: Size precision units price: type: string description: Price precision units isBuy: type: boolean remainingSize: type: string description: Size precision units sizePrecision: type: string pricePrecision: type: string basePositionValue: type: string description: Raw base token units basePositionValueInUsd: type: string description: 1e18 precision USD value baseToken: $ref: '#/components/schemas/TokenInfo' quoteToken: $ref: '#/components/schemas/TokenInfo' TradeOrderEventData: type: object required: - orderId - marketAddress - marketId - owner - orderSize - filledSize - fillPrice - updatedSize - isBuy - sizePrecision - pricePrecision - baseFilled - baseFilledInUsd - baseToken - quoteToken properties: orderId: type: string marketAddress: type: string marketId: type: integer owner: type: string orderSize: type: string description: Size precision units filledSize: type: string description: Size precision units fillPrice: type: string description: 1e18 precision price updatedSize: type: string description: Size precision units isBuy: type: boolean sizePrecision: type: string pricePrecision: type: string baseFilled: type: string description: Raw base token units baseFilledInUsd: type: string description: 1e18 precision USD value baseToken: $ref: '#/components/schemas/TokenInfo' quoteToken: $ref: '#/components/schemas/TokenInfo' TokenInfo: type: object description: Token metadata included in event payloads required: - address - name - symbol - decimal - logoUrl properties: address: type: string description: Token contract address example: 0x... name: type: string description: Token name example: USD Coin symbol: type: string description: Token ticker symbol example: USDC decimal: type: integer description: Token decimal places example: 6 logoUrl: type: string description: URL of the token logo example: https://... ````