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

# Fills

> Endpoint providing fills by user address

This endpoint provides fill data for Hyperliquid user addresses.

<Info>
  **Drop-in Replacement**

  This endpoint is a 1-1 replacement for the `userFills`, `userFillsByTime` and `userTwapSliceFills` endpoints in Hyperliquid.
  The `userFillsByTime` endpoint does not have any limits on historical data retrieval.
</Info>


## OpenAPI

````yaml /_openapi/go-src-api.json POST /api/v1/developer/trading/hyperliquid/info/fills
openapi: 3.0.3
info:
  title: Hyperliquid API Server
  description: API server for Hyperliquid trading data including orders and fills
  version: 1.0.0
servers:
  - url: https://api.allium.so
    description: Production server
security: []
paths:
  /api/v1/developer/trading/hyperliquid/info/fills:
    post:
      summary: Get user fills
      description: >-
        Retrieve fill data for a user including regular fills and TWAP slice
        fills
      operationId: getUserFills
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HyperliquidGetFillsRequest'
            example:
              type: userFills
              user: '0x1234567890abcdef1234567890abcdef12345678'
              startTime: 1640995200000
              endTime: 1641081600000
              aggregateByTime: false
      responses:
        '200':
          description: Fills retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HyperliquidGetFillsResponse'
        '400':
          description: Bad request - Invalid type or missing required fields
          content:
            text/plain:
              schema:
                type: string
        '500':
          description: Internal server error
          content:
            text/plain:
              schema:
                type: string
      security:
        - APIKeyBearer: []
components:
  schemas:
    HyperliquidGetFillsRequest:
      type: object
      required:
        - type
        - user
      properties:
        type:
          type: string
          enum:
            - userFills
            - userFillsByTime
            - userTwapSliceFills
          description: Type of fills to retrieve. Applies to all request types.
        user:
          type: string
          description: User's wallet address (hex string). Applies to all request types.
        startTime:
          type: integer
          format: int64
          description: >-
            Start time filter (Unix timestamp in milliseconds). Required for
            userFillsByTime. Only applies to userFillsByTime.
        endTime:
          type: integer
          format: int64
          description: >-
            End time filter (Unix timestamp in milliseconds). Only applies to
            userFillsByTime.
        aggregateByTime:
          type: boolean
          description: >-
            When true, aggregates multiple fills from the same order at the same
            timestamp into a single fill with combined size, weighted average
            price, and summed fees/PnL. Only applies to userFills and
            userFillsByTime.
        twapMode:
          type: string
          enum:
            - none
            - include
            - only
          description: >-
            Controls TWAP fill filtering: 'none' (default) excludes TWAP fills,
            'include' returns both regular and TWAP fills, 'only' returns only
            TWAP fills. Only applies to userFills and userFillsByTime.
    HyperliquidGetFillsResponse:
      type: object
      properties:
        closedPnl:
          type: string
          nullable: true
          description: Realized PnL from closing a position with this fill
        coin:
          type: string
          nullable: true
          description: Trading pair symbol (e.g., BTC, ETH)
        crossed:
          type: boolean
          nullable: true
          description: Whether the order crossed the spread (i.e., was a taker order)
        dir:
          type: string
          nullable: true
          description: Direction description (e.g., Open Long, Close Short, Buy, Sell)
        hash:
          type: string
          nullable: true
          description: Transaction hash
        oid:
          type: integer
          nullable: true
          description: Order ID
        px:
          type: string
          nullable: true
          description: Execution price
        side:
          type: string
          nullable: true
          description: 'Order side: B (buy) or A (sell)'
        startPosition:
          type: string
          nullable: true
          description: Position size before this fill was executed
        sz:
          type: string
          nullable: true
          description: Fill size
        time:
          type: integer
          nullable: true
          description: Fill timestamp (Unix timestamp in milliseconds)
        fee:
          type: string
          nullable: true
          description: Trading fee amount
        feeToken:
          type: string
          nullable: true
          description: Token used for fee payment
        tid:
          type: integer
          nullable: true
          description: Unique trade ID
        liquidation:
          allOf:
            - $ref: '#/components/schemas/HyperliquidLiquidation'
          nullable: true
          description: Present only for liquidation fills. Contains liquidation details
        builderFee:
          type: string
          nullable: true
          description: Builder fee if order was routed through a builder
        builderAddress:
          type: string
          nullable: true
          description: Address of the builder if applicable
        twapId:
          type: integer
          nullable: true
          description: TWAP order ID if this fill is part of a TWAP order
    HyperliquidLiquidation:
      type: object
      properties:
        liquidatedUser:
          type: string
          nullable: true
          description: Wallet address of the user being liquidated
        markPx:
          type: string
          nullable: true
          description: Mark price at the time of liquidation
        method:
          type: string
          nullable: true
          description: Liquidation method used
  securitySchemes:
    APIKeyBearer:
      type: apiKey
      in: header
      name: X-API-KEY

````