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

# List fills

> The fills on the authenticated owner's orders, newest first. Takes the same X-Numo-Auth frame as GET /v1/orders; the owner is taken from it, never from a parameter. A trade between two of the owner's orders is listed once per order.

Returns the fills on your orders — every execution, at the price and size it traded — newest first.
Use it to reconcile balances trade by trade; [order history](/api-reference/endpoint/order-history)
gives the same activity summed per order.

<Note>
  Authentication is required, and the owner is taken from the signature, never from a parameter.
  The public [trades](/api-reference/endpoint/trades) feed lists every execution by order id but not
  by owner; this endpoint is what ties fills to an address.
</Note>

## Authentication

Send the same `X-Numo-Auth` frame as [order history](/api-reference/endpoint/order-history), signed
over the same message. One frame authorizes both endpoints until it expires, so a client that already
shows order history needs no second signature.

## Reading a fill

* `liquidity` is `taker` when your order crossed the book, `maker` when it rested and was hit.
* `side`, `price` and `size` are the engine's: your order's engine side, the price in USDC per cNGN,
  and the size in whole cNGN.
* On the spot market, `spot_contract.ui_intent` restates the fill in trader terms: `side` (`buy`
  acquires USDC), `price` in cNGN per USDC, and `size` as the USDC that changed hands.
* A trade between two of your own orders, on different subaccounts, is listed twice — once for each
  order — because each moved that account's balances. Both rows share a `trade_id`.

## Fees

`fee` is what your order paid on the fill, in USDC. Makers are never charged, so a maker fill's `fee`
is `0`. A taker fill carries the fee the venue charged: recorded when the fill executes, and filled in
exactly for fills from before fees were recorded. `fee` is absent only when the fee is not known.

`tx_hash` is the Base transaction that settled the fill. It is absent for fills recorded before
transaction hashes were stored.

## Retention

Fills are kept indefinitely. An order that traded is never pruned, even after it is cancelled or
expires, so its fills stay listed.

## Paging

Pages hold up to `limit` fills (default 50, maximum 100). When a page is full, the response includes
`next_before`; pass it back as `before` to fetch older fills. The last page has no `next_before`.


## OpenAPI

````yaml GET /v1/fills
openapi: 3.1.0
info:
  title: Numo orderbook API
  description: >-
    REST endpoints exposed by Numo's markets-service and execution-service for
    dollar stablecoins. Real-time book, trades, and order streams are served
    over the WebSocket endpoint documented in the WebSocket streams reference.
  version: 1.0.0
servers:
  - url: https://api.numofx.com
    description: markets-service
  - url: https://executor.numofx.com
    description: execution-service
security: []
tags:
  - name: Markets service
  - name: Execution service
paths:
  /v1/fills:
    get:
      tags:
        - Markets service
      summary: List fills
      description: >-
        The fills on the authenticated owner's orders, newest first. Takes the
        same X-Numo-Auth frame as GET /v1/orders; the owner is taken from it,
        never from a parameter. A trade between two of the owner's orders is
        listed once per order.
      operationId: listFills
      parameters:
        - name: X-Numo-Auth
          in: header
          required: true
          schema:
            type: string
          description: >-
            Base64url-encoded JSON auth frame {address, signature, nonce,
            issued_at, expiry}, signed with personal_sign over the order-history
            message. The same frame GET /v1/orders accepts.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: before
          in: query
          required: false
          schema:
            type: string
          description: >-
            The next_before value from the previous page, to page to older
            fills.
      responses:
        '200':
          description: One page of the owner's fills, newest first
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FillsResponse'
        '400':
          description: Invalid limit or before cursor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, malformed, expired or mismatched auth frame
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    FillsResponse:
      type: object
      required:
        - fills
      properties:
        fills:
          type: array
          items:
            $ref: '#/components/schemas/Fill'
        next_before:
          type: string
          description: Pass as before to fetch older fills. Absent on the last page.
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
    Fill:
      type: object
      required:
        - trade_id
        - order_id
        - liquidity
        - side
        - price
        - size
        - asset_address
        - sub_id
        - created_at
      properties:
        trade_id:
          type: integer
          description: The trade this fill belongs to, as on GET /v1/trades.
        order_id:
          type: string
          description: Your order that filled.
        liquidity:
          type: string
          enum:
            - taker
            - maker
          description: >-
            taker when your order crossed the book, maker when it rested and was
            hit.
        side:
          type: string
          enum:
            - buy
            - sell
          description: >-
            Your order's engine side. On the spot market, the inverse of
            spot_contract.ui_intent.side.
        price:
          type: string
          description: Engine price the fill executed at, in USDC per cNGN.
        size:
          type: string
          description: Engine size filled, in whole cNGN.
        asset_address:
          type: string
        sub_id:
          type: string
        created_at:
          type: string
          format: date-time
        market:
          type: string
        display_name:
          type: string
        fee:
          type: string
          description: >-
            What your order paid on the fill, in USDC. 0 for a maker fill; for a
            taker, the fee charged. Absent when not known.
        tx_hash:
          type: string
          description: >-
            The Base transaction that settled the fill. Absent for fills
            recorded before it was stored.
        spot_contract:
          $ref: '#/components/schemas/SpotContract'
          description: >-
            The fill in trader terms: ui_intent.size is the USDC that changed
            hands and balance_delta what the fill moved.
    SpotContract:
      type: object
      description: >-
        Present only on spot markets. Restates the raw engine order in
        trader-facing terms. Read ui_intent.price for a price in cNGN per USDC;
        the sibling price and limit_price fields are raw engine values in USDC
        per cNGN.
      properties:
        spec:
          type: string
          example: usdc_cngn_spot_v1
        ui_intent:
          $ref: '#/components/schemas/SpotUIIntent'
        engine_order:
          type: object
          description: >-
            The order as the matching engine sees it: cNGN traded against
            internal USDC cash.
          properties:
            side:
              type: string
              enum:
                - buy
                - sell
              description: Always the inverse of ui_intent.side.
            price:
              type: string
              description: Engine price in USDC per cNGN.
              example: '0.000728875182750367'
            amount:
              type: string
              description: Engine amount as a whole cNGN quantity.
              example: '1646'
        balance_delta:
          type: object
          description: Balance change if the order fills completely.
          properties:
            usdc:
              type: string
              example: '-1.199729'
            cngn:
              type: string
              example: '+1646'
    SpotUIIntent:
      type: object
      description: Trader-facing view of a spot order, in the units a UI displays.
      properties:
        side:
          type: string
          enum:
            - buy
            - sell
          description: >-
            buy acquires USDC and sells cNGN inventory; sell delivers USDC and
            buys cNGN inventory.
        price:
          type: string
          description: Price in cNGN per USDC. The reciprocal of the engine price.
          example: '1371.977018'
        size:
          type: string
          description: Size as a USDC notional.
          example: '1.199729'

````