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

# Subscribe: Builder Code Fills

> Subscribe to the `builderFills` channel. Requires authentication (login first), and the logged-in account must own a builder code.

Streams every fill attributed to that builder code, across all accounts trading with it, one fill per message. There is no `markets` filter. Builder codes apply to perps only, so no spot fills arrive on this channel.

Subscribing without a builder code on the account returns `channel unsupported`; subscribing before logging in returns `login required`.

Messages are delivered only while subscribed, so a disconnect drops anything that fills in the meantime. After reconnecting, call `GET /v1/builder_code/fills` to recover the most recent fills and de-duplicate by `fillId`.



## OpenAPI

````yaml /api-reference/ws-spec.json post /ws/builderFills
openapi: 3.0.3
info:
  title: Ondo Perps WebSocket API
  version: '1.0'
  description: >-
    WebSocket API for Ondo Perps: real-time market data, order updates,
    positions, balance, funding, and more.


    ## Connection


    Connect via `wss://api.ondoperps.xyz/ws`. The server enforces a 32 KB max
    message size and a rate limit of 25 requests/second (burst 50).


    ## Authentication


    Public channels (market data) require no authentication. Private channels
    (orders, fills, positions, balance, etc.) require a `login` message first.


    ### JWT Login

    ```json

    {"op": "login", "args": {"token": "<JWT>"}}

    ```


    ### API Key Login

    ```json

    {"op": "login", "args": {"key": "<api_key_id>", "time": "<unix_ms>", "sign":
    "<hex_hmac>"}}

    ```


    Signature: `HMAC-SHA256(api_secret, time + "ondo_perps_ws_login" )`


    ## Heartbeat


    Send `{"op": "ping"}` periodically. The server responds with `{"type":
    "pong"}`. Connections idle for 180 seconds are closed.


    ## Message Format


    ### Client → Server

    All client messages use the `op` field: `ping`, `login`, `subscribe`,
    `unsubscribe`, `sendMessage`.


    ### Server → Client

    All server messages use the `type` field: `pong`, `loggedIn`, `subscribed`,
    `unsubscribed`, `update`, `error`.

    Channel data updates arrive as `{"type": "update", "channel": "<name>",
    "data": <payload>}`.
servers:
  - url: wss://api.ondoperps.xyz
    description: Production
security: []
paths:
  /ws/builderFills:
    post:
      tags:
        - Private Channels
      summary: 'Subscribe: Builder Code Fills'
      description: >-
        Subscribe to the `builderFills` channel. Requires authentication (login
        first), and the logged-in account must own a builder code.


        Streams every fill attributed to that builder code, across all accounts
        trading with it, one fill per message. There is no `markets` filter.
        Builder codes apply to perps only, so no spot fills arrive on this
        channel.


        Subscribing without a builder code on the account returns `channel
        unsupported`; subscribing before logging in returns `login required`.


        Messages are delivered only while subscribed, so a disconnect drops
        anything that fills in the meantime. After reconnecting, call `GET
        /v1/builder_code/fills` to recover the most recent fills and
        de-duplicate by `fillId`.
      operationId: subscribe_builderFills
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - op
                - channel
              properties:
                op:
                  type: string
                  enum:
                    - subscribe
                    - unsubscribe
                  example: subscribe
                  description: Operation type.
                channel:
                  type: string
                  enum:
                    - builderFills
                  example: builderFills
                  description: Channel for this subscription.
            example:
              op: subscribe
              channel: builderFills
      responses:
        '200':
          description: Channel update for `builderFills`
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - update
                  channel:
                    type: string
                    enum:
                      - builderFills
                  data:
                    $ref: '#/components/schemas/BuilderFill'
              example:
                type: update
                channel: builderFills
                data:
                  builderCodeFee: '0.2275'
                  fillId: 70a37d8f972f2494837f9dba8364cbb4
                  market: AAPL-USD.P
                  price: '227.50'
                  size: '5.00'
                  side: buy
                  time: '2026-09-28T14:32:07.123456Z'
components:
  schemas:
    BuilderFill:
      type: object
      description: >-
        One fill attributed to a builder code, as served by both the
        builderFills WebSocket channel and the builder-code fills endpoint.
      required:
        - builderCodeFee
        - fillId
        - market
        - price
        - size
        - side
        - time
      properties:
        builderCodeFee:
          type: string
          description: >-
            Exact, non-scientific decimal string containing the builder
            commission earned on this fill, in USDC. This is the charged amount,
            not the rate.
          example: '0.2275'
        fillId:
          type: string
          description: >-
            Unique fill identifier. Use it to de-duplicate overlap between a
            resynchronization response and live channel messages.
          example: 70a37d8f972f2494837f9dba8364cbb4
        market:
          type: string
          description: Market the fill traded in. Builder codes apply to perps only.
          example: AAPL-USD.P
        price:
          type: string
          description: Fill price as an exact decimal string.
          example: '227.50'
        size:
          type: string
          description: Fill quantity in the base asset, as an exact decimal string.
          example: '5.00'
        side:
          type: string
          enum:
            - buy
            - sell
          description: Side of the account that traded, not of the builder.
          example: buy
        time:
          type: string
          format: date-time
          description: Time the fill was created.
          example: '2026-09-28T14:32:07.123456Z'
      example:
        builderCodeFee: '0.2275'
        fillId: 70a37d8f972f2494837f9dba8364cbb4
        market: AAPL-USD.P
        price: '227.50'
        size: '5.00'
        side: buy
        time: '2026-09-28T14:32:07.123456Z'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.