> ## Documentation Index > Fetch the complete documentation index at: https://docs.fairground.fi/llms.txt > Use this file to discover all available pages before exploring further. # GetUserFills > Returns individual trade-history records (fills) for one wallet, optionally scoped to a time range. Results are ordered oldest first (ascending by block time). `limit` defaults to 100 and is capped at 500. ## OpenAPI ````yaml /developers/api-reference/openapi.yaml post /fill_history_service.v1.FillHistoryService/GetUserFills openapi: 3.1.0 info: title: Fairground.Fi API description: | API for the Fairground Perpetuals trading platform. This API uses ConnectRPC which accepts JSON over HTTP POST requests. All service endpoints follow the pattern: `/package.ServiceName/MethodName` version: 1.0.0 contact: name: Forte Service Company url: https://github.com/Forte-Service-Company-Ltd/perpetuals-api-server license: name: Proprietary identifier: UNLICENSED servers: - url: https://api.fairground.fi description: Production API server security: - bearerAuth: [] tags: - name: Trades description: Wallet trade/fill history - name: Markets description: Market configuration and summary endpoints - name: Orderbook description: Orderbook data retrieval - name: Orders description: Order management operations - name: Portfolio description: Aggregated per-wallet portfolio data - name: Positions description: Position management operations - name: Prices description: Oracle price and historical price data paths: /fill_history_service.v1.FillHistoryService/GetUserFills: post: tags: - Trades summary: GetUserFills description: |- Returns individual trade-history records (fills) for one wallet, optionally scoped to a time range. Results are ordered oldest first (ascending by block time). `limit` defaults to 100 and is capped at 500. operationId: fill_history_service.v1.FillHistoryService.GetUserFills parameters: - name: Connect-Protocol-Version in: header required: true schema: $ref: '#/components/schemas/connect-protocol-version' - name: Connect-Timeout-Ms in: header schema: $ref: '#/components/schemas/connect-timeout-header' requestBody: content: application/json: schema: $ref: '#/components/schemas/fill_history_service.v1.GetUserFillsRequest' required: true responses: '200': description: Success content: application/json: schema: $ref: >- #/components/schemas/fill_history_service.v1.GetUserFillsResponse example: fills: - fillId: 0x-abc123...-2 sequenceId: '48213002' timestamp: '2026-07-11T14:32:07Z' txHash: 0x-abc123... marketId: '1' market: BTC-PERP tradeType: EXECUTION_TYPE_TRADE side: SIDE_LONG owner: '0x71c7656ec7ab88b098defb751b7401b5f6d8976' orderId: '48213' positionId: '48213' reduceOnly: false size: '0.061500' price: '65000.500000' quoteNotional: '3997.780750' fees: amount: '1.80' asset: USDC rebates: amount: '0.00' asset: USDC positionSizeBefore: '0.000000' positionSizeAfter: '0.061500' components: schemas: connect-protocol-version: type: number title: Connect-Protocol-Version enum: - 1 description: Define the version of the Connect protocol. If omitted, use 1. const: 1 default: 1 connect-timeout-header: type: number title: Connect-Timeout-Ms description: Define the timeout, in ms fill_history_service.v1.GetUserFillsRequest: type: object properties: address: type: - string - 'null' title: address description: >- Wallet address to fetch fills for. A blank value returns `INVALID_ARGUMENT`. startTime: oneOf: - $ref: '#/components/schemas/google.protobuf.Timestamp' - type: 'null' title: start_time description: >- Optional inclusive lower bound on fill time. Omit to start from the earliest fill. endTime: oneOf: - $ref: '#/components/schemas/google.protobuf.Timestamp' - type: 'null' title: end_time description: >- Optional exclusive upper bound on fill time. Omit to include up to the most recent fill. limit: type: - integer - 'null' title: limit description: >- Maximum number of fills to return. Defaults to 100 when omitted; capped at 500. offset: type: - integer - 'null' title: offset description: >- Number of matching fills to skip before collecting results. Defaults to 0. title: GetUserFillsRequest required: - address additionalProperties: false fill_history_service.v1.GetUserFillsResponse: type: object properties: fills: type: array items: $ref: '#/components/schemas/base_objects.v1.FillInstance' title: fills description: Matching fills, ordered oldest first. title: GetUserFillsResponse additionalProperties: false google.protobuf.Timestamp: type: string examples: - '2023-01-15T01:30:15.01Z' - '2024-12-25T12:00:00Z' format: date-time base_objects.v1.FillInstance: type: object properties: fillId: type: string title: fill_id description: >- Deterministic unique ID, derived from the transaction hash and event index the fill occurred on. sequenceId: type: - integer - string title: sequence_id format: int64 description: Deterministic ordering key for this fill, unique within a market. timestamp: $ref: '#/components/schemas/google.protobuf.Timestamp' title: timestamp description: On-chain block timestamp when this fill's event was recorded. txHash: type: string title: tx_hash description: On-chain transaction hash for this fill. marketId: type: - integer - string title: market_id format: int64 description: On-chain market identifier. market: type: string title: market description: Human-readable market name, such as `BTC-PERP`. tradeType: $ref: '#/components/schemas/base_objects.v1.ExecutionType' title: trade_type description: >- How this fill was executed — a regular trade, a liquidation, or an ADL close-out. side: $ref: '#/components/schemas/base_objects.v1.Side' title: side description: Trade direction this fill applies to. owner: type: string title: owner description: EVM wallet address that owns the order this fill belongs to. orderId: type: - integer - string title: order_id format: int64 description: On-chain identifier of the order this fill executed against. positionId: type: - integer - string title: position_id format: int64 description: On-chain identifier of the position this fill affected. reduceOnly: type: boolean title: reduce_only description: Whether this fill was from a reduce-only order. size: type: string title: size description: >- Filled size for this event, in the base asset's units, as a decimal string. price: type: string title: price description: >- Execution price for this fill, in quote asset terms, as a decimal string. quoteNotional: type: string title: quote_notional description: >- Notional value of this fill (`size * price`), in quote asset terms, as a decimal string. fees: oneOf: - $ref: '#/components/schemas/base_objects.v1.AssetAmount' - type: 'null' title: fees description: Fee charged for this fill, if any. `null` when no fee was recorded. rebates: oneOf: - $ref: '#/components/schemas/base_objects.v1.AssetAmount' - type: 'null' title: rebates description: >- Rebate paid for this fill, if any. `null` when no rebate was recorded. positionSizeBefore: type: string title: position_size_before description: |- Position's total size immediately before this fill, as a signed decimal string in the base asset's units. positionSizeAfter: type: string title: position_size_after description: |- Position's total size immediately after this fill, as a signed decimal string in the base asset's units. title: FillInstance additionalProperties: false description: Main trade history record. base_objects.v1.ExecutionType: type: string title: ExecutionType enum: - EXECUTION_TYPE_UNSPECIFIED - EXECUTION_TYPE_TRADE - EXECUTION_TYPE_LIQUIDATION - EXECUTION_TYPE_ADL description: Type of execution for the trade record. base_objects.v1.Side: type: string title: Side enum: - SIDE_LONG - SIDE_SHORT description: Direction of the position represented by an order. base_objects.v1.AssetAmount: type: object properties: amount: type: string title: amount description: Decimal amount of the asset. asset: type: string title: asset description: Quote Asset symbol, e.g. USD title: AssetAmount additionalProperties: false description: Amount + asset pair for fees / rebates. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````