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

# List fills

> List the authenticated wallet's fills (maker or taker side). **L2, permission `read`.**



## OpenAPI

````yaml /api-reference/openapi-clob-v1.yaml get /v1/fills
openapi: 3.1.0
info:
  title: Foresight CLOB Trading API v1
  version: 1.0.0
  description: >
    Public-facing CLOB (central-limit order book) REST API for the Foresight

    prediction-market platform.


    This is a **different API from the legacy AMM Trade API** (`/trade/*`). The

    CLOB API trades signed limit/market orders against an order book instead of

    swapping against an automated market maker.


    ## Base URL


    ```

    https://api.foresight.now

    ```


    All routes below are prefixed with `/v1`.


    ## Auth tiers


    - **L0** — public, no credentials (all market-data routes).

    - **L1** — Privy JWT (`Authorization: Bearer <jwt>`); used for API-key
    management.

    - **L2** — Privy JWT **or** API-key headers (`fs-api-key` +
    `fs-api-secret`); used for trading and private reads.


    ## Market identity


    A market is identified by the pair **`condition_id`** (on-chain
    ConditionalTokens

    condition hash) + **`chain_id`** (blockchain network id). Internal database

    identifiers are never exposed.


    The CLOB currently runs on **BNB Smart Chain (BSC) mainnet — `chain_id:
    56`**.

    The collateral token on BSC has **18 decimals**. Always read the
    authoritative

    `decimals` from `GET /v1/markets/{condition_id}/tokens` rather than
    hard-coding

    it — amount math signed at the wrong scale is rejected at ingest.


    ## Async matching


    `POST /v1/orders` always returns `status: OPEN`. Matching runs in a
    background

    worker; matched / partial / failed transitions arrive on the private `user`

    WebSocket channel (`wss://api.foresight.now/v1/ws`).


    ## Error envelope


    Every non-2xx response is shaped as (all field names snake_case):


    ```json

    {
      "correlation_id": "abc-123",
      "code": "NOT_FOUND",
      "message": "Market not found",
      "status_code": 404,
      "timestamp": "2026-06-03T10:15:30.000Z",
      "path": "/v1/markets/0x.../book"
    }

    ```
servers:
  - url: https://api.foresight.now
    description: Production
  - url: http://localhost:3000
    description: Local development
security: []
tags:
  - name: Auth
    description: API-key lifecycle and WebSocket token issuance.
  - name: Market Data
    description: Public markets, orderbook, ticker, trades, tokens. L0 — no auth.
  - name: Orders
    description: Place, list, and cancel signed EIP-712 orders. L2.
  - name: Fills
    description: Authenticated wallet's fill history. L2.
  - name: Positions
    description: Authenticated wallet's CLOB positions. L2.
paths:
  /v1/fills:
    get:
      tags:
        - Fills
      summary: List fills
      description: >-
        List the authenticated wallet's fills (maker or taker side). **L2,
        permission `read`.**
      parameters:
        - in: query
          name: condition_id
          schema:
            type: string
        - in: query
          name: chain_id
          schema:
            type: integer
            example: 56
        - in: query
          name: trade_ids
          schema:
            type: string
          description: >-
            Optional. Comma-separated or repeated trade ids (max 100). Results
            stay scoped to your own fills.
        - $ref: '#/components/parameters/CursorQuery'
        - $ref: '#/components/parameters/LimitQuery'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FillsListResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
        - PrivyJWT: []
        - ApiKey: []
          ApiSecret: []
components:
  parameters:
    CursorQuery:
      in: query
      name: cursor
      schema:
        type: string
        nullable: true
      description: Opaque cursor from the prior response's `next_cursor`.
    LimitQuery:
      in: query
      name: limit
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
  schemas:
    FillsListResponse:
      allOf:
        - $ref: '#/components/schemas/PaginatedEnvelope'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/Fill'
    PaginatedEnvelope:
      type: object
      required:
        - data
        - next_cursor
        - has_more
      properties:
        data:
          type: array
          items: {}
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    Fill:
      type: object
      properties:
        trade_id:
          type: string
        order_hash:
          type: string
          description: Your own order hash for this fill.
        condition_id:
          type: string
        chain_id:
          type: integer
          example: 56
        role:
          type: string
          enum:
            - maker
            - taker
        side:
          type: string
          enum:
            - BUY
            - SELL
        outcome:
          type: integer
          enum:
            - 0
            - 1
        price:
          type: string
        size:
          type: string
        fee:
          type: string
          description: Fee for this fill, as a decimal string.
        settlement_status:
          type: string
          enum:
            - PENDING
            - SETTLED
            - FAILED
        tx_hash:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
    Error:
      type: object
      required:
        - correlation_id
        - code
        - message
        - status_code
        - timestamp
        - path
      properties:
        correlation_id:
          type: string
          description: Request correlation id; falls back to `"unknown"` when none is set.
        code:
          type: string
          example: NOT_FOUND
        message:
          type: string
        status_code:
          type: integer
          example: 404
        timestamp:
          type: string
          format: date-time
        path:
          type: string
          example: /v1/markets/0x.../book
  responses:
    ErrorResponse:
      description: Error envelope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    PrivyJWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Privy-issued JWT. Required for L1 routes; accepted on L2 routes.
    ApiKey:
      type: apiKey
      in: header
      name: fs-api-key
      description: >-
        API key id issued by `POST /v1/auth/api-keys`. Pair with
        `fs-api-secret`.
    ApiSecret:
      type: apiKey
      in: header
      name: fs-api-secret
      description: Plaintext secret returned once at API-key creation.

````