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

# Get Orderbook

> Retrieve the current orderbook for a trading pair

## Overview

Get the current orderbook (market depth) for a specific trading pair. This endpoint does not require authentication.

## Path Parameters

<ParamField path="symbol" type="string" required>
  Trading pair symbol

  **Example:** `USDT-NGN`

  **Allowed values:** `USDT-NGN`, `USDC-NGN`, `USD-NGN`
</ParamField>

## Query Parameters

<ParamField query="depth" type="integer">
  Number of price levels to return

  **Default:** `20`

  **Range:** `1` to `100`
</ParamField>

## Request Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api.pro.daya.co/public/v1/orderbook/USDT-NGN?depth=10'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.pro.daya.co/public/v1/orderbook/USDT-NGN?depth=10'
  );
  const orderbook = await response.json();
  console.log('Best bid:', orderbook.data.stats.best_bid);
  console.log('Best ask:', orderbook.data.stats.best_ask);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.pro.daya.co/public/v1/orderbook/USDT-NGN',
      params={'depth': 10}
  )
  orderbook = response.json()
  print(f"Best bid: {orderbook['data']['stats']['best_bid']}")
  print(f"Best ask: {orderbook['data']['stats']['best_ask']}")
  ```

  ```go Go theme={null}
  package main

  import (
      "encoding/json"
      "fmt"
      "net/http"
  )

  func main() {
      resp, err := http.Get("https://api.pro.daya.co/public/v1/orderbook/USDT-NGN?depth=10")
      if err != nil {
          panic(err)
      }
      defer resp.Body.Close()

      var result map[string]interface{}
      json.NewDecoder(resp.Body).Decode(&result)

      data := result["data"].(map[string]interface{})
      stats := data["stats"].(map[string]interface{})
      fmt.Println("Best bid:", stats["best_bid"])
      fmt.Println("Best ask:", stats["best_ask"])
  }
  ```
</CodeGroup>

## Response

<ResponseField name="success" type="boolean" required>
  Indicates if the request was successful
</ResponseField>

<ResponseField name="message" type="string" required>
  Human-readable response message
</ResponseField>

<ResponseField name="data" type="object" required>
  Orderbook data

  <Expandable title="data properties">
    <ResponseField name="symbol" type="string">
      Trading pair symbol
    </ResponseField>

    <ResponseField name="market_id" type="string">
      Market ID (UUID)
    </ResponseField>

    <ResponseField name="base_asset" type="string">
      Base asset of the pair
    </ResponseField>

    <ResponseField name="quote_asset" type="string">
      Quote asset of the pair
    </ResponseField>

    <ResponseField name="bids" type="array">
      Buy orders sorted by price (highest first)

      <Expandable title="bid properties">
        <ResponseField name="price" type="string">
          Bid price
        </ResponseField>

        <ResponseField name="quantity" type="string">
          Total quantity at this price level
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="asks" type="array">
      Sell orders sorted by price (lowest first)

      <Expandable title="ask properties">
        <ResponseField name="price" type="string">
          Ask price
        </ResponseField>

        <ResponseField name="quantity" type="string">
          Total quantity at this price level
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="stats" type="object">
      Orderbook statistics

      <Expandable title="stats properties">
        <ResponseField name="best_bid" type="string">
          Best (highest) bid price
        </ResponseField>

        <ResponseField name="best_ask" type="string">
          Best (lowest) ask price
        </ResponseField>

        <ResponseField name="spread" type="string">
          Spread between best bid and ask
        </ResponseField>

        <ResponseField name="spread_percent" type="string">
          Spread as percentage
        </ResponseField>

        <ResponseField name="mid_price" type="string">
          Mid price between best bid and ask
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="depth" type="integer">
      Orderbook depth returned
    </ResponseField>

    <ResponseField name="timestamp" type="string">
      ISO 8601 timestamp of the snapshot
    </ResponseField>
  </Expandable>
</ResponseField>

### Success Response

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "success": true,
    "message": "Orderbook retrieved successfully",
    "data": {
      "symbol": "USD-NGN",
      "market_id": "550e8400-e29b-41d4-a716-446655440000",
      "base_asset": "USD",
      "quote_asset": "NGN",
      "bids": [
        {"price": "1545.00", "quantity": "500.00"},
        {"price": "1544.50", "quantity": "1200.00"},
        {"price": "1544.00", "quantity": "800.00"}
      ],
      "asks": [
        {"price": "1546.00", "quantity": "800.00"},
        {"price": "1546.50", "quantity": "350.00"},
        {"price": "1547.00", "quantity": "1500.00"}
      ],
      "stats": {
        "best_bid": "1545.00",
        "best_ask": "1546.00",
        "spread": "1.00",
        "spread_percent": "0.065",
        "mid_price": "1545.50"
      },
      "depth": 10,
      "timestamp": "2024-01-15T10:30:00Z"
    }
  }
  ```
</ResponseExample>

## Error Responses

<ResponseExample>
  ```json 404 Not Found - Invalid symbol theme={null}
  {
    "success": false,
    "message": "Market not found",
    "error": {
      "code": "SYMBOL_NOT_FOUND",
      "message": "Market not found",
      "symbol": "INVALID-PAIR"
    }
  }
  ```

  ```json 400 Bad Request - Invalid depth theme={null}
  {
    "success": false,
    "message": "Validation error",
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Depth must be between 1 and 100"
    }
  }
  ```
</ResponseExample>

## Understanding the Orderbook

### Bids vs Asks

| Type     | Description                                          | Sort Order          |
| -------- | ---------------------------------------------------- | ------------------- |
| **Bids** | Buy orders - users willing to purchase at this price | Highest price first |
| **Asks** | Sell orders - users willing to sell at this price    | Lowest price first  |

### Reading the Spread

The spread is the difference between the best ask and best bid:

```
Spread = Best Ask - Best Bid
Spread % = (Spread / Mid Price) × 100
```

A tighter spread indicates higher liquidity.

## Rate Limits

* **100 requests per minute** per IP address
* No authentication required

## Next Steps

<CardGroup cols={2}>
  <Card title="Place Order" icon="arrow-right-arrow-left" href="/pro/api-reference/place-order">
    Execute a trade at current market prices
  </Card>

  <Card title="List Markets" icon="chart-line" href="/pro/api-reference/list-markets">
    View all available markets
  </Card>
</CardGroup>