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

# Get orderbook

> Read the orderbook for a league or game (v2, recommended)

Returns the orderbook for a league or single game in **flat** form: each market is an array of orders rather than an object keyed by spread / total.

This is the recommended orderbook endpoint. Pair it with the [WebSocket Streaming](/pages/streaming/price-feed) price feed for real-time updates.

## Request

`GET /exchange/v2/getOrderbook`

<ParamField query="league" type="string">
  League code, e.g. `NBA` (case-insensitive). Required when `gameID` is not provided.
</ParamField>

<ParamField query="sport" type="string">
  Sport name, e.g. `basketball` (case-insensitive). Optional filter when `league` is set.
</ParamField>

<ParamField query="gameID" type="string">
  Single game id. When provided, `league` and `sport` are ignored.
</ParamField>

<CodeGroup>
  ```bash curl (one league) theme={null}
  curl "https://api.4casters.io/exchange/v2/getOrderbook?league=NBA" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```bash curl (one game) theme={null}
  curl "https://api.4casters.io/exchange/v2/getOrderbook?gameID=688c0516fbc14da0c202d426" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```
</CodeGroup>

## Response

<ResponseField name="data.games" type="array">
  Each `game` is the standard [Game](/pages/rest/markets/get-games#response) shape with the following additional per-market arrays:

  <Expandable title="Per-game orderbook fields">
    <ResponseField name="awayMoneylines" type="array">Resting moneyline orders backing the away team. Sorted best-price first.</ResponseField>
    <ResponseField name="homeMoneylines" type="array">Resting moneyline orders backing the home team.</ResponseField>
    <ResponseField name="awaySpreads" type="array">Resting away-side spread orders, flattened across spread numbers.</ResponseField>
    <ResponseField name="homeSpreads" type="array">Resting home-side spread orders.</ResponseField>
    <ResponseField name="over" type="array">Resting `over` orders, flattened across totals.</ResponseField>
    <ResponseField name="under" type="array">Resting `under` orders.</ResponseField>
    <ResponseField name="awayMoneylines1x2" type="array">**Soccer only.** Three-way money line orders backing the away team.</ResponseField>
    <ResponseField name="homeMoneylines1x2" type="array">**Soccer only.** Three-way money line orders backing the home team.</ResponseField>
    <ResponseField name="draw1x2" type="array">**Soccer only.** Three-way money line orders on the draw.</ResponseField>
    <ResponseField name="openInterest" type="number">Sum of `bet` across every resting order on the game.</ResponseField>
    <ResponseField name="matchedVolume" type="number">Total volume matched on this game.</ResponseField>
  </Expandable>
</ResponseField>

Each order in those arrays has the following shape:

<Snippet file="types/orderbook-order.mdx" />

### Example (trimmed)

<CodeGroup>
  ```json JSON theme={null}
  {
    "data": {
      "games": [
        {
          "id": "67aaba04c32f13ae2e8aa070",
          "league": "NBA",
          "sport": "basketball",
          "start": "2025-02-12T00:10:00.000Z",
          "ended": false,
          "live": false,
          "featured": false,
          "eventName": "TORONTO RAPTORS VS PHILADELPHIA 76ERS",
          "isSpecials": false,
          "periodName": "Full Time",
          "participants": [/* away, home */],
          "awayMoneylines": [
            {
              "id": "67ab79fc786aa2c2cfe7524f",
              "type": "moneyline",
              "sumUntaken": 1151.04,
              "odds": 330,
              "bet": 3798.43,
              "gameID": "67aaba04c32f13ae2e8aa070",
              "takenRatio": 0,
              "participantID": "61a3917a8afa5950306490fd",
              "expiry": "2025-02-12T00:10:06.000Z",
              "createdAt": "2025-02-11T16:25:32.354Z",
              "gameStartExpiry": true
            }
          ],
          "homeMoneylines": [/* ... */],
          "awaySpreads":    [/* ... */],
          "homeSpreads":    [/* ... */],
          "over":           [/* ... */],
          "under":          [/* ... */],
          "openInterest": 12450.30,
          "matchedVolume": 27916.55
        }
      ]
    }
  }
  ```
</CodeGroup>


## OpenAPI

````yaml GET /exchange/v2/getOrderbook
openapi: 3.1.0
info:
  title: 4casters REST API
  version: 1.0.0
  description: >-
    Public REST API for the 4casters peer-to-peer betting exchange. Use this API
    to manage your account, query the orderbook and games, and place / edit /
    cancel orders.


    All responses (unless noted otherwise) are JSON envelopes of the form `{
    "data": ... }`.
  contact:
    name: 4casters
    url: https://4casters.io
servers:
  - url: https://api.4casters.io
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Authentication
    description: Login and account session management
  - name: User
    description: Read account info, bets, and orders
  - name: Orders
    description: Place, edit, look up, and cancel orders
  - name: Markets
    description: Browse leagues, games, participants, and orderbooks
  - name: Affiliate
    description: Affiliate / referral commission
paths:
  /exchange/v2/getOrderbook:
    get:
      tags:
        - Markets
      summary: Get orderbook (v2)
      description: >-
        Return the orderbook for a league or single game in **flat** form: each
        market is an array of orders rather than an object keyed by spread /
        total. This is the recommended orderbook endpoint.


        Provide either `league` (entire league) or `gameID` (one game).
      parameters:
        - name: league
          in: query
          required: false
          schema:
            type: string
          description: League code, e.g. `NBA` (case-insensitive).
        - name: sport
          in: query
          required: false
          schema:
            type: string
          description: >-
            Sport name, e.g. `basketball` (case-insensitive). Optional filter
            when `league` is set.
        - name: gameID
          in: query
          required: false
          schema:
            type: string
          description: Single game id. When provided, `league` and `sport` are ignored.
      responses:
        '200':
          description: Orderbook for one or more games
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      games:
                        type: array
                        items:
                          $ref: '#/components/schemas/GameOrderbookFlat'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    GameOrderbookFlat:
      allOf:
        - $ref: '#/components/schemas/Game'
        - type: object
          description: >-
            v2 orderbook: per-market arrays of orders (totals and spreads are
            flattened).
          properties:
            homeMoneylines:
              type: array
              items:
                $ref: '#/components/schemas/OrderbookOrder'
            awayMoneylines:
              type: array
              items:
                $ref: '#/components/schemas/OrderbookOrder'
            homeSpreads:
              type: array
              items:
                $ref: '#/components/schemas/OrderbookOrder'
            awaySpreads:
              type: array
              items:
                $ref: '#/components/schemas/OrderbookOrder'
            over:
              type: array
              items:
                $ref: '#/components/schemas/OrderbookOrder'
            under:
              type: array
              items:
                $ref: '#/components/schemas/OrderbookOrder'
            homeMoneylines1x2:
              type: array
              items:
                $ref: '#/components/schemas/OrderbookOrder'
              description: Soccer only.
            awayMoneylines1x2:
              type: array
              items:
                $ref: '#/components/schemas/OrderbookOrder'
              description: Soccer only.
            draw1x2:
              type: array
              items:
                $ref: '#/components/schemas/OrderbookOrder'
              description: Soccer only.
            openInterest:
              type: number
            matchedVolume:
              type: number
    Game:
      type: object
      description: Game without orderbook data.
      properties:
        id:
          type: string
        parentGameID:
          type: string
          nullable: true
        cheapDataUID:
          type: string
          description: >-
            Stable cross-system identifier for the game (used for line
            correlation).
        league:
          type: string
        sport:
          type: string
        start:
          type: string
          format: date-time
        ended:
          type: boolean
        live:
          type: boolean
        featured:
          type: boolean
        eventName:
          type: string
          nullable: true
        tournamentName:
          type: string
          nullable: true
        periodName:
          type: string
          description: e.g. `Full Time`, `1H`, `Set 1`.
        isSpecials:
          type: boolean
          description: True for futures and other specials markets.
        participants:
          type: array
          items:
            $ref: '#/components/schemas/Participant'
    OrderbookOrder:
      type: object
      description: A single resting order on the book.
      properties:
        id:
          type: string
        type:
          $ref: '#/components/schemas/MarketType'
        createdBy:
          type: string
          description: Present **only** when the order belongs to the caller.
        sumUntaken:
          type: number
          description: Win amount still available (taker pays risk to claim it).
        odds:
          type: integer
          description: American odds.
        bet:
          type: number
          description: Original `bet` amount.
        gameID:
          type: string
        takenRatio:
          type: number
          nullable: true
          description: Fraction of the order that has been matched.
        expiry:
          type: string
          format: date-time
          nullable: true
        createdAt:
          type: string
          format: date-time
        mockOrder:
          type: boolean
        gameStartExpiry:
          type: boolean
          description: True when the order is set to auto-cancel at game start.
        isPostArb:
          type: boolean
          description: 'Present when the order was placed with `orderType: postArb`.'
        participantID:
          type: string
          description: Present for `moneyline` and `spread`.
        spread:
          type: number
          description: Present for `spread`.
        total:
          type: number
          description: Present for `total`.
        OU:
          type: string
          enum:
            - over
            - under
          description: Present for `total`.
        market:
          type: string
          description: Present for `moneyline1x2`.
        side:
          type: string
          enum:
            - 'yes'
            - 'no'
          description: Present for `moneyline1x2`.
    Participant:
      type: object
      properties:
        id:
          type: string
        longName:
          type: string
        shortName:
          type: string
        homeAway:
          type: string
          enum:
            - home
            - away
        mainPitcher:
          type: string
          nullable: true
        rotationNumber:
          type: string
          nullable: true
        futuresSide:
          type: string
          nullable: true
        score:
          type: number
          description: Final score; only present for ended games.
    MarketType:
      type: string
      enum:
        - moneyline
        - spread
        - total
        - moneyline1x2
      description: >-
        Market type. `moneyline1x2` is **soccer-only** (three-way money line:
        home / away / draw).
  responses:
    Unauthorized:
      description: Missing or invalid auth token
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Pass your auth token in the `Authorization` header. The `Bearer` prefix
        is optional; the server also accepts a signed `auth` cookie or a `token`
        field in the request body.

````