openapi: 3.1.0
info:
  title: Polymarket CLOB API
  description: Polymarket CLOB API Reference
  license:
    name: MIT
    identifier: MIT
  version: 1.0.0
servers:
  - url: https://clob.polymarket.com
    description: Production CLOB API
  - url: https://clob-staging.polymarket.com
    description: Staging CLOB API
tags:
  - name: Trade
    description: Trade endpoints
  - name: Markets
    description: Market data endpoints
  - name: Account
    description: Account and authentication endpoints
  - name: Notifications
    description: User notification endpoints
  - name: Rewards
    description: Rewards and earnings endpoints
  - name: Rebates
    description: Maker rebate endpoints
paths:
  /order:
    post:
      summary: Post a new order
      description: |
        Creates a new order in the order book
      operationId: postOrder
      tags:
        - Trade
      security:
        - polyApiKey: []
          polyAddress: []
          polySignature: []
          polyPassphrase: []
          polyTimestamp: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendOrder'
            examples:
              example:
                summary: Send order example
                value:
                  order:
                    maker: '0x1234567890123456789012345678901234567890'
                    signer: '0x1234567890123456789012345678901234567890'
                    tokenId: 0xabc123def456...
                    makerAmount: '100000000'
                    takerAmount: '200000000'
                    side: BUY
                    expiration: '1735689600'
                    timestamp: '1735689600000'
                    metadata: ''
                    builder: >-
                      0x0000000000000000000000000000000000000000000000000000000000000000
                    signature: 0x1234abcd...
                    salt: 1234567890
                    signatureType: 0
                  owner: f4f247b7-4ac7-ff29-a152-04fda0a8755a
                  orderType: GTC
                  deferExec: false
                  postOnly: false
      responses:
        '200':
          description: Order successfully processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendOrderResponse'
              examples:
                live_order:
                  summary: Order placed on book
                  value:
                    success: true
                    orderID: '0xabcdef1234567890abcdef1234567890abcdef12'
                    status: live
                    makingAmount: '100000000'
                    takingAmount: '200000000'
                    errorMsg: ''
                matched_order:
                  summary: Order immediately matched
                  value:
                    success: true
                    orderID: '0xabcdef1234567890abcdef1234567890abcdef12'
                    status: matched
                    makingAmount: '100000000'
                    takingAmount: '200000000'
                    transactionsHashes:
                      - '0x1234567890abcdef1234567890abcdef12345678'
                    tradeIDs:
                      - trade-123
                    errorMsg: ''
                delayed_order:
                  summary: Order delayed
                  value:
                    success: true
                    orderID: '0xabcdef1234567890abcdef1234567890abcdef12'
                    status: delayed
                    makingAmount: '100000000'
                    takingAmount: '200000000'
                    errorMsg: ''
        '400':
          description: Bad request - Invalid order payload or validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_payload:
                  summary: Invalid order payload
                  value:
                    error: Invalid order payload
                owner_mismatch:
                  summary: Owner mismatch
                  value:
                    error: the order owner has to be the owner of the API KEY
                signer_mismatch:
                  summary: Signer mismatch
                  value:
                    error: >-
                      the order signer address has to be the address of the API
                      KEY
                banned_address:
                  summary: Banned address
                  value:
                    error: '''0x1234...'' address banned'
                closed_only_mode:
                  summary: Closed only mode violation
                  value:
                    error: '''0x1234...'' address in closed only mode'
                invalid_order:
                  summary: Invalid order details
                  value:
                    error: >-
                      order 0xabc... is invalid. Price (100) breaks minimum tick
                      size rule: 0.1
        '401':
          description: Unauthorized - Invalid API key or authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid API key
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: could not insert order
        '503':
          description: Service unavailable - Trading disabled or cancel-only mode
          headers:
            Retry-After:
              description: Seconds to wait before retrying when provided by post-only mode.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                trading_disabled:
                  summary: Trading disabled
                  value:
                    error: >-
                      Trading is currently disabled. Check polymarket.com for
                      updates
                cancel_only:
                  summary: Cancel-only mode
                  value:
                    error: >-
                      Trading is currently cancel-only. New orders are not
                      accepted, but cancels are allowed.
                post_only_mode:
                  summary: Post-only mode
                  value:
                    error: >-
                      post-only mode: only post-only orders and cancels are
                      allowed
                    code: post_only_mode
                    retry_after_seconds: 79
    delete:
      summary: Cancel single order
      description: |
        Cancels a single order by its ID. Works even in cancel-only mode.
      operationId: cancelOrder
      tags:
        - Trade
      security:
        - polyApiKey: []
          polyAddress: []
          polySignature: []
          polyPassphrase: []
          polyTimestamp: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelOrderPayload'
            example:
              orderID: '0xabcdef1234567890abcdef1234567890abcdef12'
      responses:
        '200':
          description: Order cancellation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelOrdersResponse'
              examples:
                canceled:
                  summary: Order successfully canceled
                  value:
                    canceled:
                      - '0xabcdef1234567890abcdef1234567890abcdef12'
                    not_canceled: {}
                not_canceled:
                  summary: Order could not be canceled
                  value:
                    canceled: []
                    not_canceled:
                      '0xabcdef1234567890abcdef1234567890abcdef12': Order not found or already canceled
        '400':
          description: Bad request - Invalid order ID or payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_order_id:
                  summary: Invalid order ID
                  value:
                    error: Invalid orderID
                invalid_payload:
                  summary: Invalid payload
                  value:
                    error: Invalid order payload
        '401':
          description: Unauthorized - Invalid API key or authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid API key
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
        '503':
          description: >-
            Service unavailable - Trading disabled (cancels still work in
            cancel-only mode)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: >-
                  Trading is currently disabled. Check polymarket.com for
                  updates
  /orders:
    post:
      summary: Post multiple orders
      description: >
        Creates multiple new orders in the order book. Orders are processed in
        parallel.

        Maximum 15 orders per request.
      operationId: postOrders
      tags:
        - Trade
      security:
        - polyApiKey: []
          polyAddress: []
          polySignature: []
          polyPassphrase: []
          polyTimestamp: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/SendOrder'
              maxItems: 15
            examples:
              example:
                summary: Send multiple orders example
                value:
                  - order:
                      maker: '0x1234567890123456789012345678901234567890'
                      signer: '0x1234567890123456789012345678901234567890'
                      tokenId: 0xabc123def456...
                      makerAmount: '100000000'
                      takerAmount: '200000000'
                      side: BUY
                      expiration: '1735689600'
                      timestamp: '1735689600000'
                      metadata: ''
                      builder: >-
                        0x0000000000000000000000000000000000000000000000000000000000000000
                      signature: 0x1234abcd...
                      salt: 1234567890
                      signatureType: 0
                    owner: f4f247b7-4ac7-ff29-a152-04fda0a8755a
                    orderType: GTC
                    deferExec: false
                    postOnly: false
                  - order:
                      maker: '0x1234567890123456789012345678901234567890'
                      signer: '0x1234567890123456789012345678901234567890'
                      tokenId: 0xdef456abc789...
                      makerAmount: '200000000'
                      takerAmount: '100000000'
                      side: SELL
                      expiration: '1735689600'
                      timestamp: '1735689600000'
                      metadata: ''
                      builder: >-
                        0x0000000000000000000000000000000000000000000000000000000000000000
                      signature: 0x5678efgh...
                      salt: 1234567891
                      signatureType: 0
                    owner: f4f247b7-4ac7-ff29-a152-04fda0a8755a
                    orderType: GTC
                    deferExec: false
                    postOnly: false
      responses:
        '200':
          description: >-
            Orders successfully processed. Returns an array of order responses,
            one for each order in the request.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SendOrderResponse'
              examples:
                mixed_results:
                  summary: Mixed order results
                  value:
                    - success: true
                      orderID: '0xabcdef1234567890abcdef1234567890abcdef12'
                      status: live
                      makingAmount: '100000000'
                      takingAmount: '200000000'
                      errorMsg: ''
                    - success: true
                      orderID: '0xfedcba0987654321fedcba0987654321fedcba09'
                      status: matched
                      makingAmount: '200000000'
                      takingAmount: '100000000'
                      transactionsHashes:
                        - '0x1234567890abcdef1234567890abcdef12345678'
                      tradeIDs:
                        - trade-123
                      errorMsg: ''
                    - success: false
                      orderID: ''
                      status: delayed
                      errorMsg: 'Rate limit exceeded for tokenId: 0xdef456abc789...'
                post_only_mode:
                  summary: Post-only mode results
                  value:
                    - errorMsg: >-
                        post-only mode: only post-only orders and cancels are
                        allowed
                      orderID: ''
                      takingAmount: ''
                      makingAmount: ''
                      status: ''
                      success: true
                    - errorMsg: >-
                        post-only mode: only post-only orders and cancels are
                        allowed
                      orderID: ''
                      takingAmount: ''
                      makingAmount: ''
                      status: ''
                      success: true
        '400':
          description: Bad request - Invalid order payload or validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_payload:
                  summary: Invalid order payload
                  value:
                    error: Invalid order payload
                empty_payload:
                  summary: Empty orders array
                  value:
                    error: Invalid order payload
                too_many_orders:
                  summary: Too many orders
                  value:
                    error: 'Too many orders in payload: 20, max allowed: 15'
                owner_mismatch:
                  summary: Owner mismatch
                  value:
                    error: the order owner has to be the owner of the API KEY
                signer_mismatch:
                  summary: Signer mismatch
                  value:
                    error: >-
                      the order signer address has to be the address of the API
                      KEY
                banned_address:
                  summary: Banned address
                  value:
                    error: '''0x1234...'' address banned'
                closed_only_mode:
                  summary: Closed only mode violation
                  value:
                    error: '''0x1234...'' address in closed only mode'
        '401':
          description: Unauthorized - Invalid API key or authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid API key
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: could not insert order
        '503':
          description: Service unavailable - Trading disabled or cancel-only mode
          headers:
            Retry-After:
              description: Seconds to wait before retrying when provided by post-only mode.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                trading_disabled:
                  summary: Trading disabled
                  value:
                    error: >-
                      Trading is currently disabled. Check polymarket.com for
                      updates
                cancel_only:
                  summary: Cancel-only mode
                  value:
                    error: >-
                      Trading is currently cancel-only. New orders are not
                      accepted, but cancels are allowed.
                post_only_mode:
                  summary: Post-only mode
                  value:
                    error: >-
                      post-only mode: only post-only orders and cancels are
                      allowed
                    code: post_only_mode
                    retry_after_seconds: 79
    delete:
      summary: Cancel multiple orders
      description: |
        Cancels multiple orders by their IDs. Maximum 1000 orders per request.
        Duplicate order IDs in the request are automatically ignored.
        Works even in cancel-only mode.
      operationId: cancelOrders
      tags:
        - Trade
      security:
        - polyApiKey: []
          polyAddress: []
          polySignature: []
          polyPassphrase: []
          polyTimestamp: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
              maxItems: 1000
            example:
              - '0xabcdef1234567890abcdef1234567890abcdef12'
              - '0xfedcba0987654321fedcba0987654321fedcba09'
              - '0x1234567890abcdef1234567890abcdef12345678'
      responses:
        '200':
          description: Cancellation results for all orders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelOrdersResponse'
              examples:
                all_canceled:
                  summary: All orders canceled
                  value:
                    canceled:
                      - '0xabcdef1234567890abcdef1234567890abcdef12'
                      - '0xfedcba0987654321fedcba0987654321fedcba09'
                      - '0x1234567890abcdef1234567890abcdef12345678'
                    not_canceled: {}
                mixed:
                  summary: Some orders canceled, some not
                  value:
                    canceled:
                      - '0xabcdef1234567890abcdef1234567890abcdef12'
                      - '0xfedcba0987654321fedcba0987654321fedcba09'
                    not_canceled:
                      '0x1234567890abcdef1234567890abcdef12345678': Order already matched
                partial:
                  summary: Partial cancellation
                  value:
                    canceled:
                      - '0xabcdef1234567890abcdef1234567890abcdef12'
                    not_canceled:
                      '0xfedcba0987654321fedcba0987654321fedcba09': Order not found
                      '0x1234567890abcdef1234567890abcdef12345678': Order already canceled
        '400':
          description: Bad request - Invalid order IDs or payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_order_id:
                  summary: Invalid order ID
                  value:
                    error: Invalid orderID
                invalid_payload:
                  summary: Invalid payload
                  value:
                    error: Invalid order payload
                too_many_orders:
                  summary: Too many orders
                  value:
                    error: 'Too many orders in payload, max allowed: 1000'
        '401':
          description: Unauthorized - Invalid API key or authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid API key
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
        '503':
          description: >-
            Service unavailable - Trading disabled (cancels still work in
            cancel-only mode)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: >-
                  Trading is currently disabled. Check polymarket.com for
                  updates
  /data/orders:
    get:
      summary: Get user orders
      description: >
        Retrieves open orders for the authenticated user. Returns paginated
        results.

        Builder-authenticated clients can also use this endpoint to retrieve
        orders attributed to their builder account.
      operationId: getOrders
      tags:
        - Trade
      security:
        - polyApiKey: []
          polyAddress: []
          polySignature: []
          polyPassphrase: []
          polyTimestamp: []
      parameters:
        - name: id
          in: query
          description: Order ID (hash) to filter by specific order
          required: false
          schema:
            type: string
          example: '0xabcdef1234567890abcdef1234567890abcdef12'
        - name: market
          in: query
          description: Market (condition ID) to filter orders
          required: false
          schema:
            type: string
          example: '0x0000000000000000000000000000000000000000000000000000000000000001'
        - name: asset_id
          in: query
          description: Asset ID (token ID) to filter orders
          required: false
          schema:
            type: string
          example: 0xabc123def456...
        - name: next_cursor
          in: query
          description: Cursor for pagination (base64 encoded offset)
          required: false
          schema:
            type: string
          example: MA==
      responses:
        '200':
          description: Successfully retrieved orders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrdersResponse'
              examples:
                example:
                  summary: User orders response
                  value:
                    limit: 100
                    next_cursor: MTAw
                    count: 2
                    data:
                      - id: '0xabcdef1234567890abcdef1234567890abcdef12'
                        status: ORDER_STATUS_LIVE
                        owner: f4f247b7-4ac7-ff29-a152-04fda0a8755a
                        maker_address: '0x1234567890123456789012345678901234567890'
                        market: >-
                          0x0000000000000000000000000000000000000000000000000000000000000001
                        asset_id: 0xabc123def456...
                        side: BUY
                        original_size: '100000000'
                        size_matched: '0'
                        price: '0.5'
                        outcome: 'YES'
                        expiration: '1735689600'
                        order_type: GTC
                        associate_trades: []
                        created_at: 1700000000
                      - id: '0xfedcba0987654321fedcba0987654321fedcba09'
                        status: ORDER_STATUS_LIVE
                        owner: f4f247b7-4ac7-ff29-a152-04fda0a8755a
                        maker_address: '0x1234567890123456789012345678901234567890'
                        market: >-
                          0x0000000000000000000000000000000000000000000000000000000000000002
                        asset_id: 0xdef456abc789...
                        side: SELL
                        original_size: '200000000'
                        size_matched: '50000000'
                        price: '0.75'
                        outcome: 'NO'
                        expiration: '1735689600'
                        order_type: GTC
                        associate_trades:
                          - trade-123
                        created_at: 1700000001
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: invalid order params payload
        '401':
          description: Unauthorized - Invalid API key or authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid API key
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
  /data/order/{orderID}:
    get:
      summary: Get single order by ID
      description: >
        Retrieves a specific order by its ID (order hash) for the authenticated
        user.

        Builder-authenticated clients can also use this endpoint to retrieve
        orders attributed to their builder account.
      operationId: getOrder
      tags:
        - Trade
      security:
        - polyApiKey: []
          polyAddress: []
          polySignature: []
          polyPassphrase: []
          polyTimestamp: []
      parameters:
        - name: orderID
          in: path
          description: Order ID (order hash)
          required: true
          schema:
            type: string
          example: '0x0000000000000000000000000000000000000000000000000000000000000001'
      responses:
        '200':
          description: Successfully retrieved order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenOrder'
              example:
                id: '0xabcdef1234567890abcdef1234567890abcdef12'
                status: ORDER_STATUS_LIVE
                owner: f4f247b7-4ac7-ff29-a152-04fda0a8755a
                maker_address: '0x1234567890123456789012345678901234567890'
                market: >-
                  0x0000000000000000000000000000000000000000000000000000000000000001
                asset_id: 0xabc123def456...
                side: BUY
                original_size: '100000000'
                size_matched: '0'
                price: '0.5'
                outcome: 'YES'
                expiration: '1735689600'
                order_type: GTC
                associate_trades: []
                created_at: 1700000000
        '400':
          description: Bad request - Invalid order ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid orderID
        '401':
          description: Unauthorized - Invalid API key or authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid API key
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Order not found
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
  /cancel-all:
    delete:
      summary: Cancel all orders
      description: >
        Cancels all open orders for the authenticated user. Works even in
        cancel-only mode.
      operationId: cancelAllOrders
      tags:
        - Trade
      security:
        - polyApiKey: []
          polyAddress: []
          polySignature: []
          polyPassphrase: []
          polyTimestamp: []
      responses:
        '200':
          description: Cancellation results for all orders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelOrdersResponse'
              examples:
                canceled:
                  summary: All orders canceled
                  value:
                    canceled:
                      - '0xabcdef1234567890abcdef1234567890abcdef12'
                      - '0xfedcba0987654321fedcba0987654321fedcba09'
                    not_canceled: {}
                mixed:
                  summary: Some orders canceled, some not
                  value:
                    canceled:
                      - '0xabcdef1234567890abcdef1234567890abcdef12'
                    not_canceled:
                      '0xfedcba0987654321fedcba0987654321fedcba09': Order already matched
                no_orders:
                  summary: No orders to cancel
                  value:
                    canceled: []
                    not_canceled: {}
        '401':
          description: Unauthorized - Invalid API key or authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid API key
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
        '503':
          description: >-
            Service unavailable - Trading disabled (cancels still work in
            cancel-only mode)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: >-
                  Trading is currently disabled. Check polymarket.com for
                  updates
  /cancel-market-orders:
    delete:
      summary: Cancel orders for a market
      description: >
        Cancels all open orders for the authenticated user in a specific market
        (condition) and asset.

        Works even in cancel-only mode.
      operationId: cancelMarketOrders
      tags:
        - Trade
      security:
        - polyApiKey: []
          polyAddress: []
          polySignature: []
          polyPassphrase: []
          polyTimestamp: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderMarketCancelParams'
            example:
              market: >-
                0x0000000000000000000000000000000000000000000000000000000000000001
              asset_id: 0xabc123def456...
      responses:
        '200':
          description: Cancellation results for market orders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelOrdersResponse'
              examples:
                canceled:
                  summary: All market orders canceled
                  value:
                    canceled:
                      - '0xabcdef1234567890abcdef1234567890abcdef12'
                      - '0xfedcba0987654321fedcba0987654321fedcba09'
                    not_canceled: {}
                mixed:
                  summary: Some orders canceled, some not
                  value:
                    canceled:
                      - '0xabcdef1234567890abcdef1234567890abcdef12'
                    not_canceled:
                      '0xfedcba0987654321fedcba0987654321fedcba09': Order already matched
                no_orders:
                  summary: No orders found for this market
                  value:
                    canceled: []
                    not_canceled: {}
        '400':
          description: Bad request - Invalid payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid order payload
        '401':
          description: Unauthorized - Invalid API key or authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid API key
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
        '503':
          description: >-
            Service unavailable - Trading disabled (cancels still work in
            cancel-only mode)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: >-
                  Trading is currently disabled. Check polymarket.com for
                  updates
  /time:
    get:
      summary: Get server time
      description: |
        Returns the current Unix timestamp of the server.
        This can be used to synchronize client time with server time.
      operationId: getTime
      tags:
        - Data
      security: []
      responses:
        '200':
          description: Successfully retrieved server time
          content:
            application/json:
              schema:
                type: integer
                format: int64
                description: Unix timestamp (seconds since epoch)
              example: 1234567890
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /midpoint:
    get:
      summary: Get midpoint price
      description: >
        Retrieves the midpoint price for a specific token ID.

        The midpoint is calculated as the average of the best bid and best ask
        prices.
      operationId: getMidpoint
      tags:
        - Data
      security: []
      parameters:
        - name: token_id
          in: query
          description: Token ID (asset ID)
          required: true
          schema:
            type: string
          example: 0xabc123def456...
      responses:
        '200':
          description: Successfully retrieved midpoint price
          content:
            application/json:
              schema:
                type: object
                required:
                  - mid_price
                properties:
                  mid_price:
                    type: string
                    description: Midpoint price as a string
                    example: '0.45'
        '400':
          description: Bad request - Invalid token id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid token id
        '404':
          description: Not found - No orderbook exists for the requested token id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: No orderbook exists for the requested token id
  /midpoints:
    get:
      summary: Get midpoint prices (query parameters)
      description: >
        Retrieves midpoint prices for multiple token IDs using query parameters.

        The midpoint is calculated as the average of the best bid and best ask
        prices.
      operationId: getMidpointsGet
      tags:
        - Market Data
      security: []
      parameters:
        - name: token_ids
          in: query
          description: Comma-separated list of token IDs
          required: true
          schema:
            type: string
          example: 0xabc123...,0xdef456...
      responses:
        '200':
          description: Successfully retrieved midpoint prices
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
                description: Map of token ID to midpoint price
              example:
                0xabc123def456...: '0.45'
                0xdef456abc123...: '0.52'
        '400':
          description: Bad request - Invalid payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid payload
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: error getting the mid price
    post:
      summary: Get midpoint prices (request body)
      security: []
      description: >
        Retrieves midpoint prices for multiple token IDs using a request body.

        The midpoint is calculated as the average of the best bid and best ask
        prices.
      operationId: getMidpointsPost
      tags:
        - Market Data
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/BookRequest'
            example:
              - token_id: 0xabc123def456...
              - token_id: 0xdef456abc123...
      responses:
        '200':
          description: Successfully retrieved midpoint prices
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
                description: Map of token ID to midpoint price
              example:
                0xabc123def456...: '0.45'
                0xdef456abc123...: '0.52'
        '400':
          description: Bad request - Invalid payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid payload
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: error getting the mid price
  /spread:
    get:
      summary: Get spread
      description: |
        Retrieves the spread for a specific token ID.
        The spread is the difference between the best ask and best bid prices.
      operationId: getSpread
      tags:
        - Market Data
      security: []
      parameters:
        - name: token_id
          in: query
          description: Token ID (asset ID)
          required: true
          schema:
            type: string
          example: 0xabc123def456...
      responses:
        '200':
          description: Successfully retrieved spread
          content:
            application/json:
              schema:
                type: object
                required:
                  - spread
                properties:
                  spread:
                    type: string
                    description: Spread as a string
                    example: '0.02'
        '400':
          description: Bad request - Invalid token id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid token id
        '404':
          description: Not found - No orderbook exists for the requested token id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: No orderbook exists for the requested token id
  /spreads:
    post:
      summary: Get spreads
      description: |
        Retrieves spreads for multiple token IDs.
        The spread is the difference between the best ask and best bid prices.
      operationId: getSpreads
      tags:
        - Market Data
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/BookRequest'
            example:
              - token_id: 0xabc123def456...
              - token_id: 0xdef456abc123...
      responses:
        '200':
          description: Successfully retrieved spreads
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
                description: Map of token ID to spread
              example:
                0xabc123def456...: '0.02'
                0xdef456abc123...: '0.015'
        '400':
          description: Bad request - Invalid payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid payload
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: error getting the spread
  /last-trade-price:
    get:
      summary: Get last trade price
      description: >
        Retrieves the last trade price and side for a specific token ID.

        Returns default values of "0.5" for price and empty string for side if
        no trades found.
      operationId: getLastTradePrice
      tags:
        - Market Data
      security: []
      parameters:
        - name: token_id
          in: query
          description: Token ID (asset ID)
          required: true
          schema:
            type: string
          example: 0xabc123def456...
      responses:
        '200':
          description: Successfully retrieved last trade price
          content:
            application/json:
              schema:
                type: object
                required:
                  - price
                  - side
                properties:
                  price:
                    type: string
                    description: Last trade price
                    example: '0.45'
                  side:
                    type: string
                    description: Last trade side (BUY or SELL)
                    enum:
                      - BUY
                      - SELL
                      - ''
                    example: BUY
        '400':
          description: Bad request - Invalid token id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid token id
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
  /last-trades-prices:
    get:
      summary: Get last trade prices (query parameters)
      description: >
        Retrieves last trade prices for multiple token IDs using query
        parameters.

        Maximum 500 token IDs can be requested per call.
      operationId: getLastTradesPricesGet
      tags:
        - Market Data
      security: []
      parameters:
        - name: token_ids
          in: query
          description: Comma-separated list of token IDs (max 500)
          required: true
          schema:
            type: string
          example: 0xabc123...,0xdef456...
      responses:
        '200':
          description: Successfully retrieved last trade prices
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  required:
                    - token_id
                    - price
                    - side
                  properties:
                    token_id:
                      type: string
                      description: Token ID (asset ID)
                      example: 0xabc123def456...
                    price:
                      type: string
                      description: Last trade price
                      example: '0.45'
                    side:
                      type: string
                      description: Last trade side (BUY or SELL)
                      enum:
                        - BUY
                        - SELL
                      example: BUY
              example:
                - token_id: 0xabc123def456...
                  price: '0.45'
                  side: BUY
                - token_id: 0xdef456abc123...
                  price: '0.52'
                  side: SELL
        '400':
          description: Bad request - Invalid payload or exceeds limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_payload:
                  summary: Invalid payload
                  value:
                    error: Invalid payload
                exceeds_limit:
                  summary: Payload exceeds limit
                  value:
                    error: Payload exceeds the limit
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
    post:
      summary: Get last trade prices (request body)
      security: []
      description: |
        Retrieves last trade prices for multiple token IDs using a request body.
        Maximum 500 token IDs can be requested per call.
      operationId: getLastTradesPricesPost
      tags:
        - Market Data
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/BookRequest'
            example:
              - token_id: 0xabc123def456...
              - token_id: 0xdef456abc123...
      responses:
        '200':
          description: Successfully retrieved last trade prices
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  required:
                    - token_id
                    - price
                    - side
                  properties:
                    token_id:
                      type: string
                      description: Token ID (asset ID)
                      example: 0xabc123def456...
                    price:
                      type: string
                      description: Last trade price
                      example: '0.45'
                    side:
                      type: string
                      description: Last trade side (BUY or SELL)
                      enum:
                        - BUY
                        - SELL
                      example: BUY
              example:
                - token_id: 0xabc123def456...
                  price: '0.45'
                  side: BUY
                - token_id: 0xdef456abc123...
                  price: '0.52'
                  side: SELL
        '400':
          description: Bad request - Invalid payload or exceeds limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_payload:
                  summary: Invalid payload
                  value:
                    error: Invalid payload
                exceeds_limit:
                  summary: Payload exceeds limit
                  value:
                    error: Payload exceeds the limit
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
  /fee-rate:
    get:
      summary: Get fee rate
      description: >
        Retrieves the base fee rate for a specific token ID.

        The fee rate can be provided either as a query parameter or as a path
        parameter.
      operationId: getFeeRate
      tags:
        - Market Data
      security: []
      parameters:
        - name: token_id
          in: query
          description: Token ID (asset ID)
          required: false
          schema:
            type: string
          example: 0xabc123def456...
      responses:
        '200':
          description: Successfully retrieved fee rate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeeRate'
              example:
                base_fee: 30
        '400':
          description: Bad request - Invalid token id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid token id
        '404':
          description: Not found - Fee rate not found for market
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: fee rate not found for market
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
  /fee-rate/{token_id}:
    get:
      summary: Get fee rate by path parameter
      description: >
        Retrieves the base fee rate for a specific token ID using the token ID
        as a path parameter.
      operationId: getFeeRateByPath
      tags:
        - Market Data
      security: []
      parameters:
        - name: token_id
          in: path
          description: Token ID (asset ID)
          required: true
          schema:
            type: string
          example: 0xabc123def456...
      responses:
        '200':
          description: Successfully retrieved fee rate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeeRate'
              example:
                base_fee: 30
        '400':
          description: Bad request - Invalid token id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid token id
        '404':
          description: Not found - Fee rate not found for market
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: fee rate not found for market
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
  /tick-size:
    get:
      summary: Get tick size
      description: >
        Retrieves the minimum tick size (price increment) for a specific token
        ID.

        The tick size can be provided either as a query parameter or as a path
        parameter.
      operationId: getTickSize
      tags:
        - Market Data
      security: []
      parameters:
        - name: token_id
          in: query
          description: Token ID (asset ID)
          required: false
          schema:
            type: string
          example: 0xabc123def456...
      responses:
        '200':
          description: Successfully retrieved tick size
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TickSize'
              example:
                minimum_tick_size: 0.01
        '400':
          description: Bad request - Invalid token id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid token id
        '404':
          description: Not found - Market not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: market not found
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
  /tick-size/{token_id}:
    get:
      summary: Get tick size by path parameter
      description: >
        Retrieves the minimum tick size (price increment) for a specific token
        ID using the token ID as a path parameter.
      operationId: getTickSizeByPath
      tags:
        - Market Data
      security: []
      parameters:
        - name: token_id
          in: path
          description: Token ID (asset ID)
          required: true
          schema:
            type: string
          example: 0xabc123def456...
      responses:
        '200':
          description: Successfully retrieved tick size
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TickSize'
              example:
                minimum_tick_size: 0.01
        '400':
          description: Bad request - Invalid token id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid token id
        '404':
          description: Not found - Market not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: market not found
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
  /neg-risk:
    get:
      summary: Get negative risk flag
      description: >
        Retrieves the negative risk flag for a specific token ID.

        The token ID can be provided either as a query parameter or as a path
        parameter.
      operationId: getNegRisk
      tags:
        - Market Data
      security: []
      parameters:
        - name: token_id
          in: query
          description: Token ID (asset ID)
          required: false
          schema:
            type: string
          example: 0xabc123def456...
      responses:
        '200':
          description: Successfully retrieved negative risk flag
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NegRisk'
              example:
                neg_risk: false
        '400':
          description: Bad request - Invalid token id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid token id
        '404':
          description: Not found - Market not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: market not found
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
  /neg-risk/{token_id}:
    get:
      summary: Get negative risk flag by path parameter
      description: >
        Retrieves the negative risk flag for a specific token ID using the token
        ID as a path parameter.
      operationId: getNegRiskByPath
      tags:
        - Market Data
      security: []
      parameters:
        - name: token_id
          in: path
          description: Token ID (asset ID)
          required: true
          schema:
            type: string
          example: 0xabc123def456...
      responses:
        '200':
          description: Successfully retrieved negative risk flag
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NegRisk'
              example:
                neg_risk: false
        '400':
          description: Bad request - Invalid token id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid token id
        '404':
          description: Not found - Market not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: market not found
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
  /price:
    get:
      summary: Get market price
      description: >
        Retrieves the best market price for a specific token ID and side (bid or
        ask).

        Returns the best bid price for BUY side or best ask price for SELL side.
      operationId: getPrice
      tags:
        - Market Data
      security: []
      parameters:
        - name: token_id
          in: query
          description: Token ID (asset ID)
          required: true
          schema:
            type: string
          example: 0xabc123def456...
        - name: side
          in: query
          description: Order side
          required: true
          schema:
            type: string
            enum:
              - BUY
              - SELL
          example: BUY
      responses:
        '200':
          description: Successfully retrieved market price
          content:
            application/json:
              schema:
                type: object
                required:
                  - price
                properties:
                  price:
                    type: number
                    format: double
                    description: Market price as a decimal number
                    example: 0.45
              example:
                price: 0.45
        '400':
          description: Bad request - Invalid token id or side
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_token_id:
                  summary: Invalid token id
                  value:
                    error: Invalid token id
                invalid_side:
                  summary: Invalid side
                  value:
                    error: Invalid side
        '404':
          description: Not found - No orderbook exists for the requested token id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: No orderbook exists for the requested token id
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
  /prices:
    get:
      summary: Get market prices (query parameters)
      description: >
        Retrieves market prices for multiple token IDs and sides using query
        parameters.
      operationId: getPricesGet
      tags:
        - Market Data
      security: []
      parameters:
        - name: token_ids
          in: query
          description: Comma-separated list of token IDs
          required: true
          schema:
            type: string
          example: 0xabc123...,0xdef456...
        - name: sides
          in: query
          description: >-
            Comma-separated list of sides (BUY or SELL) corresponding to token
            IDs
          required: true
          schema:
            type: string
          example: BUY,SELL
      responses:
        '200':
          description: Successfully retrieved market prices
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: object
                  additionalProperties:
                    type: number
                    format: double
                description: Map of token ID to map of side to price
              example:
                0xabc123def456...:
                  BUY: 0.45
                0xdef456abc123...:
                  SELL: 0.52
        '400':
          description: Bad request - Invalid payload or side
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_payload:
                  summary: Invalid payload
                  value:
                    error: Invalid payload
                invalid_side:
                  summary: Invalid side
                  value:
                    error: Invalid side
        '404':
          description: Not found - No orderbook exists for the requested token id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: No orderbook exists for the requested token id
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
    post:
      summary: Get market prices (request body)
      security: []
      description: >
        Retrieves market prices for multiple token IDs and sides using a request
        body.

        Each request must include both token_id and side.
      operationId: getPricesPost
      tags:
        - Market Data
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/BookRequest'
            example:
              - token_id: 0xabc123def456...
                side: BUY
              - token_id: 0xdef456abc123...
                side: SELL
      responses:
        '200':
          description: Successfully retrieved market prices
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: object
                  additionalProperties:
                    type: number
                    format: double
                description: Map of token ID to map of side to price
              example:
                0xabc123def456...:
                  BUY: 0.45
                0xdef456abc123...:
                  SELL: 0.52
        '400':
          description: Bad request - Invalid payload or side
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_payload:
                  summary: Invalid payload
                  value:
                    error: Invalid payload
                invalid_side:
                  summary: Invalid side
                  value:
                    error: Invalid side
        '404':
          description: Not found - No orderbook exists for the requested token id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: No orderbook exists for the requested token id
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
  /book:
    get:
      summary: Get order book
      description: |
        Retrieves the order book summary for a specific token ID.
        Includes bids, asks, market details, and last trade price.
      operationId: getBook
      tags:
        - Market Data
      security: []
      parameters:
        - name: token_id
          in: query
          description: Token ID (asset ID)
          required: true
          schema:
            type: string
          example: 0xabc123def456...
      responses:
        '200':
          description: Successfully retrieved order book
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderBookSummary'
              example:
                market: '0x1234567890123456789012345678901234567890'
                asset_id: 0xabc123def456...
                timestamp: '1234567890'
                hash: a1b2c3d4e5f6...
                bids:
                  - price: '0.45'
                    size: '100'
                  - price: '0.44'
                    size: '200'
                asks:
                  - price: '0.46'
                    size: '150'
                  - price: '0.47'
                    size: '250'
                min_order_size: '1'
                tick_size: '0.01'
                neg_risk: false
                last_trade_price: '0.45'
        '400':
          description: Bad request - Invalid token id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid token id
        '404':
          description: Not found - No orderbook exists for the requested token id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: No orderbook exists for the requested token id
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: error getting the orderbook
  /books:
    get:
      summary: Get order books (query parameters)
      description: >
        Retrieves order book summaries for multiple token IDs using query
        parameters.
      operationId: getBooksGet
      tags:
        - Market Data
      security: []
      parameters:
        - name: token_ids
          in: query
          description: Comma-separated list of token IDs
          required: true
          schema:
            type: string
          example: 0xabc123...,0xdef456...
      responses:
        '200':
          description: Successfully retrieved order books
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrderBookSummary'
              example:
                - market: '0x1234567890123456789012345678901234567890'
                  asset_id: 0xabc123def456...
                  timestamp: '1234567890'
                  hash: a1b2c3d4e5f6...
                  bids:
                    - price: '0.45'
                      size: '100'
                  asks:
                    - price: '0.46'
                      size: '150'
                  min_order_size: '1'
                  tick_size: '0.01'
                  neg_risk: false
                  last_trade_price: '0.45'
        '400':
          description: Bad request - Invalid payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid payload
    post:
      summary: Get order books (request body)
      security: []
      description: >
        Retrieves order book summaries for multiple token IDs using a request
        body.
      operationId: getBooksPost
      tags:
        - Market Data
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/BookRequest'
            example:
              - token_id: 0xabc123def456...
              - token_id: 0xdef456abc123...
      responses:
        '200':
          description: Successfully retrieved order books
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrderBookSummary'
              example:
                - market: '0x1234567890123456789012345678901234567890'
                  asset_id: 0xabc123def456...
                  timestamp: '1234567890'
                  hash: a1b2c3d4e5f6...
                  bids:
                    - price: '0.45'
                      size: '100'
                  asks:
                    - price: '0.46'
                      size: '150'
                  min_order_size: '1'
                  tick_size: '0.01'
                  neg_risk: false
                  last_trade_price: '0.45'
        '400':
          description: Bad request - Invalid payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid payload
  /simplified-markets:
    get:
      operationId: getSimplifiedMarkets
      summary: Get simplified markets
      tags:
        - Markets
      security: []
      parameters:
        - name: next_cursor
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedSimplifiedMarkets'
        '400':
          description: Invalid request
        '500':
          description: Internal server error
  /sampling-markets:
    get:
      operationId: getSamplingMarkets
      summary: Get sampling markets
      tags:
        - Markets
      security: []
      parameters:
        - name: next_cursor
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedMarkets'
        '400':
          description: Invalid request
        '500':
          description: Internal server error
  /sampling-simplified-markets:
    get:
      operationId: getSamplingSimplifiedMarkets
      summary: Get sampling simplified markets
      tags:
        - Markets
      security: []
      parameters:
        - name: next_cursor
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedSimplifiedMarkets'
        '400':
          description: Invalid request
        '500':
          description: Internal server error
  /clob-markets/{condition_id}:
    get:
      summary: Get CLOB market info
      description: |
        Returns all CLOB-level parameters for a market in a single call —
        tokens, tick size, base fees, rewards, RFQ status, and fee details.
      operationId: getClobMarketInfo
      tags:
        - Markets
      parameters:
        - name: condition_id
          in: path
          required: true
          description: The condition ID of the market
          schema:
            type: string
          example: '0xbd31dc8a20211944f6b70f31557f1001557b59905b7738480ca09bd4532f84af'
      responses:
        '200':
          description: Successfully retrieved CLOB market info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClobMarketDetails'
        '400':
          description: Bad request - Invalid condition ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /markets-by-token/{token_id}:
    get:
      summary: Get market by token
      description: |
        Returns the parent market for a given token ID. Useful when you have
        a token ID and need to resolve its parent market without knowing the
        condition ID in advance.
      operationId: getMarketByToken
      tags:
        - Markets
      parameters:
        - name: token_id
          in: path
          required: true
          description: The token ID to look up the parent market for
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved market
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketByTokenResponse'
        '400':
          description: Invalid market - empty token_id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Market not found for token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /markets/live-activity:
    post:
      operationId: getMarketsLiveActivity
      summary: Get live activity markets by condition IDs
      description: >-
        Returns minimal market information for multiple markets, optimized for
        live activity widgets (e.g., iOS Live Activities, Android widgets)
      tags:
        - Markets
      security: []
      requestBody:
        required: true
        description: Array of condition IDs to fetch
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
              example:
                - 0x1234...
                - 0x5678...
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LiveActivityMarket'
        '400':
          description: Invalid markets - request body is missing or empty
        '404':
          description: Markets not found
        '500':
          description: Internal server error
  /markets/live-activity/{condition_id}:
    get:
      operationId: getMarketLiveActivity
      summary: Get live activity market by condition ID
      description: >-
        Returns minimal market information optimized for live activity widgets
        (e.g., iOS Live Activities, Android widgets)
      tags:
        - Markets
      security: []
      parameters:
        - name: condition_id
          in: path
          description: The condition ID of the market
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LiveActivityMarket'
        '400':
          description: Invalid market - condition_id is missing or invalid
        '404':
          description: Market not found
        '500':
          description: Internal server error
  /prices-history:
    get:
      summary: Get prices history
      description: Retrieve historical price data for a market.
      operationId: getPricesHistory
      tags:
        - Markets
      security: []
      parameters:
        - name: market
          in: query
          required: true
          description: The market (asset id) to query.
          schema:
            type: string
        - name: startTs
          in: query
          required: false
          description: Filter by items after this unix timestamp.
          schema:
            type: number
            format: double
        - name: endTs
          in: query
          required: false
          description: Filter by items before this unix timestamp.
          schema:
            type: number
            format: double
        - name: interval
          in: query
          required: false
          description: Time interval for data aggregation.
          schema:
            type: string
            enum:
              - max
              - all
              - 1m
              - 1w
              - 1d
              - 6h
              - 1h
        - name: fidelity
          in: query
          required: false
          description: Accuracy of the data expressed in minutes. Default is 1 minute.
          schema:
            type: integer
      responses:
        '200':
          description: Successful response with price history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PricesHistoryResponse'
        '400':
          description: Bad Request - Missing or invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /batch-prices-history:
    post:
      summary: Get batch prices history
      description: Retrieve historical price data for multiple markets in a single request.
      operationId: getBatchPricesHistory
      tags:
        - Markets
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchPricesHistoryRequest'
      responses:
        '200':
          description: Successful response with price history for each market
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchPricesHistoryResponse'
        '400':
          description: Bad Request - Missing or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /auth/api-key:
    post:
      summary: Create API key
      description: |
        Creates a new API key for the authenticated Ethereum address.
        The API key is deterministically generated from the address and nonce.
      operationId: createApiKey
      tags:
        - Account
      security:
        - polyAddress: []
          polySignature: []
          polyTimestamp: []
          polyNonce: []
      responses:
        '200':
          description: API key successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyResponse'
              example:
                apiKey: f4f247b7-4ac7-ff29-a152-04fda0a8755a
                secret: base64-encoded-secret
                passphrase: hex-encoded-passphrase
        '400':
          description: Bad request - Could not create API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Could not create api key
        '401':
          description: Unauthorized - Invalid L1 headers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid L1 headers
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
    delete:
      summary: Delete API key
      description: |
        Deletes the API key used for authentication.
        The API key to delete is determined from the authentication headers.
      operationId: deleteApiKey
      tags:
        - Account
      security:
        - polyApiKey: []
          polyAddress: []
          polySignature: []
          polyPassphrase: []
          polyTimestamp: []
      responses:
        '200':
          description: API key successfully deleted
          content:
            application/json:
              schema:
                type: string
              example: OK
        '401':
          description: Unauthorized - Invalid API key or authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid API key
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Could not delete API key
  /auth/api-keys:
    get:
      summary: Get API keys
      description: |
        Retrieves all API keys for the authenticated user.
      operationId: getApiKeys
      tags:
        - Account
      security:
        - polyAddress: []
          polySignature: []
          polyTimestamp: []
          polyNonce: []
      responses:
        '200':
          description: Successfully retrieved API keys
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeysResponse'
              example:
                apiKeys:
                  - f4f247b7-4ac7-ff29-a152-04fda0a8755a
                  - a1b2c3d4-e5f6-7890-abcd-ef1234567890
        '401':
          description: Unauthorized - Invalid API key or authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid API key
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Could not retrieve API keys
  /auth/derive-api-key:
    get:
      summary: Derive API key
      description: >
        Derives an existing API key from an Ethereum address and nonce.

        The API key must have been previously created using the same address and
        nonce.
      operationId: deriveApiKey
      tags:
        - Account
      security:
        - polyAddress: []
          polySignature: []
          polyTimestamp: []
          polyNonce: []
      responses:
        '200':
          description: API key successfully derived
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyResponse'
              example:
                apiKey: f4f247b7-4ac7-ff29-a152-04fda0a8755a
                secret: base64-encoded-secret
                passphrase: hex-encoded-passphrase
        '400':
          description: Bad request - Could not derive API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Could not derive api key!
        '401':
          description: Unauthorized - Invalid L1 headers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid L1 headers
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
  /balance-allowance:
    get:
      summary: Get balance and allowance
      description: >
        Retrieves the balance and allowances for the authenticated user's
        address.

        The address is determined from the API key authentication and signature
        type.
      operationId: getBalanceAllowance
      tags:
        - Account
      security:
        - polyApiKey: []
          polyAddress: []
          polySignature: []
          polyPassphrase: []
          polyTimestamp: []
      parameters:
        - name: asset_type
          in: query
          description: Type of asset
          required: true
          schema:
            type: string
            enum:
              - COLLATERAL
              - CONDITIONAL
          example: COLLATERAL
        - name: token_id
          in: query
          description: Token ID (asset ID). Defaults to "-1" for ERC20 collateral.
          required: false
          schema:
            type: string
          example: 0xabc123def456...
        - name: signature_type
          in: query
          description: >-
            Signature type for address derivation (0=EOA, 1=POLY_PROXY,
            2=POLY_GNOSIS_SAFE)
          required: false
          schema:
            type: integer
            default: 0
            enum:
              - 0
              - 1
              - 2
      responses:
        '200':
          description: Successfully retrieved balance and allowances
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceAllowanceResponse'
              example:
                balance: '1000000000000000000'
                allowances:
                  '0x1234567890123456789012345678901234567890': '500000000000000000'
                  '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd': '1000000000000000000'
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_asset_type:
                  summary: Invalid asset type
                  value:
                    error: Invalid asset type
                invalid_signature_type:
                  summary: Invalid signature type
                  value:
                    error: Invalid signature_type
        '401':
          description: Unauthorized - Invalid API key or authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid API key
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
    put:
      summary: Update balance and allowance
      description: >
        Forces an update of the balance and allowances by fetching fresh data
        from the blockchain.

        The address is determined from the API key authentication and signature
        type.
      operationId: updateBalanceAllowance
      tags:
        - Account
      security:
        - polyApiKey: []
          polyAddress: []
          polySignature: []
          polyPassphrase: []
          polyTimestamp: []
      parameters:
        - name: asset_type
          in: query
          description: Type of asset
          required: true
          schema:
            type: string
            enum:
              - COLLATERAL
              - CONDITIONAL
          example: COLLATERAL
        - name: token_id
          in: query
          description: Token ID (asset ID). Defaults to "-1" for ERC20 collateral.
          required: false
          schema:
            type: string
          example: 0xabc123def456...
        - name: signature_type
          in: query
          description: >-
            Signature type for address derivation (0=EOA, 1=POLY_PROXY,
            2=POLY_GNOSIS_SAFE)
          required: false
          schema:
            type: integer
            default: 0
            enum:
              - 0
              - 1
              - 2
      responses:
        '200':
          description: Balance and allowances successfully updated
          content:
            application/json:
              schema:
                type: object
              example: {}
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_asset_type:
                  summary: Invalid asset type
                  value:
                    error: Invalid asset type
                invalid_signature_type:
                  summary: Invalid signature type
                  value:
                    error: Invalid signature_type
        '401':
          description: Unauthorized - Invalid API key or authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid API key
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
  /balance-allowance/update:
    get:
      summary: Update balance and allowance
      description: >
        Forces an update of the balance and allowances by fetching fresh data
        from the blockchain.

        The address is determined from the API key authentication and signature
        type.
      operationId: getUpdateBalanceAllowance
      tags:
        - Account
      security:
        - polyApiKey: []
          polyAddress: []
          polySignature: []
          polyPassphrase: []
          polyTimestamp: []
      parameters:
        - name: asset_type
          in: query
          description: Type of asset
          required: true
          schema:
            type: string
            enum:
              - COLLATERAL
              - CONDITIONAL
          example: COLLATERAL
        - name: token_id
          in: query
          description: Token ID (asset ID). Defaults to "-1" for ERC20 collateral.
          required: false
          schema:
            type: string
          example: 0xabc123def456...
        - name: signature_type
          in: query
          description: >-
            Signature type for address derivation (0=EOA, 1=POLY_PROXY,
            2=POLY_GNOSIS_SAFE)
          required: false
          schema:
            type: integer
            default: 0
            enum:
              - 0
              - 1
              - 2
      responses:
        '200':
          description: Balance and allowances successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceAllowanceResponse'
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_asset_type:
                  summary: Invalid asset type
                  value:
                    error: Invalid asset type
                invalid_signature_type:
                  summary: Invalid signature type
                  value:
                    error: Invalid signature_type
        '401':
          description: Unauthorized - Invalid API key or authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid API key
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
  /auth/ban-status/closed-only:
    get:
      summary: Get closed-only mode status
      description: >
        Retrieves the closed-only trading mode status for the authenticated
        user.


        When closed-only mode is enabled, the user can only close existing
        positions

        and cannot open new ones.
      operationId: getClosedOnlyMode
      tags:
        - Account
      security:
        - polyApiKey: []
          polyAddress: []
          polySignature: []
          polyPassphrase: []
          polyTimestamp: []
      responses:
        '200':
          description: Successfully retrieved closed-only mode status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClosedOnlyResponse'
              example:
                closed_only: false
        '401':
          description: Unauthorized - Invalid API key or authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid API key
        '404':
          description: Not found - No ban status record found for the address
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: not found
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
  /auth/builder-api-key:
    get:
      summary: Get builder API keys
      description: |
        Retrieves all active builder API keys owned by the authenticated user.

        Requires Polymarket L2 Authentication.
      operationId: getBuilderApiKeys
      tags:
        - Account
      security:
        - polyApiKey: []
          polyAddress: []
          polySignature: []
          polyPassphrase: []
          polyTimestamp: []
      responses:
        '200':
          description: Successfully retrieved builder API keys
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                description: Array of builder API key UUIDs
              example:
                - 019894b9-cb40-79c4-b2bd-6aecb6f8c6c5
                - 019894b9-cb40-79c4-b2bd-6aecb6f8c6c6
                - 019894b9-cb40-79c4-b2bd-6aecb6f8c6c7
        '401':
          description: Unauthorized - Invalid API key or authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid API key
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Could not get builder api keys
    post:
      summary: Create builder API key
      description: |
        Creates a new builder API key for the authenticated user.

        Requires Polymarket L2 Authentication. The owner is determined from the
        L2 authentication headers.
      operationId: createBuilderApiKey
      tags:
        - Account
      security:
        - polyApiKey: []
          polyAddress: []
          polySignature: []
          polyPassphrase: []
          polyTimestamp: []
      responses:
        '200':
          description: Builder API key successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuilderApiKeyResponse'
              example:
                key: 019894b9-cb40-79c4-b2bd-6aecb6f8c6c5
                secret: base64-encoded-secret
                passphrase: hex-encoded-passphrase
        '401':
          description: Unauthorized - Invalid API key or authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid API key
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Could not create builder api key
    delete:
      summary: Revoke builder API key
      description: >
        Revokes a builder API key.


        Builder codes are tied to the authenticated user's profile. Authenticate
        with

        standard CLOB L2 headers to revoke a builder API key associated with
        your account.
      operationId: revokeBuilderApiKey
      tags:
        - Account
      security:
        - polyApiKey: []
          polyAddress: []
          polySignature: []
          polyPassphrase: []
          polyTimestamp: []
      responses:
        '200':
          description: Builder API key successfully revoked
          content:
            application/json:
              schema:
                type: string
              example: OK
        '400':
          description: Bad request - Invalid revoke builder api key body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid revoke builder api key body
        '401':
          description: Unauthorized - Invalid authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid auth
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: >-
                  Could not revoke the builder api key:
                  019894b9-cb40-79c4-b2bd-6aecb6f8c6c5
  /notifications:
    get:
      summary: Get notifications
      description: |
        Retrieves all unread notifications for the authenticated user.

        Notification types include:
        - Order cancellation
        - Order fill (taker or maker)
        - Market registered
        - Market resolved
        - Reward payout
        - Child comment created
      operationId: getNotifications
      tags:
        - Notifications
      security:
        - polyApiKey: []
          polyAddress: []
          polySignature: []
          polyPassphrase: []
          polyTimestamp: []
      parameters:
        - name: signature_type
          in: query
          description: |
            Signature type for address derivation:
            - 0: EOA
            - 1: POLY_PROXY
            - 2: POLY_GNOSIS_SAFE
          required: true
          schema:
            type: integer
            enum:
              - 0
              - 1
              - 2
      responses:
        '200':
          description: Successfully retrieved notifications
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Notification'
              example:
                - id: 1
                  owner: f4f247b7-4ac7-ff29-a152-04fda0a8755a
                  type: 2
                  payload:
                    order_id: >-
                      0x72c66a1f70c00ac5e5eb9ce0452b7d118bc4869f8b822a1a8d8580c16e3ca83e
                    market: >-
                      0xbd31dc8a20211944f6b70f31557f1001557b59905b7738480ca09bd4532f84af
                    asset_id: >-
                      1343197538147866997676250008839231694243646439454152539053893078719042421992
                    side: SELL
                    price: '0.6'
                    original_size: '100'
                    matched_size: '10'
                    remaining_size: '90'
                    outcome: 'YES'
                    outcome_index: 0
                  timestamp: 1675277676
        '400':
          description: Bad request - Invalid signature_type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid signature_type
        '401':
          description: Unauthorized - Invalid API key or authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid API key
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
    delete:
      summary: Mark notifications as read
      description: >
        Marks the specified notifications as read/seen for the authenticated
        user.

        Once marked as read, notifications will no longer appear in GET
        /notifications.
      operationId: dropNotifications
      tags:
        - Notifications
      security:
        - polyApiKey: []
          polyAddress: []
          polySignature: []
          polyPassphrase: []
          polyTimestamp: []
      parameters:
        - name: ids
          in: query
          description: Comma-separated list of notification IDs to mark as read
          required: true
          schema:
            type: string
          example: 1,2,3
      responses:
        '200':
          description: Notifications successfully marked as read
          content:
            application/json:
              schema:
                type: string
              example: OK
        '400':
          description: Bad request - Invalid ids
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid ids
        '401':
          description: Unauthorized - Invalid API key or authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid API key
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
  /rewards/user:
    get:
      summary: Get earnings for user by date
      description: >
        Returns an array of user earnings per market for a provided day.


        Requires CLOB L2 Auth headers.


        Results are paginated (100 items per page). Use next_cursor to fetch
        subsequent pages.

        A next_cursor value of "LTE=" indicates the last page.
      operationId: getEarningsForUserForDay
      tags:
        - Rewards
      security:
        - polyApiKey: []
          polyAddress: []
          polySignature: []
          polyPassphrase: []
          polyTimestamp: []
      parameters:
        - name: date
          in: query
          description: Date in YYYY-MM-DD format
          required: true
          schema:
            type: string
            format: date
          example: '2024-03-26'
        - name: signature_type
          in: query
          description: |
            Signature type for address derivation (required for API KEY auth):
            - 0: EOA
            - 1: POLY_PROXY
            - 2: POLY_GNOSIS_SAFE
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
              - 2
        - name: maker_address
          in: query
          description: Maker address to query earnings for
          required: false
          schema:
            type: string
          example: '0xFeA4cB3dD4ca7CefD3368653B7D6FF9BcDFca604'
        - name: sponsored
          in: query
          description: If true, returns sponsored-only earnings
          required: false
          schema:
            type: boolean
            default: false
        - name: next_cursor
          in: query
          description: Pagination cursor from previous response
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved user earnings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedUserEarnings'
              example:
                limit: 100
                count: 1
                next_cursor: LTE=
                data:
                  - date: '2024-03-26T00:00:00Z'
                    condition_id: >-
                      0xbd31dc8a20211944f6b70f31557f1001557b59905b7738480ca09bd4532f84af
                    asset_address: '0x9c4E1703476E875070EE25b56A58B008CFb8FA78'
                    maker_address: '0xFeA4cB3dD4ca7CefD3368653B7D6FF9BcDFca604'
                    earnings: 0.237519
                    asset_rate: 1
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_date:
                  summary: Invalid date format
                  value:
                    error: 'Invalid date (format: YYYY-MM-DD)'
                invalid_signature_type:
                  summary: Invalid signature type
                  value:
                    error: Invalid signature_type
                invalid_maker_address:
                  summary: Invalid maker address
                  value:
                    error: Invalid maker_address
        '401':
          description: Unauthorized - Invalid API key or authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid API key
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
  /rewards/user/total:
    get:
      summary: Get total earnings for user by date
      description: |
        Returns the summed total rewards earnings for a user on a provided day,
        grouped by asset address.

        Requires CLOB L2 Auth headers.
      operationId: getTotalEarningsForUserForDay
      tags:
        - Rewards
      security:
        - polyApiKey: []
          polyAddress: []
          polySignature: []
          polyPassphrase: []
          polyTimestamp: []
      parameters:
        - name: date
          in: query
          description: Date in YYYY-MM-DD format
          required: true
          schema:
            type: string
            format: date
          example: '2024-03-26'
        - name: signature_type
          in: query
          description: |
            Signature type for address derivation (required for API KEY auth):
            - 0: EOA
            - 1: POLY_PROXY
            - 2: POLY_GNOSIS_SAFE
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
              - 2
        - name: maker_address
          in: query
          description: Maker address to query earnings for
          required: false
          schema:
            type: string
          example: '0xFeA4cB3dD4ca7CefD3368653B7D6FF9BcDFca604'
        - name: sponsored
          in: query
          description: If true, aggregates both native and sponsored earnings
          required: false
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Successfully retrieved total user earnings
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TotalUserEarning'
              example:
                - date: '2024-04-09T00:00:00Z'
                  asset_address: '0x9c4E1703476E875070EE25b56A58B008CFb8FA78'
                  maker_address: '0xD527CCdBEB6478488c848465F9947bDA3C2e6994'
                  earnings: 1.59984
                  asset_rate: 0.999357
                - date: '2024-04-09T00:00:00Z'
                  asset_address: '0x69308FB512518e39F9b16112fA8d994F4e2Bf8bB'
                  maker_address: '0xD527CCdBEB6478488c848465F9947bDA3C2e6994'
                  earnings: 8.187219
                  asset_rate: 3.51
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_date:
                  summary: Invalid date format
                  value:
                    error: 'Invalid date (format: YYYY-MM-DD)'
                invalid_signature_type:
                  summary: Invalid signature type
                  value:
                    error: Invalid signature_type
                invalid_maker_address:
                  summary: Invalid maker address
                  value:
                    error: Invalid maker_address
        '401':
          description: Unauthorized - Invalid API key or authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid API key
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
  /rewards/user/percentages:
    get:
      summary: Get reward percentages for user
      description: >
        Returns the real-time percentages of rewards that a user is earning per
        market.


        The response is a map of condition_id to the percentage of total rewards

        the user is currently earning in that market.


        Requires CLOB L2 Auth headers.
      operationId: getRewardPercentagesForUser
      tags:
        - Rewards
      security:
        - polyApiKey: []
          polyAddress: []
          polySignature: []
          polyPassphrase: []
          polyTimestamp: []
      parameters:
        - name: signature_type
          in: query
          description: |
            Signature type for address derivation (required for API KEY auth):
            - 0: EOA
            - 1: POLY_PROXY
            - 2: POLY_GNOSIS_SAFE
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
              - 2
        - name: maker_address
          in: query
          description: Maker address to query percentages for
          required: false
          schema:
            type: string
          example: '0xFeA4cB3dD4ca7CefD3368653B7D6FF9BcDFca604'
      responses:
        '200':
          description: Successfully retrieved reward percentages
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: number
                  format: double
                description: Map of condition_id to reward percentage
              example:
                '0x296ea2f3ad438ce7ead77f40d0159bf3e5d8be146f6f615fa253b00e02243f5c': 20
                '0xbd31dc8a20211944f6b70f31557f1001557b59905b7738480ca09bd4532f84af': 20
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_signature_type:
                  summary: Invalid signature type
                  value:
                    error: Invalid signature_type
                invalid_maker_address:
                  summary: Invalid maker address
                  value:
                    error: Invalid maker_address
        '401':
          description: Unauthorized - Invalid API key or authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid API key
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
  /rewards/user/markets:
    get:
      summary: Get user earnings and markets configuration
      description: >
        Returns an array of current rewards including user earnings and live
        percentages

        per market for a provided day.


        Results are paginated (100 items per page by default, max 500). Use
        next_cursor to fetch subsequent pages.

        A next_cursor value of "LTE=" indicates the last page.


        Requires CLOB L2 Auth headers.


        Optional features:

        - Search by question/description using the `q` parameter

        - Filter by tag slugs using `tag_slug` parameter (multiple values are
        OR'ed)

        - Filter by favorite markets using `favorite_markets=true`

        - Sort by various fields using `order_by` and `position` parameters
      operationId: getUserEarningsAndMarketsConfig
      tags:
        - Rewards
      security:
        - polyApiKey: []
          polyAddress: []
          polySignature: []
          polyPassphrase: []
          polyTimestamp: []
      parameters:
        - name: date
          in: query
          description: Date in YYYY-MM-DD format. Defaults to current date if not provided.
          required: false
          schema:
            type: string
            format: date
          example: '2024-03-26'
        - name: signature_type
          in: query
          description: |
            Signature type for address derivation (required for API KEY auth):
            - 0: EOA
            - 1: POLY_PROXY
            - 2: POLY_GNOSIS_SAFE
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
              - 2
        - name: maker_address
          in: query
          description: Maker address to query data for
          required: false
          schema:
            type: string
          example: '0xFeA4cB3dD4ca7CefD3368653B7D6FF9BcDFca604'
        - name: sponsored
          in: query
          description: If true, returns sponsored reward earnings
          required: false
          schema:
            type: boolean
            default: false
        - name: next_cursor
          in: query
          description: Pagination cursor from previous response
          required: false
          schema:
            type: string
        - name: page_size
          in: query
          description: Number of items per page (max 500, values above are capped)
          required: false
          schema:
            type: integer
            default: 100
            maximum: 500
        - name: q
          in: query
          description: Search query to filter markets by question/description
          required: false
          schema:
            type: string
        - name: tag_slug
          in: query
          description: Filter by tag slug (can be repeated for OR logic)
          required: false
          schema:
            type: string
        - name: favorite_markets
          in: query
          description: If true, only show markets favorited by the user (requires auth)
          required: false
          schema:
            type: boolean
            default: false
        - name: no_competition
          in: query
          description: Filter for markets with no competition
          required: false
          schema:
            type: boolean
            default: false
        - name: only_mergeable
          in: query
          description: Filter for only mergeable markets
          required: false
          schema:
            type: boolean
            default: false
        - name: only_open_orders
          in: query
          description: Filter for markets where user has open orders
          required: false
          schema:
            type: boolean
            default: false
        - name: only_open_positions
          in: query
          description: Filter for markets where user has open positions
          required: false
          schema:
            type: boolean
            default: false
        - name: order_by
          in: query
          description: Field to sort by
          required: false
          schema:
            type: string
            enum:
              - max_spread
              - min_size
              - end_date
              - earning_percentage
              - rate_per_day
              - earnings
              - spread
              - competitiveness
              - question
              - price
              - market
              - volume_24hr
        - name: position
          in: query
          description: Sort direction
          required: false
          schema:
            type: string
            enum:
              - ASC
              - DESC
      responses:
        '200':
          description: Successfully retrieved user earnings and market configurations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedUserRewardsMarkets'
              example:
                limit: 100
                count: 1
                total_count: 42
                next_cursor: LTE=
                data:
                  - condition_id: >-
                      0xbd31dc8a20211944f6b70f31557f1001557b59905b7738480ca09bd4532f84af
                    market_id: '248849'
                    event_id: '12345'
                    question: Will Trump win the 2024 Iowa Caucus?
                    market_slug: will-trump-win-the-2024-iowa-caucus
                    event_slug: will-trump-win-the-2024-iowa-caucus
                    image: >-
                      https://polymarket-upload.s3.us-east-2.amazonaws.com/trump1+copy.png
                    rewards_max_spread: 99
                    rewards_min_size: 10
                    volume_24hr: 12345.67
                    spread: 0.12
                    market_competitiveness: 0.42
                    tokens:
                      - token_id: >-
                          1343197538147866997676250008839231694243646439454152539053893078719042421992
                        outcome: 'YES'
                        price: 0.8
                      - token_id: >-
                          16678291189211314787145083999015737376658799626183230671758641503291735614088
                        outcome: 'NO'
                        price: 0.2
                    rewards_config:
                      - id: 0
                        asset_address: '0x9c4E1703476E875070EE25b56A58B008CFb8FA78'
                        start_date: '2024-03-01'
                        end_date: '2500-12-31'
                        rate_per_day: 2
                        total_rewards: 92
                    maker_address: '0xD527CCdBEB6478488c848465F9947bDA3C2e6994'
                    earning_percentage: 30
                    earnings:
                      - asset_address: '0x9c4E1703476E875070EE25b56A58B008CFb8FA78'
                        earnings: 0.585051
                        asset_rate: 1.001
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_date:
                  summary: Invalid date format
                  value:
                    error: 'Invalid date (format: YYYY-MM-DD)'
                invalid_signature_type:
                  summary: Invalid signature type
                  value:
                    error: Invalid signature_type
                favorite_requires_auth:
                  summary: Favorite markets requires auth
                  value:
                    error: favorite_markets query argument requires authentication
        '401':
          description: Unauthorized - Invalid API key or authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid API key
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
  /rewards/markets/current:
    get:
      summary: Get current active rewards configurations
      description: >
        Returns all current active rewards configurations grouped by market.


        When `sponsored=true`, returns sponsored reward configurations instead.


        Results are paginated (500 items per page). Use next_cursor to fetch
        subsequent pages.

        A next_cursor value of "LTE=" indicates the last page.
      operationId: getCurrentRewards
      tags:
        - Rewards
      parameters:
        - name: sponsored
          in: query
          description: >-
            If true, returns sponsored reward configurations instead of standard
            ones
          required: false
          schema:
            type: boolean
            default: false
        - name: next_cursor
          in: query
          description: Pagination cursor from previous response
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved current rewards configurations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedCurrentReward'
              example:
                limit: 500
                count: 1
                next_cursor: LTE=
                data:
                  - condition_id: >-
                      0xbd31dc8a20211944f6b70f31557f1001557b59905b7738480ca09bd4532f84af
                    rewards_max_spread: 99
                    rewards_min_size: 10
                    rewards_config:
                      - id: 0
                        asset_address: '0x9c4E1703476E875070EE25b56A58B008CFb8FA78'
                        start_date: '2024-03-01'
                        end_date: '2500-12-31'
                        rate_per_day: 2
                        total_rewards: 92
                      - id: 0
                        asset_address: '0x69308FB512518e39F9b16112fA8d994F4e2Bf8bB'
                        start_date: '2024-03-01'
                        end_date: '2500-12-31'
                        rate_per_day: 1
                        total_rewards: 46
                    sponsored_daily_rate: 0.5
                    sponsors_count: 2
                    native_daily_rate: 2.5
                    total_daily_rate: 3
        '400':
          description: Bad request - Invalid next_cursor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid next_cursor
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
  /rewards/markets/{condition_id}:
    get:
      summary: Get raw rewards for a specific market
      description: >
        Returns an array of present and future rewards configured on a market.


        When `sponsored=true`, sponsored daily rates are folded into each
        config's

        `rate_per_day` .


        Results are paginated (100 items per page). Use next_cursor to fetch
        subsequent pages.

        A next_cursor value of "LTE=" indicates the last page.
      operationId: getRawRewardsForMarket
      tags:
        - Rewards
      parameters:
        - name: condition_id
          in: path
          description: The condition ID of the market
          required: true
          schema:
            type: string
          example: '0xbd31dc8a20211944f6b70f31557f1001557b59905b7738480ca09bd4532f84af'
        - name: sponsored
          in: query
          description: If true, folds sponsored daily rates into each config's rate_per_day
          required: false
          schema:
            type: boolean
            default: false
        - name: next_cursor
          in: query
          description: Pagination cursor from previous response
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved rewards for market
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedMarketReward'
              example:
                limit: 100
                count: 1
                next_cursor: LTE=
                data:
                  - condition_id: >-
                      0xbd31dc8a20211944f6b70f31557f1001557b59905b7738480ca09bd4532f84af
                    question: Will Trump win the 2024 Iowa Caucus?
                    market_slug: will-trump-win-the-2024-iowa-caucus
                    event_slug: will-trump-win-the-2024-iowa-caucus
                    image: >-
                      https://polymarket-upload.s3.us-east-2.amazonaws.com/trump1+copy.png
                    rewards_max_spread: 99
                    rewards_min_size: 10
                    market_competitiveness: 0.42
                    tokens:
                      - token_id: >-
                          1343197538147866997676250008839231694243646439454152539053893078719042421992
                        outcome: 'YES'
                        price: 0.8
                      - token_id: >-
                          16678291189211314787145083999015737376658799626183230671758641503291735614088
                        outcome: 'NO'
                        price: 0.2
                    rewards_config:
                      - id: 1
                        asset_address: '0x9c4E1703476E875070EE25b56A58B008CFb8FA78'
                        start_date: '2024-03-01'
                        end_date: '2500-12-31'
                        rate_per_day: 0.25
                        total_rewards: 0
                        total_days: 174161
                      - id: 2
                        asset_address: '0x9c4E1703476E875070EE25b56A58B008CFb8FA78'
                        start_date: '2024-03-01'
                        end_date: '2024-05-31'
                        rate_per_day: 1
                        total_rewards: 92
                        total_days: 92
        '400':
          description: Bad request - Invalid market or next_cursor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_market:
                  summary: Empty condition ID
                  value:
                    error: Invalid market
                invalid_cursor:
                  summary: Invalid pagination cursor
                  value:
                    error: Invalid next_cursor
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
  /rewards/markets/multi:
    get:
      summary: Get multiple markets with rewards
      description: >
        Returns a list of active markets with their reward configurations.

        Supports text search, tag filtering, numeric filters, and sorting.


        Results are paginated (100 items per page by default). Use next_cursor
        to fetch subsequent pages.

        A next_cursor value of "LTE=" indicates the last page.
      operationId: getMultiMarkets
      tags:
        - Rewards
      parameters:
        - name: q
          in: query
          description: Text search on market question/description
          required: false
          schema:
            type: string
        - name: tag_slug
          in: query
          description: >-
            Filter by tag slug. Can be repeated for OR logic (e.g.,
            ?tag_slug=sports&tag_slug=politics)
          required: false
          schema:
            type: string
        - name: event_id
          in: query
          description: >-
            Filter by event ID. Can be repeated for multiple events (e.g.,
            ?event_id=100&event_id=200)
          required: false
          schema:
            type: string
        - name: event_title
          in: query
          description: Search event titles using case-insensitive pattern matching
          required: false
          schema:
            type: string
        - name: order_by
          in: query
          description: Field to sort results by
          required: false
          schema:
            type: string
            enum:
              - market_id
              - created_at
              - volume_24hr
              - spread
              - competitiveness
              - max_spread
              - min_size
              - question
              - one_day_price_change
              - rate_per_day
              - price
              - end_date
              - start_date
              - reward_end_date
        - name: position
          in: query
          description: Sort direction
          required: false
          schema:
            type: string
            enum:
              - ASC
              - DESC
        - name: min_volume_24hr
          in: query
          description: Minimum 24-hour volume filter
          required: false
          schema:
            type: number
            format: double
        - name: max_volume_24hr
          in: query
          description: Maximum 24-hour volume filter
          required: false
          schema:
            type: number
            format: double
        - name: min_spread
          in: query
          description: Minimum spread filter
          required: false
          schema:
            type: number
            format: double
        - name: max_spread
          in: query
          description: Maximum spread filter
          required: false
          schema:
            type: number
            format: double
        - name: min_price
          in: query
          description: Minimum first token price filter
          required: false
          schema:
            type: number
            format: double
        - name: max_price
          in: query
          description: Maximum first token price filter
          required: false
          schema:
            type: number
            format: double
        - name: next_cursor
          in: query
          description: Pagination cursor from previous response
          required: false
          schema:
            type: string
        - name: page_size
          in: query
          description: Number of items per page (max 500, values above are capped)
          required: false
          schema:
            type: integer
            default: 100
            maximum: 500
      responses:
        '200':
          description: Successfully retrieved markets with rewards
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedMultiMarketInfo'
              example:
                limit: 50
                count: 1
                next_cursor: NQ==
                data:
                  - condition_id: >-
                      0xbd31dc8a20211944f6b70f31557f1001557b59905b7738480ca09bd4532f84af
                    event_id: '12345'
                    event_slug: 2024-us-election
                    created_at: '2024-05-01T12:00:00Z'
                    group_item_title: ''
                    image: https://example.com/image.png
                    market_competitiveness: 0.42
                    market_id: '248849'
                    market_slug: will-trump-win-the-2024-iowa-caucus
                    one_day_price_change: 0.03
                    question: Will Trump win the 2024 Iowa Caucus?
                    rewards_max_spread: 99
                    rewards_min_size: 10
                    spread: 0.12
                    end_date: '2024-08-10 00:00:00'
                    tokens:
                      - token_id: >-
                          1343197538147866997676250008839231694243646439454152539053893078719042421992
                        outcome: 'YES'
                        price: 0.8
                      - token_id: >-
                          16678291189211314787145083999015737376658799626183230671758641503291735614088
                        outcome: 'NO'
                        price: 0.2
                    volume_24hr: 12345.67
                    rewards_config:
                      - id: 7
                        asset_address: '0x9c4E1703476E875070EE25b56A58B008CFb8FA78'
                        start_date: '2024-03-01'
                        end_date: '2500-12-31'
                        rate_per_day: 2
                        total_rewards: 92
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_order_by:
                  summary: Invalid order_by value
                  value:
                    error: Invalid order_by
                invalid_position:
                  summary: Invalid position value
                  value:
                    error: Invalid position
                invalid_cursor:
                  summary: Invalid pagination cursor
                  value:
                    error: Invalid next_cursor
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
  /rebates/current:
    get:
      summary: Get current rebated fees for a maker
      description: >
        Returns the current rebated fees for a maker address on a given date.


        Each entry includes the condition ID, asset address, and the USDC amount
        rebated.


        This endpoint does not require authentication.
      operationId: getCurrentRebatedFees
      tags:
        - Rebates
      parameters:
        - name: date
          in: query
          description: Date in YYYY-MM-DD format
          required: true
          schema:
            type: string
            format: date
          example: '2026-02-27'
        - name: maker_address
          in: query
          description: Ethereum address of the maker
          required: true
          schema:
            type: string
          example: '0xFeA4cB3dD4ca7CefD3368653B7D6FF9BcDFca604'
      responses:
        '200':
          description: Successfully retrieved rebated fees
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RebatedFees'
              example:
                - date: '2026-02-27'
                  condition_id: >-
                    0xbd31dc8a20211944f6b70f31557f1001557b59905b7738480ca09bd4532f84af
                  asset_address: '0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB'
                  maker_address: '0xFeA4cB3dD4ca7CefD3368653B7D6FF9BcDFca604'
                  rebated_fees_usdc: '0.237519'
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_date:
                  summary: Invalid date
                  value:
                    error: Invalid date
                invalid_maker_address:
                  summary: Invalid maker address
                  value:
                    error: Invalid maker_address
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
  /heartbeats:
    post:
      summary: Send heartbeat
      description: >
        Sends a heartbeat signal to maintain active session status.

        If heartbeats are not sent regularly, all open orders for the user will
        be automatically canceled.

        This is useful for automated trading systems that need to ensure orders
        are canceled

        if the system becomes unresponsive.
      operationId: sendHeartbeat
      tags:
        - Trade
      security:
        - polyApiKey: []
          polyAddress: []
          polySignature: []
          polyPassphrase: []
          polyTimestamp: []
      responses:
        '200':
          description: Heartbeat acknowledged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeartbeatResponse'
              example:
                status: ok
        '401':
          description: Unauthorized - Invalid API key or authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid API key
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
  /v1/heartbeats:
    post:
      summary: Send heartbeat (v1)
      description: >
        Sends a heartbeat signal with session tracking via heartbeat ID.


        The first request should include an empty or initial heartbeat_id. The
        response will contain

        a new heartbeat_id that must be used in subsequent requests. If the
        provided heartbeat_id

        doesn't match the expected value, the request will fail.


        If heartbeats are not sent regularly, all open orders for the user will
        be automatically canceled.

        This is useful for automated trading systems that need to ensure orders
        are canceled

        if the system becomes unresponsive.
      operationId: sendHeartbeatV1
      tags:
        - Trade
      security:
        - polyApiKey: []
          polyAddress: []
          polySignature: []
          polyPassphrase: []
          polyTimestamp: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HeartbeatRequest'
            examples:
              first_heartbeat:
                summary: First heartbeat (empty ID)
                value:
                  heartbeat_id: ''
              subsequent_heartbeat:
                summary: Subsequent heartbeat
                value:
                  heartbeat_id: 550e8400-e29b-41d4-a716-446655440000
      responses:
        '200':
          description: Heartbeat acknowledged with new ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeartbeatV1Response'
              example:
                heartbeat_id: 550e8400-e29b-41d4-a716-446655440000
        '400':
          description: Invalid heartbeat ID - ID doesn't match expected value
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeartbeatErrorResponse'
              example:
                error: Invalid Heartbeat ID
                heartbeat_id: 550e8400-e29b-41d4-a716-446655440000
        '401':
          description: Unauthorized - Invalid API key or authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid API key
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
  /order-scoring:
    get:
      summary: Get order scoring status
      description: >
        Checks if a specific order is currently scoring for rewards.


        An order is considered "scoring" if it meets all the criteria for
        earning maker rewards:

        - The order is live on a rewards-eligible market

        - The order meets the minimum size requirements

        - The order is within the valid spread range

        - The order has been live for the required duration
      operationId: getOrderScoring
      tags:
        - Trade
      security:
        - polyApiKey: []
          polyAddress: []
          polySignature: []
          polyPassphrase: []
          polyTimestamp: []
      parameters:
        - name: order_id
          in: query
          description: The order ID (order hash) to check scoring status for
          required: true
          schema:
            type: string
          example: '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890'
      responses:
        '200':
          description: Successfully retrieved order scoring status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderScoringResponse'
              examples:
                scoring:
                  summary: Order is scoring
                  value:
                    scoring: true
                not_scoring:
                  summary: Order is not scoring
                  value:
                    scoring: false
        '400':
          description: Bad request - Invalid order ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid order_id
        '401':
          description: Unauthorized - Invalid API key or order doesn't belong to user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid API key
        '404':
          description: Market not found for the order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: market not found
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
        '503':
          description: Service unavailable - Trading disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: >-
                  Trading is currently disabled. Check polymarket.com for
                  updates
  /orders-scoring:
    get:
      summary: Get scoring status for multiple orders
      description: >
        Checks if multiple orders are currently scoring for rewards.


        An order is considered "scoring" if it meets all the criteria for
        earning maker rewards:

        - The order is live on a rewards-eligible market

        - The order meets the minimum size requirements

        - The order is within the valid spread range

        - The order has been live for the required duration
      operationId: getOrdersScoring
      tags:
        - Trade
      security:
        - polyApiKey: []
          polyAddress: []
          polySignature: []
          polyPassphrase: []
          polyTimestamp: []
      parameters:
        - name: order_ids
          in: query
          description: Array of order IDs (order hashes) to check scoring status for
          required: true
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
          example:
            - '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890'
            - '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
      responses:
        '200':
          description: Successfully retrieved scoring status for all orders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrdersScoringResponse'
              example:
                '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890': true
                '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef': false
        '400':
          description: Bad request - Invalid payload or order ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_payload:
                  summary: Invalid payload
                  value:
                    error: Invalid payload
                invalid_order_id:
                  summary: Invalid order ID
                  value:
                    error: Invalid orderID
        '401':
          description: Unauthorized - Invalid API key or authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid API key
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
        '503':
          description: Service unavailable - Trading disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: >-
                  Trading is currently disabled. Check polymarket.com for
                  updates
    post:
      summary: Get scoring status for multiple orders (POST)
      description: >
        Checks if multiple orders are currently scoring for rewards.

        This POST variant accepts order IDs in the request body.


        An order is considered "scoring" if it meets all the criteria for
        earning maker rewards:

        - The order is live on a rewards-eligible market

        - The order meets the minimum size requirements

        - The order is within the valid spread range

        - The order has been live for the required duration
      operationId: postOrdersScoring
      tags:
        - Trade
      security:
        - polyApiKey: []
          polyAddress: []
          polySignature: []
          polyPassphrase: []
          polyTimestamp: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
              description: Array of order IDs (order hashes) to check scoring status for
            example:
              - >-
                0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890
              - >-
                0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
      responses:
        '200':
          description: Successfully retrieved scoring status for all orders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrdersScoringResponse'
              example:
                '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890': true
                '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef': false
        '400':
          description: Bad request - Invalid payload or order ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_payload:
                  summary: Invalid payload
                  value:
                    error: Invalid payload
                invalid_order_id:
                  summary: Invalid order ID
                  value:
                    error: Invalid orderID
        '401':
          description: Unauthorized - Invalid API key or authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid API key
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
        '503':
          description: Service unavailable - Trading disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: >-
                  Trading is currently disabled. Check polymarket.com for
                  updates
  /data/trades:
    get:
      summary: Get trades
      description: |
        Retrieves trades for the authenticated user. Returns paginated results.
        Requires readonly or level 2 API key authentication.
      operationId: getTrades
      tags:
        - Trade
      security:
        - polyApiKey: []
          polyAddress: []
          polySignature: []
          polyPassphrase: []
          polyTimestamp: []
      parameters:
        - name: id
          in: query
          description: Trade ID to filter by specific trade
          required: false
          schema:
            type: string
          example: trade-123
        - name: maker_address
          in: query
          description: Maker address to filter trades
          required: true
          schema:
            type: string
            pattern: ^0x[a-fA-F0-9]{40}$
          example: '0x1234567890123456789012345678901234567890'
        - name: market
          in: query
          description: Market (condition ID) to filter trades
          required: false
          schema:
            type: string
            pattern: ^0x[a-fA-F0-9]{64}$
          example: '0x0000000000000000000000000000000000000000000000000000000000000001'
        - name: asset_id
          in: query
          description: Asset ID (token ID) to filter trades
          required: false
          schema:
            type: string
          example: >-
            15871154585880608648532107628464183779895785213830018178010423617714102767076
        - name: before
          in: query
          description: Filter trades before this Unix timestamp
          required: false
          schema:
            type: string
            pattern: ^\d+$
          example: '1700000000'
        - name: after
          in: query
          description: Filter trades after this Unix timestamp
          required: false
          schema:
            type: string
            pattern: ^\d+$
          example: '1600000000'
        - name: next_cursor
          in: query
          description: Cursor for pagination (base64 encoded offset)
          required: false
          schema:
            type: string
          example: MA==
      responses:
        '200':
          description: Successfully retrieved trades
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TradesResponse'
              examples:
                example:
                  summary: User trades response
                  value:
                    limit: 100
                    next_cursor: MTAw
                    count: 2
                    data:
                      - id: trade-123
                        taker_order_id: '0xabcdef1234567890abcdef1234567890abcdef12'
                        market: >-
                          0x0000000000000000000000000000000000000000000000000000000000000001
                        asset_id: >-
                          15871154585880608648532107628464183779895785213830018178010423617714102767076
                        side: BUY
                        size: '100000000'
                        fee_rate_bps: '30'
                        price: '0.5'
                        status: TRADE_STATUS_CONFIRMED
                        match_time: '1700000000'
                        last_update: '1700000000'
                        outcome: 'YES'
                        bucket_index: 0
                        owner: f4f247b7-4ac7-ff29-a152-04fda0a8755a
                        maker_address: '0x1234567890123456789012345678901234567890'
                        transaction_hash: >-
                          0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
                        trader_side: TAKER
                        maker_orders: []
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid trade params payload
        '401':
          description: Unauthorized - Invalid API key or authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid API key
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal server error
  /builder/trades:
    get:
      summary: Get builder trades
      description: |
        Retrieves trades attributed to a builder code.
      operationId: getBuilderTrades
      tags:
        - Trade
      parameters:
        - name: builder_code
          in: query
          description: Builder code to fetch attributed trades for
          required: true
          schema:
            type: string
            pattern: ^0x[a-fA-F0-9]{64}$
          example: '0x0000000000000000000000000000000000000000000000000000000000000001'
        - name: id
          in: query
          description: Trade ID to filter by specific trade
          required: false
          schema:
            type: string
          example: trade-123
        - name: market
          in: query
          description: Market (condition ID) to filter trades
          required: false
          schema:
            type: string
            pattern: ^0x[a-fA-F0-9]{64}$
          example: '0x0000000000000000000000000000000000000000000000000000000000000001'
        - name: asset_id
          in: query
          description: Asset ID (token ID) to filter trades
          required: false
          schema:
            type: string
          example: >-
            15871154585880608648532107628464183779895785213830018178010423617714102767076
        - name: before
          in: query
          description: Filter trades before this Unix timestamp
          required: false
          schema:
            type: string
            pattern: ^\d+$
          example: '1700000000'
        - name: after
          in: query
          description: Filter trades after this Unix timestamp
          required: false
          schema:
            type: string
            pattern: ^\d+$
          example: '1600000000'
        - name: next_cursor
          in: query
          description: Cursor for pagination (base64 encoded offset)
          required: false
          schema:
            type: string
          example: MA==
      responses:
        '200':
          description: Successfully retrieved builder trades
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuilderTradesResponse'
              examples:
                example:
                  summary: Builder trades response
                  value:
                    limit: 300
                    next_cursor: MzAw
                    count: 2
                    data:
                      - id: trade-123
                        tradeType: TAKER
                        takerOrderHash: '0xabcdef1234567890abcdef1234567890abcdef12'
                        builder: >-
                          0x0000000000000000000000000000000000000000000000000000000000000001
                        market: >-
                          0x0000000000000000000000000000000000000000000000000000000000000001
                        assetId: >-
                          15871154585880608648532107628464183779895785213830018178010423617714102767076
                        side: BUY
                        size: '100000000'
                        sizeUsdc: '50000000'
                        price: '0.5'
                        status: TRADE_STATUS_CONFIRMED
                        outcome: 'YES'
                        outcomeIndex: 0
                        owner: f4f247b7-4ac7-ff29-a152-04fda0a8755a
                        maker: '0x1234567890123456789012345678901234567890'
                        transactionHash: >-
                          0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
                        matchTime: '1700000000'
                        bucketIndex: 0
                        fee: '300000'
                        feeUsdc: '150000'
                        createdAt: '2024-01-01T00:00:00Z'
                        updatedAt: '2024-01-01T00:00:00Z'
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: invalid builder trade params
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: could not fetch builder trades
components:
  securitySchemes:
    polyApiKey:
      type: apiKey
      in: header
      name: POLY_API_KEY
      description: Your API key
    polyAddress:
      type: apiKey
      in: header
      name: POLY_ADDRESS
      description: Ethereum address associated with the API key
    polySignature:
      type: apiKey
      in: header
      name: POLY_SIGNATURE
      description: HMAC signature of the request
    polyPassphrase:
      type: apiKey
      in: header
      name: POLY_PASSPHRASE
      description: API key passphrase
    polyTimestamp:
      type: apiKey
      in: header
      name: POLY_TIMESTAMP
      description: Unix timestamp of the request
    polyNonce:
      type: apiKey
      in: header
      name: POLY_NONCE
      description: Nonce of the request
  schemas:
    Order:
      type: object
      description: >
        Order payload submitted to the CLOB API. In CLOB V2, `expiration`
        remains in

        the POST /order wire body for GTD/order-expiry handling, but it is not
        part

        of the EIP-712 signed order struct.
      required:
        - maker
        - signer
        - tokenId
        - makerAmount
        - takerAmount
        - side
        - expiration
        - timestamp
        - builder
        - signature
        - salt
        - signatureType
      properties:
        maker:
          type: string
          description: >-
            Ethereum address of the maker (In the default case, this is your
            proxy address)
          example: '0x1234567890123456789012345678901234567890'
        signer:
          type: string
          description: Ethereum address of the signer
          example: '0x1234567890123456789012345678901234567890'
        tokenId:
          type: string
          description: Token ID (asset ID) for the order
          example: 0xabc123def456...
        makerAmount:
          type: string
          description: Amount the maker is providing in fixed-math with 6 decimals
          example: '100000000'
        takerAmount:
          type: string
          description: Amount the taker is providing in fixed-math with 6 decimals
          example: '200000000'
        side:
          type: string
          description: Order side
          enum:
            - BUY
            - SELL
          example: BUY
        expiration:
          type: string
          description: >-
            Unix timestamp when the order expires. Present in the API wire body;
            not part of the CLOB V2 EIP-712 signed order struct.
          example: '1735689600'
        timestamp:
          type: string
          description: >-
            Unix timestamp in milliseconds when the order was created (used for
            order uniqueness)
          example: '1735689600000'
        metadata:
          type: string
          description: Reserved for future use
          example: ''
        builder:
          type: string
          description: >-
            Builder code (bytes32) for integrator attribution. `0x` + 64 hex
            chars or empty.
          example: '0x0000000000000000000000000000000000000000000000000000000000000000'
        signature:
          type: string
          description: Cryptographic signature of the order
          example: 0x1234abcd...
        salt:
          type: integer
          description: Random salt for order uniqueness
          example: 1234567890
        signatureType:
          type: integer
          description: Type of signature (0 = EOA, 1 = POLY_PROXY, 2 = POLY_GNOSIS_SAFE)
          enum:
            - 0
            - 1
            - 2
    SendOrder:
      type: object
      required:
        - order
        - owner
      properties:
        order:
          $ref: '#/components/schemas/Order'
        owner:
          type: string
          description: UUID of the API key owner
          example: f4f247b7-4ac7-ff29-a152-04fda0a8755a
        orderType:
          type: string
          description: Time in force
          enum:
            - GTC
            - FOK
            - GTD
            - FAK
          default: GTC
        deferExec:
          type: boolean
          description: Whether to defer execution
          default: false
        postOnly:
          type: boolean
          description: >-
            Whether the order must rest on the book and not match immediately.
            Only supported for GTC and GTD orders.
          default: false
    SendOrderResponse:
      type: object
      required:
        - success
        - orderID
        - status
      properties:
        success:
          type: boolean
          description: Whether the order was successfully processed
          example: true
        orderID:
          type: string
          description: Unique identifier for the order (order hash)
          example: '0xabcdef1234567890abcdef1234567890abcdef12'
        status:
          type: string
          description: Status of the order after processing
          enum:
            - live
            - matched
            - delayed
        makingAmount:
          type: string
          description: Amount the maker is providing in fixed-math with 6 decimals
          example: '100000000'
        takingAmount:
          type: string
          description: Amount the taker is providing in fixed-math with 6 decimals
          example: '200000000'
        transactionsHashes:
          type: array
          description: Array of transaction hashes (present when status is 'matched')
          items:
            type: string
          example:
            - '0x1234567890abcdef1234567890abcdef12345678'
        tradeIDs:
          type: array
          description: Array of trade IDs (present when status is 'matched')
          items:
            type: string
        errorMsg:
          type: string
          description: Error message (empty on success)
          example: ''
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Error message
        code:
          type: string
          description: Machine-readable error code, when provided
        retry_after_seconds:
          type: integer
          description: Number of seconds to wait before retrying, when provided
    CancelOrderPayload:
      type: object
      required:
        - orderID
      properties:
        orderID:
          type: string
          description: Order ID (order hash) to cancel
          example: '0xabcdef1234567890abcdef1234567890abcdef12'
    CancelOrdersResponse:
      type: object
      required:
        - canceled
        - not_canceled
      properties:
        canceled:
          type: array
          description: Array of order IDs that were successfully canceled
          items:
            type: string
          example:
            - '0xabcdef1234567890abcdef1234567890abcdef12'
        not_canceled:
          type: object
          description: Map of order IDs that could not be canceled with error messages
          additionalProperties:
            type: string
          example:
            '0xabcdef1234567890abcdef1234567890abcdef12': Order not found or already canceled
    OpenOrder:
      type: object
      required:
        - id
        - status
        - owner
        - maker_address
        - market
        - asset_id
        - side
        - original_size
        - size_matched
        - price
        - expiration
        - order_type
        - created_at
        - outcome
      properties:
        id:
          type: string
          description: Order ID (order hash)
          example: '0xabcdef1234567890abcdef1234567890abcdef12'
        status:
          type: string
          description: Order status
          enum:
            - ORDER_STATUS_LIVE
            - ORDER_STATUS_INVALID
            - ORDER_STATUS_CANCELED_MARKET_RESOLVED
            - ORDER_STATUS_CANCELED
            - ORDER_STATUS_MATCHED
        owner:
          type: string
          description: UUID of the order owner
          example: f4f247b7-4ac7-ff29-a152-04fda0a8755a
        maker_address:
          type: string
          description: Ethereum address of the maker
          example: '0x1234567890123456789012345678901234567890'
        market:
          type: string
          description: Market (condition ID)
          example: '0x0000000000000000000000000000000000000000000000000000000000000001'
        asset_id:
          type: string
          description: Asset ID (token ID)
          example: 0xabc123def456...
        side:
          type: string
          description: Order side
          enum:
            - BUY
            - SELL
          example: BUY
        original_size:
          type: string
          description: Original order size in fixed-math with 6 decimals
          example: '100000000'
        size_matched:
          type: string
          description: Size that has been matched in fixed-math with 6 decimals
          example: '0'
        price:
          type: string
          description: Order price
          example: '0.5'
        outcome:
          type: string
          description: Market outcome (YES/NO)
          example: 'YES'
        expiration:
          type: string
          description: Unix timestamp when the order expires
          example: '1735689600'
        order_type:
          type: string
          description: Order type
          enum:
            - GTC
            - FOK
            - GTD
            - FAK
          example: GTC
        associate_trades:
          type: array
          description: Array of associated trade IDs
          items:
            type: string
          example:
            - trade-123
        created_at:
          type: integer
          description: Unix timestamp when the order was created
          example: 1700000000
    OrdersResponse:
      type: object
      required:
        - limit
        - next_cursor
        - count
        - data
      properties:
        limit:
          type: integer
          description: Maximum number of results per page
          example: 100
        next_cursor:
          type: string
          description: >-
            Cursor for pagination (base64 encoded offset). Empty if no more
            results.
          example: MTAw
        count:
          type: integer
          description: Number of orders in this response
          example: 2
        data:
          type: array
          description: Array of open orders
          items:
            $ref: '#/components/schemas/OpenOrder'
    OrderMarketCancelParams:
      type: object
      required:
        - market
        - asset_id
      properties:
        market:
          type: string
          description: Market (condition ID)
          example: '0x0000000000000000000000000000000000000000000000000000000000000001'
        asset_id:
          type: string
          description: Asset ID (token ID)
          example: 0xabc123def456...
    BookRequest:
      type: object
      required:
        - token_id
      properties:
        token_id:
          type: string
          description: Token ID (asset ID)
          example: 0xabc123def456...
        side:
          type: string
          description: Order side (optional, not used for midpoint calculation)
          enum:
            - BUY
            - SELL
          example: BUY
    FeeRate:
      type: object
      required:
        - base_fee
      properties:
        base_fee:
          type: integer
          format: int64
          description: Base fee in basis points
          example: 30
    TickSize:
      type: object
      required:
        - minimum_tick_size
      properties:
        minimum_tick_size:
          type: number
          format: double
          description: Minimum tick size (price increment)
          example: 0.01
    NegRisk:
      type: object
      required:
        - neg_risk
      properties:
        neg_risk:
          type: boolean
          description: Whether negative risk is enabled for this market
          example: false
    OrderSummary:
      type: object
      required:
        - price
        - size
      properties:
        price:
          type: string
          description: Order price
          example: '0.45'
        size:
          type: string
          description: Order size
          example: '100'
    OrderBookSummary:
      type: object
      required:
        - market
        - asset_id
        - timestamp
        - hash
        - bids
        - asks
        - min_order_size
        - tick_size
        - neg_risk
        - last_trade_price
      properties:
        market:
          type: string
          description: Market condition ID
          example: '0x1234567890123456789012345678901234567890'
        asset_id:
          type: string
          description: Token ID (asset ID)
          example: 0xabc123def456...
        timestamp:
          type: string
          description: Timestamp of the order book snapshot
          example: '1234567890'
        hash:
          type: string
          description: Hash of the order book summary
          example: a1b2c3d4e5f6...
        bids:
          type: array
          description: List of bid orders (sorted by price descending)
          items:
            $ref: '#/components/schemas/OrderSummary'
        asks:
          type: array
          description: List of ask orders (sorted by price ascending)
          items:
            $ref: '#/components/schemas/OrderSummary'
        min_order_size:
          type: string
          description: Minimum order size
          example: '1'
        tick_size:
          type: string
          description: Minimum price increment (tick size)
          example: '0.01'
        neg_risk:
          type: boolean
          description: Whether negative risk is enabled for this market
          example: false
        last_trade_price:
          type: string
          description: Last trade price
          example: '0.45'
    Rewards:
      type: object
      properties:
        rates:
          type: array
          items:
            type: object
            properties:
              asset_address:
                type: string
              rewards_daily_rate:
                type: number
                format: double
        min_size:
          type: number
          format: double
        max_spread:
          type: number
          format: double
    Token:
      type: object
      properties:
        token_id:
          type: string
        outcome:
          type: string
        price:
          type: number
          format: double
        winner:
          type: boolean
    SimplifiedMarket:
      type: object
      properties:
        condition_id:
          type: string
        rewards:
          $ref: '#/components/schemas/Rewards'
        tokens:
          type: array
          items:
            $ref: '#/components/schemas/Token'
        active:
          type: boolean
        closed:
          type: boolean
        archived:
          type: boolean
        accepting_orders:
          type: boolean
    PaginatedSimplifiedMarkets:
      type: object
      properties:
        limit:
          type: integer
        next_cursor:
          type: string
        count:
          type: integer
        data:
          type: array
          items:
            $ref: '#/components/schemas/SimplifiedMarket'
    ClobMarketDetails:
      type: object
      description: >-
        CLOB-level parameters for a market — tokens, tick size, base fees,
        rewards, RFQ status, and fee details.
      properties:
        gst:
          type: string
          format: date-time
          nullable: true
          description: >-
            Game start time (used for sports markets), ISO 8601 timestamp or
            null
        r:
          $ref: '#/components/schemas/ClobRewards'
        t:
          type: array
          description: Tokens for this market
          items:
            $ref: '#/components/schemas/ClobToken'
        mos:
          type: number
          format: float
          description: Minimum order size
          example: 5
        mts:
          type: number
          format: float
          description: Minimum tick size (price increment)
          example: 0.01
        mbf:
          type: integer
          format: int64
          description: Maker base fee in basis points
          example: 0
        tbf:
          type: integer
          format: int64
          description: Taker base fee in basis points
          example: 0
        rfqe:
          type: boolean
          description: Whether RFQ (Request for Quote) is enabled for this market
        itode:
          type: boolean
          description: >-
            Whether taker order delay is enabled for this market. When true,
            marketable orders are held for the 250 ms taker-delay window before
            synchronous processing. This field is omitted when false.
        ibce:
          type: boolean
          description: Whether Blockaid check is enabled
        fd:
          $ref: '#/components/schemas/FeeDetails'
        oas:
          type: integer
          description: Minimum order age in seconds
    ClobToken:
      type: object
      description: A token in a CLOB market with its ID and outcome label.
      properties:
        t:
          type: string
          description: The token ID
          example: >-
            71321045679252212594626385532706912750332728571942532289631379312455583992563
        o:
          type: string
          description: Outcome label for the token (e.g. "Yes", "No")
          example: 'Yes'
    FeeDetails:
      type: object
      description: Fee curve parameters for a market.
      properties:
        r:
          type: number
          format: float
          nullable: true
          description: Fee rate
          example: 0.02
        e:
          type: number
          format: float
          nullable: true
          description: Fee curve exponent
          example: 2
        to:
          type: boolean
          nullable: true
          description: Whether fees apply to takers only
          example: true
    ClobRewards:
      type: object
      description: Rewards configuration for a market.
      additionalProperties: true
    MarketByTokenResponse:
      type: object
      description: >-
        Response for GET /markets-by-token/{token_id} — condition ID and both
        token IDs in the market.
      required:
        - condition_id
        - primary_token_id
        - secondary_token_id
      properties:
        condition_id:
          type: string
          description: The condition ID of the market containing the given token
          example: '0xbd31dc8a20211944f6b70f31557f1001557b59905b7738480ca09bd4532f84af'
        primary_token_id:
          type: string
          description: The primary (Yes) token ID
          example: >-
            71321045679252212594626385532706912750332728571942532289631379312455583992563
        secondary_token_id:
          type: string
          description: The secondary (No) token ID
          example: >-
            52114319501245915516055106046884209969926127482827954674443846427813813222426
    Market:
      type: object
      properties:
        enable_order_book:
          type: boolean
        active:
          type: boolean
        closed:
          type: boolean
        archived:
          type: boolean
        accepting_orders:
          type: boolean
        accepting_order_timestamp:
          type: string
          format: date-time
        minimum_order_size:
          type: number
          format: double
        minimum_tick_size:
          type: number
          format: double
        condition_id:
          type: string
        question_id:
          type: string
        question:
          type: string
        description:
          type: string
        market_slug:
          type: string
        end_date_iso:
          type: string
          format: date-time
        game_start_time:
          type: string
          format: date-time
        seconds_delay:
          type: integer
        fpmm:
          type: string
        maker_base_fee:
          type: integer
          format: int64
        taker_base_fee:
          type: integer
          format: int64
        notifications_enabled:
          type: boolean
        neg_risk:
          type: boolean
        neg_risk_market_id:
          type: string
        neg_risk_request_id:
          type: string
        icon:
          type: string
        image:
          type: string
        rewards:
          $ref: '#/components/schemas/Rewards'
        is_50_50_outcome:
          type: boolean
        tokens:
          type: array
          items:
            $ref: '#/components/schemas/Token'
        tags:
          type: array
          items:
            type: string
    PaginatedMarkets:
      type: object
      properties:
        limit:
          type: integer
        next_cursor:
          type: string
        count:
          type: integer
        data:
          type: array
          items:
            $ref: '#/components/schemas/Market'
    LiveActivityMarket:
      type: object
      description: >-
        Minimal market information for live activity widgets (e.g., iOS Live
        Activities, Android widgets)
      properties:
        condition_id:
          type: string
          description: Unique identifier for the market condition
        id:
          type: integer
          description: Internal market ID
        question:
          type: string
          description: The market question being asked
        market_slug:
          type: string
          description: URL-friendly slug for the market
        event_slug:
          type: string
          description: URL-friendly slug for the parent event
        series_slug:
          type: string
          description: URL-friendly slug for the series (if applicable)
        icon:
          type: string
          description: URL to the market icon image
        image:
          type: string
          description: URL to the market image
        tags:
          type: array
          items:
            type: string
          description: List of tag slugs associated with this market
    MarketPrice:
      type: object
      properties:
        t:
          type: integer
          format: uint32
        p:
          type: number
          format: float
    PricesHistoryResponse:
      type: object
      properties:
        history:
          type: array
          items:
            $ref: '#/components/schemas/MarketPrice'
    BatchPricesHistoryRequest:
      type: object
      required:
        - markets
      properties:
        markets:
          type: array
          items:
            type: string
          description: List of market asset ids to query. Maximum 20.
          maxItems: 20
        start_ts:
          type: number
          format: double
          description: Filter by items after this unix timestamp (seconds).
        end_ts:
          type: number
          format: double
          description: Filter by items before this unix timestamp (seconds).
        interval:
          type: string
          enum:
            - max
            - all
            - 1m
            - 1w
            - 1d
            - 6h
            - 1h
          description: Time interval for data aggregation.
        fidelity:
          type: integer
          description: Accuracy of the data expressed in minutes. Default is 1 minute.
    BatchPricesHistoryResponse:
      type: object
      properties:
        history:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/MarketPrice'
          description: Map of market asset id to array of price data points.
    ApiKeyResponse:
      type: object
      required:
        - apiKey
        - secret
        - passphrase
      properties:
        apiKey:
          type: string
          description: UUID of the API key
          example: f4f247b7-4ac7-ff29-a152-04fda0a8755a
        secret:
          type: string
          description: Base64-encoded secret key for HMAC authentication
        passphrase:
          type: string
          description: Hex-encoded passphrase for secret decryption
    ApiKeysResponse:
      type: object
      required:
        - apiKeys
      properties:
        apiKeys:
          type: array
          description: Array of API key UUIDs
          items:
            type: string
          example:
            - f4f247b7-4ac7-ff29-a152-04fda0a8755a
            - a1b2c3d4-e5f6-7890-abcd-ef1234567890
    BalanceAllowanceResponse:
      type: object
      required:
        - balance
        - allowances
      properties:
        balance:
          type: string
          description: Balance amount in fixed-math with 6 decimals
          example: '1000000000000000000'
        allowances:
          type: object
          description: Map of spender addresses to allowance amounts
          additionalProperties:
            type: string
          example:
            '0x1234567890123456789012345678901234567890': '500000000000000000'
            '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd': '1000000000000000000'
    ClosedOnlyResponse:
      type: object
      description: Response containing the closed-only trading mode status
      properties:
        closed_only:
          type: boolean
          description: Whether the user is in closed-only trading mode
      required:
        - closed_only
    BuilderApiKeyResponse:
      type: object
      description: Response containing a newly created builder API key
      properties:
        key:
          type: string
          format: uuid
          description: Unique UUID identifier for the builder API key
        secret:
          type: string
          description: Base64-encoded secret key for HMAC authentication
        passphrase:
          type: string
          description: Hex-encoded passphrase for secret decryption
      required:
        - key
        - secret
        - passphrase
    Notification:
      type: object
      description: A notification event for the user
      properties:
        id:
          type: integer
          description: Unique identifier for the notification
        owner:
          type: string
          description: >-
            API key of the notification owner (empty for broadcast
            notifications)
        type:
          type: integer
          description: |
            Type of notification:
            - 1: Order cancellation
            - 2: Order fill
            - 3: Market registered
            - 4: Market resolved
            - 5: Reward payout
            - 6: Child comment created
          enum:
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
        payload:
          type: object
          description: Dynamic payload containing notification-specific data
          additionalProperties: true
        timestamp:
          type: integer
          description: Unix timestamp when the notification was created
      required:
        - id
        - type
        - payload
        - timestamp
    UserEarning:
      type: object
      description: User earnings for a specific market on a given day
      properties:
        date:
          type: string
          format: date-time
          description: Date of the earnings
        condition_id:
          type: string
          description: Condition ID of the market
        asset_address:
          type: string
          description: Address of the reward asset
        maker_address:
          type: string
          description: Address of the maker
        earnings:
          type: number
          format: double
          description: Amount of earnings in the asset
        asset_rate:
          type: number
          format: double
          description: Exchange rate of the asset
      required:
        - date
        - condition_id
        - asset_address
        - maker_address
        - earnings
    PaginatedUserEarnings:
      type: object
      description: Paginated list of user earnings
      properties:
        limit:
          type: integer
          description: Maximum number of items per page
        count:
          type: integer
          description: Number of items in the current response
        next_cursor:
          type: string
          description: Cursor for the next page. "LTE=" indicates the last page.
        data:
          type: array
          items:
            $ref: '#/components/schemas/UserEarning'
      required:
        - limit
        - count
        - next_cursor
        - data
    TotalUserEarning:
      type: object
      description: Total user earnings for a given day grouped by asset
      properties:
        date:
          type: string
          format: date-time
          description: Date of the earnings
        asset_address:
          type: string
          description: Address of the reward asset
        maker_address:
          type: string
          description: Address of the maker
        earnings:
          type: number
          format: double
          description: Total amount of earnings in the asset
        asset_rate:
          type: number
          format: double
          description: Exchange rate of the asset
      required:
        - date
        - asset_address
        - maker_address
        - earnings
        - asset_rate
    RewardsToken:
      type: object
      description: Token information for rewards markets
      properties:
        token_id:
          type: string
          description: Token ID
        outcome:
          type: string
          description: Outcome name (e.g., "YES", "NO")
        price:
          type: number
          format: double
          description: Current price of the token
      required:
        - token_id
        - outcome
    RewardsConfig:
      type: object
      description: Rewards configuration for a market
      properties:
        id:
          type: integer
          description: Rewards config ID
        asset_address:
          type: string
          description: Address of the reward asset
        start_date:
          type: string
          format: date
          description: Start date of the rewards period
        end_date:
          type: string
          format: date
          description: End date of the rewards period
        rate_per_day:
          type: number
          format: double
          description: Daily reward rate
        total_rewards:
          type: number
          format: double
          description: Total rewards amount
        remaining_reward_amount:
          type: number
          format: double
          description: Remaining reward amount
        total_days:
          type: integer
          description: Total number of days in the rewards period
      required:
        - asset_address
        - start_date
        - rate_per_day
    AssetEarning:
      type: object
      description: Earnings for a specific asset
      properties:
        asset_address:
          type: string
          description: Address of the reward asset
        earnings:
          type: number
          format: double
          description: Amount of earnings
        asset_rate:
          type: number
          format: double
          description: Exchange rate of the asset
      required:
        - asset_address
        - earnings
    UserRewardsMarket:
      type: object
      description: Market with user rewards earnings and configuration
      properties:
        condition_id:
          type: string
          description: Condition ID of the market
        market_id:
          type: string
          description: Market ID
        event_id:
          type: string
          description: Event ID
        question:
          type: string
          description: Market question
        market_slug:
          type: string
          description: URL slug for the market
        event_slug:
          type: string
          description: URL slug for the event
        image:
          type: string
          description: URL to market image
        rewards_max_spread:
          type: number
          description: Maximum spread for rewards eligibility
        rewards_min_size:
          type: number
          description: Minimum order size for rewards eligibility
        volume_24hr:
          type: number
          format: double
          description: 24-hour trading volume
        spread:
          type: number
          format: double
          description: Current spread
        market_competitiveness:
          type: number
          format: double
          description: Competitiveness score of the market
        tokens:
          type: array
          items:
            $ref: '#/components/schemas/RewardsToken'
        rewards_config:
          type: array
          items:
            $ref: '#/components/schemas/CurrentRewardConfig'
        maker_address:
          type: string
          description: Maker address
        earning_percentage:
          type: number
          format: double
          description: Percentage of total rewards the user is earning
        earnings:
          type: array
          items:
            $ref: '#/components/schemas/AssetEarning'
      required:
        - condition_id
        - market_id
        - question
        - tokens
    PaginatedUserRewardsMarkets:
      type: object
      description: Paginated list of user rewards markets
      properties:
        limit:
          type: integer
          description: Maximum number of items per page
        count:
          type: integer
          description: Number of items in the current response
        total_count:
          type: integer
          description: Total number of items across all pages
        next_cursor:
          type: string
          description: Cursor for the next page. "LTE=" indicates the last page.
        data:
          type: array
          items:
            $ref: '#/components/schemas/UserRewardsMarket'
      required:
        - limit
        - count
        - next_cursor
        - data
    CurrentRewardConfig:
      type: object
      description: Reward configuration entry for a current rewards market
      properties:
        id:
          type: integer
          description: Rewards config ID (always 0 on /rewards/markets/current)
        asset_address:
          type: string
          description: Address of the reward asset
        start_date:
          type: string
          format: date
          description: Start date of the rewards period
        end_date:
          type: string
          format: date
          description: End date of the rewards period
        rate_per_day:
          type: number
          format: double
          description: Daily reward rate
        total_rewards:
          type: number
          format: double
          description: Total rewards amount
      required:
        - asset_address
        - start_date
        - rate_per_day
    CurrentReward:
      type: object
      description: Current active reward configuration for a market
      properties:
        condition_id:
          type: string
          description: Condition ID of the market
        rewards_max_spread:
          type: number
          description: Maximum spread for rewards eligibility
        rewards_min_size:
          type: number
          description: Minimum order size for rewards eligibility
        rewards_config:
          type: array
          items:
            $ref: '#/components/schemas/CurrentRewardConfig'
        sponsored_daily_rate:
          type: number
          format: double
          description: Sponsored daily rate (omitted when zero)
        sponsors_count:
          type: integer
          description: Number of sponsors (omitted when zero)
        native_daily_rate:
          type: number
          format: double
          description: Computed native daily rate excluding sponsors (omitted when zero)
        total_daily_rate:
          type: number
          format: double
          description: Computed total daily rate including sponsors (omitted when zero)
      required:
        - condition_id
    PaginatedCurrentReward:
      type: object
      description: Paginated list of current reward configurations
      properties:
        limit:
          type: integer
          description: Maximum number of items per page
        count:
          type: integer
          description: Number of items in the current response
        next_cursor:
          type: string
          description: Cursor for the next page. "LTE=" indicates the last page.
        data:
          type: array
          items:
            $ref: '#/components/schemas/CurrentReward'
      required:
        - limit
        - count
        - next_cursor
        - data
    MarketReward:
      type: object
      description: Market with raw reward configurations
      properties:
        condition_id:
          type: string
          description: Condition ID of the market
        question:
          type: string
          description: Market question
        market_slug:
          type: string
          description: URL slug for the market
        event_slug:
          type: string
          description: URL slug for the event
        image:
          type: string
          description: URL to market image
        rewards_max_spread:
          type: number
          description: Maximum spread for rewards eligibility
        rewards_min_size:
          type: number
          description: Minimum order size for rewards eligibility
        market_competitiveness:
          type: number
          format: double
          description: Competitiveness score of the market
        tokens:
          type: array
          items:
            $ref: '#/components/schemas/RewardsToken'
        rewards_config:
          type: array
          items:
            $ref: '#/components/schemas/RewardsConfig'
      required:
        - condition_id
        - question
        - tokens
    PaginatedMarketReward:
      type: object
      description: Paginated list of market reward configurations
      properties:
        limit:
          type: integer
          description: Maximum number of items per page
        count:
          type: integer
          description: Number of items in the current response
        next_cursor:
          type: string
          description: Cursor for the next page. "LTE=" indicates the last page.
        data:
          type: array
          items:
            $ref: '#/components/schemas/MarketReward'
      required:
        - limit
        - count
        - next_cursor
        - data
    MultiMarketInfo:
      type: object
      description: Market with rewards configuration and trading metrics
      properties:
        condition_id:
          type: string
          description: Condition ID of the market
        event_id:
          type: string
          description: Event ID
        event_slug:
          type: string
          description: URL slug for the event
        created_at:
          type: string
          format: date-time
          description: Market creation timestamp
        group_item_title:
          type: string
          description: Title within an event group
        image:
          type: string
          description: URL to market image
        market_competitiveness:
          type: number
          format: double
          description: Competitiveness score of the market
        market_id:
          type: string
          description: Market ID
        market_slug:
          type: string
          description: URL slug for the market
        one_day_price_change:
          type: number
          format: double
          description: Price change over the last 24 hours
        question:
          type: string
          description: Market question
        rewards_max_spread:
          type: number
          description: Maximum spread for rewards eligibility
        rewards_min_size:
          type: number
          description: Minimum order size for rewards eligibility
        spread:
          type: number
          format: double
          description: Current spread
        end_date:
          type: string
          description: Market end date
        tokens:
          type: array
          items:
            $ref: '#/components/schemas/RewardsToken'
        volume_24hr:
          type: number
          format: double
          description: 24-hour trading volume
        rewards_config:
          type: array
          items:
            $ref: '#/components/schemas/RewardsConfig'
      required:
        - condition_id
        - market_id
        - question
        - tokens
    PaginatedMultiMarketInfo:
      type: object
      description: Paginated list of markets with rewards and trading metrics
      properties:
        limit:
          type: integer
          description: Maximum number of items per page
        count:
          type: integer
          description: Number of items in the current response
        next_cursor:
          type: string
          description: Cursor for the next page. "LTE=" indicates the last page.
        data:
          type: array
          items:
            $ref: '#/components/schemas/MultiMarketInfo'
      required:
        - limit
        - count
        - next_cursor
        - data
    HeartbeatResponse:
      type: object
      description: Response for heartbeat request
      required:
        - status
      properties:
        status:
          type: string
          description: Status of the heartbeat acknowledgment
          example: ok
    HeartbeatRequest:
      type: object
      description: Request body for heartbeat v1 endpoint
      required:
        - heartbeat_id
      properties:
        heartbeat_id:
          type: string
          description: |
            The heartbeat ID from the previous response. For the first request,
            this should be empty or a new UUID. Subsequent requests must use
            the heartbeat_id returned from the previous response.
          example: 550e8400-e29b-41d4-a716-446655440000
    HeartbeatV1Response:
      type: object
      description: Response for heartbeat v1 request
      required:
        - heartbeat_id
      properties:
        heartbeat_id:
          type: string
          format: uuid
          description: The new heartbeat ID to use in the next request
          example: 550e8400-e29b-41d4-a716-446655440000
    HeartbeatErrorResponse:
      type: object
      description: Error response when heartbeat ID doesn't match
      required:
        - error
        - heartbeat_id
      properties:
        error:
          type: string
          description: Error message
          example: Invalid Heartbeat ID
        heartbeat_id:
          type: string
          format: uuid
          description: The expected heartbeat ID that should have been used
          example: 550e8400-e29b-41d4-a716-446655440000
    OrderScoringResponse:
      type: object
      description: Response indicating whether an order is currently scoring for rewards
      required:
        - scoring
      properties:
        scoring:
          type: boolean
          description: Whether the order is currently scoring for maker rewards
          example: true
    OrdersScoringResponse:
      type: object
      description: >
        Map of order IDs to their scoring status.

        Each key is an order ID (order hash) and the value is a boolean
        indicating

        whether that order is currently scoring for maker rewards.
      additionalProperties:
        type: boolean
      example:
        '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890': true
        '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef': false
    Trade:
      type: object
      description: Trade information
      required:
        - id
        - taker_order_id
        - market
        - asset_id
        - side
        - size
        - price
        - status
        - match_time
        - last_update
        - outcome
        - bucket_index
        - owner
        - maker_address
        - trader_side
      properties:
        id:
          type: string
          description: Trade ID
          example: trade-123
        taker_order_id:
          type: string
          description: Taker order ID (hash)
          example: '0xabcdef1234567890abcdef1234567890abcdef12'
        market:
          type: string
          description: Market (condition ID)
          pattern: ^0x[a-fA-F0-9]{64}$
          example: '0x0000000000000000000000000000000000000000000000000000000000000001'
        asset_id:
          type: string
          description: Asset ID (token ID)
          example: >-
            15871154585880608648532107628464183779895785213830018178010423617714102767076
        side:
          type: string
          description: Trade side
          enum:
            - BUY
            - SELL
          example: BUY
        size:
          type: string
          description: Trade size
          example: '100000000'
        fee_rate_bps:
          type: string
          description: Fee rate in basis points
          example: '30'
        price:
          type: string
          description: Trade price
          example: '0.5'
        status:
          type: string
          description: Trade status
          enum:
            - TRADE_STATUS_CONFIRMED
            - TRADE_STATUS_FAILED
            - TRADE_STATUS_RETRYING
            - TRADE_STATUS_MATCHED
            - TRADE_STATUS_MINED
          example: TRADE_STATUS_CONFIRMED
        match_time:
          type: string
          description: Match time (Unix timestamp)
          example: '1700000000'
        match_time_nano:
          type: string
          description: Match time in nanoseconds
          example: '1700000000000000000'
        last_update:
          type: string
          description: Last update time (Unix timestamp)
          example: '1700000000'
        outcome:
          type: string
          description: Market outcome
          example: 'YES'
        bucket_index:
          type: integer
          description: Bucket index
          example: 0
        owner:
          type: string
          description: Owner UUID
          example: f4f247b7-4ac7-ff29-a152-04fda0a8755a
        maker_address:
          type: string
          description: Maker address
          pattern: ^0x[a-fA-F0-9]{40}$
          example: '0x1234567890123456789012345678901234567890'
        transaction_hash:
          type: string
          description: Transaction hash
          pattern: ^0x[a-fA-F0-9]{64}$
          example: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
        err_msg:
          type:
            - string
            - 'null'
          description: Error message (if any)
          example: null
        maker_orders:
          type: array
          description: Array of maker orders associated with this trade
          items:
            type: object
            properties:
              order_id:
                type: string
                description: Order ID (hash)
              owner:
                type: string
                description: Owner UUID
              maker_address:
                type: string
                description: Maker address
              matched_amount:
                type: string
                description: Matched amount
              price:
                type: string
                description: Price
              fee_rate_bps:
                type: string
                description: Fee rate in basis points
              asset_id:
                type: string
                description: Asset ID
              outcome:
                type: string
                description: Outcome
              side:
                type: string
                enum:
                  - BUY
                  - SELL
          example: []
        trader_side:
          type: string
          description: Trader side (TAKER or MAKER)
          enum:
            - TAKER
            - MAKER
          example: TAKER
    TradesResponse:
      type: object
      description: Paginated trades response
      required:
        - limit
        - next_cursor
        - count
        - data
      properties:
        limit:
          type: integer
          description: Maximum number of items per page
          example: 100
        next_cursor:
          type: string
          description: >-
            Cursor for next page (base64 encoded offset). "LTE=" indicates no
            more pages
          example: MTAw
        count:
          type: integer
          description: Number of items in current response
          example: 2
        data:
          type: array
          description: Array of trades
          items:
            $ref: '#/components/schemas/Trade'
    BuilderTrade:
      type: object
      description: Builder trade information
      required:
        - id
        - tradeType
        - takerOrderHash
        - builder
        - market
        - assetId
        - side
        - size
        - sizeUsdc
        - price
        - status
        - outcome
        - outcomeIndex
        - owner
        - maker
        - transactionHash
        - matchTime
        - bucketIndex
        - fee
        - feeUsdc
      properties:
        id:
          type: string
          description: Trade ID
          example: trade-123
        tradeType:
          type: string
          description: Trade type
          example: TAKER
        takerOrderHash:
          type: string
          description: Taker order hash
          example: '0xabcdef1234567890abcdef1234567890abcdef12'
        builder:
          type: string
          description: Builder code attributed to the trade
          pattern: ^0x[a-fA-F0-9]{64}$
          example: '0x0000000000000000000000000000000000000000000000000000000000000001'
        market:
          type: string
          description: Market (condition ID)
          pattern: ^0x[a-fA-F0-9]{64}$
          example: '0x0000000000000000000000000000000000000000000000000000000000000001'
        assetId:
          type: string
          description: Asset ID (token ID)
          example: >-
            15871154585880608648532107628464183779895785213830018178010423617714102767076
        side:
          type: string
          description: Trade side
          enum:
            - BUY
            - SELL
          example: BUY
        size:
          type: string
          description: Trade size
          example: '100000000'
        sizeUsdc:
          type: string
          description: Trade size in USDC
          example: '50000000'
        price:
          type: string
          description: Trade price
          example: '0.5'
        status:
          type: string
          description: Trade status
          example: TRADE_STATUS_CONFIRMED
        outcome:
          type: string
          description: Market outcome
          example: 'YES'
        outcomeIndex:
          type: integer
          description: Outcome index
          example: 0
        owner:
          type: string
          description: Owner UUID
          example: f4f247b7-4ac7-ff29-a152-04fda0a8755a
        maker:
          type: string
          description: Maker address
          pattern: ^0x[a-fA-F0-9]{40}$
          example: '0x1234567890123456789012345678901234567890'
        transactionHash:
          type: string
          description: Transaction hash
          pattern: ^0x[a-fA-F0-9]{64}$
          example: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
        matchTime:
          type: string
          description: Match time (Unix timestamp)
          example: '1700000000'
        bucketIndex:
          type: integer
          description: Bucket index
          example: 0
        fee:
          type: string
          description: Fee amount
          example: '300000'
        feeUsdc:
          type: string
          description: Fee amount in USDC
          example: '150000'
        err_msg:
          type:
            - string
            - 'null'
          description: Error message (if any)
          example: null
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp
          example: '2024-01-01T00:00:00Z'
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp
          example: '2024-01-01T00:00:00Z'
    BuilderTradesResponse:
      type: object
      description: Paginated builder trades response
      required:
        - limit
        - next_cursor
        - count
        - data
      properties:
        limit:
          type: integer
          description: Maximum number of items per page
          example: 300
        next_cursor:
          type: string
          description: >-
            Cursor for next page (base64 encoded offset). "LTE=" indicates no
            more pages
          example: MzAw
        count:
          type: integer
          description: Number of items in current response
          example: 2
        data:
          type: array
          description: Array of builder trades
          items:
            $ref: '#/components/schemas/BuilderTrade'
    RebatedFees:
      type: object
      description: Rebated fees for a maker on a specific market and date
      required:
        - date
        - condition_id
        - asset_address
        - maker_address
        - rebated_fees_usdc
      properties:
        date:
          type: string
          description: Date of the rebate (YYYY-MM-DD)
          example: '2026-02-27'
        condition_id:
          type: string
          description: Condition ID of the market
          example: '0xbd31dc8a20211944f6b70f31557f1001557b59905b7738480ca09bd4532f84af'
        asset_address:
          type: string
          description: Asset address (e.g. USDC contract)
          example: '0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB'
        maker_address:
          type: string
          description: Maker's Ethereum address
          example: '0xFeA4cB3dD4ca7CefD3368653B7D6FF9BcDFca604'
        rebated_fees_usdc:
          type: string
          description: Rebated fee amount in USDC
          example: '0.237519'