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

# List partner fills

> Each fee event on a position opened through your builder codes, oldest first: its opening, claims and sale back to the vault, with the wallet that acted, the fee and the transaction, whose fees add up to GET /v1/partner/report's total_fees for the same range.

Requires your partner server key (`tpk_`), sent from your server with no `Origin`; an API key cannot call it.



## OpenAPI

````yaml /hyperliquid/openapi.json get /v1/partner/fills
openapi: 3.1.1
info:
  title: Totalis Hyperliquid API
  description: >-
    REST API for Totalis singles and parlays on Hyperliquid HIP-4 outcome
    markets, for client integrations and external market makers.


    There are three ways in, each sent as `Authorization: Bearer <credential>`:


    - **Scoped API key** (`ttk_`), for servers, bots and market makers. The
    account owner creates it in the Totalis app, or a wallet-session user
    creates one with `POST /v1/me/api-keys` and a fresh wallet signature (see
    API keys). It acts for one account, yours or a maker's, with only the scopes
    it holds, and needs no `Origin`.

    - **Wallet session**, for users who bring their own wallet to a partner's
    web page. The page signs the wallet in with `POST
    /v1/auth/wallet-challenges` and `POST /v1/auth/wallet-sessions`; the session
    is bound to the page's registered `Origin` and must be sent from it. Pages
    may also label their traffic with their publishable browser key in
    `X-Totalis-Partner: tpb_...`.

    - **Partner server key** (`tpk_`), only for `POST
    /v1/partner/wallet-admissions`, which lets a new wallet open its account
    during the invite-only launch, `GET /v1/partner/report`, your fees, terms
    and payouts, `GET /v1/partner/fills`, each fee event on your users'
    positions, `GET /v1/partner/webhook-events`, the webhook events Totalis
    queued for you, and `GET /v1/partner/accounts/{wallet}/account-value`, the
    value of an account you admitted. Server to server, never in a browser, and
    never with an `Origin`.


    Public market reads need no credential. A credential only authenticates:
    every bet, cash-out and withdrawal also carries the wallet or maker
    signature the HyperEVM contract verifies. An external wallet sends `POST
    /v1/core-exits` to move its vault cash to HyperCore before a HyperCore
    order.


    For access, partner credentials (origins, browser and server keys), builder
    codes or staging, email
    [founders@totalis.trade](mailto:founders@totalis.trade).


    Amounts are base-10 strings in native USDC atomic units, large identifiers
    are decimal strings, and every command `POST` requires an `Idempotency-Key`
    header.


    Every error is `{error: {code, message, retry, request_id,
    field_violations}}`. `code` is stable; each operation lists the codes it
    returns per status. `retry` is `NEVER` (stop), `BACKOFF` (resend the same
    request with the same `Idempotency-Key` after `Retry-After` seconds) or
    `REFRESH` (re-read state, then send a new request with a new key).
    `field_violations` names invalid inputs by JSON pointer, such as
    `/legs/0/side`.
  version: 239.0.0-maker-opened-via
servers:
  - url: https://hip4-api.totalis.trade
    description: Production public edge
  - url: https://hip4-api-staging.totalis.trade
    description: Staging and chain-998 public edge
security: []
tags:
  - name: Markets
    description: >-
      HIP-4 questions and markets, their sides and price history. No API key
      needed.
  - name: RFQs & Quotes
    description: >-
      RFQs and the quotes that answer them: what a taker calls, then what a
      maker calls.
  - name: Positions
    description: Positions the account holds, or its maker backs.
  - name: Account
    description: >-
      The account a key acts for: identity, balances, activity, operations,
      withdrawals, deposits and HyperCore exits.
  - name: Makers
    description: >-
      The rest of a maker's setup after Making: admission, quote history,
      capital and collateral.
  - name: Partners & wallet sign-in
    description: >-
      A partner admits its users' own wallets, which sign in from the partner's
      pages, and reads its own report, fills, webhook events and its users'
      account values.
  - name: API keys
    description: >-
      Issue, rotate and revoke scoped keys from a wallet session. An API key
      cannot manage keys.
  - name: Deployment
    description: The contract deployment every signature is made against.
  - name: WebSocket
    description: The authenticated WebSocket for account and maker updates.
paths:
  /v1/partner/fills:
    get:
      tags:
        - Partners & wallet sign-in
      summary: List partner fills
      description: >-
        Each fee event on a position opened through your builder codes, oldest
        first: its opening, claims and sale back to the vault, with the wallet
        that acted, the fee and the transaction, whose fees add up to GET
        /v1/partner/report's total_fees for the same range.


        Requires your partner server key (`tpk_`), sent from your server with no
        `Origin`; an API key cannot call it.
      operationId: listPartnerFills
      parameters:
        - name: from
          in: query
          required: false
          schema:
            type: string
            pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
          description: >-
            First UTC day of the range, inclusive. Send from and to together, at
            most 366 days apart; omit both for the 30 days through today.
          example: '2026-10-01'
        - name: to
          in: query
          required: false
          schema:
            type: string
            pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
          description: >-
            UTC day after the range, exclusive: `from=2026-10-01&to=2026-11-01`
            is October.
          example: '2026-11-01'
        - name: cursor
          in: query
          required: false
          description: >-
            Omit for the first fills in the range; then send a previous
            response's next_cursor unchanged.
          schema:
            $ref: '#/components/schemas/PageCursor'
          example: v1:21987305:0
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A page of your fills. No caching.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerFillPage'
              example:
                fills:
                  - kind: ACCEPT
                    wallet: '0x1111111111111111111111111111111111111111'
                    position_id: >-
                      0x7a3c9e1f00000000000000000000000000000000000000000000000000000001
                    legs:
                      - outcome_id: '1201'
                        side: 'YES'
                      - outcome_id: '1207'
                        side: 'NO'
                    amount: '25000000'
                    fee: '375000'
                    stake: '24962500'
                    payout: '61000000'
                    share_bps: 2000
                    time: '2026-11-03T14:02:11Z'
                    block_number: 21904412
                    log_index: 3
                    transaction_hash: >-
                      0x5b0e8d2a00000000000000000000000000000000000000000000000000000001
                  - kind: CASH_OUT
                    wallet: '0x1111111111111111111111111111111111111111'
                    position_id: >-
                      0x7a3c9e1f00000000000000000000000000000000000000000000000000000001
                    legs:
                      - outcome_id: '1201'
                        side: 'YES'
                      - outcome_id: '1207'
                        side: 'NO'
                    amount: '41000000'
                    fee: '253875'
                    stake: '24962500'
                    payout: '61000000'
                    share_bps: 2000
                    time: '2026-11-04T19:40:52Z'
                    block_number: 21987305
                    log_index: 0
                    transaction_hash: >-
                      0x5b0e8d2a00000000000000000000000000000000000000000000000000000002
                next_cursor: v1:21987305:0
                has_more: true
        '400':
          description: >-
            `INVALID_QUERY`: from or to is not a YYYY-MM-DD date, only one was
            sent, from is not before to, they are more than 366 days apart, or
            limit is not 1 to 200. `INVALID_CURSOR`: the cursor is not one this
            endpoint returned.


            - `INVALID_QUERY` (retry `NEVER`): A query parameter is malformed,
            out of range or not accepted by this operation. `field_violations`
            names it.

            - `INVALID_CURSOR` (retry `NEVER`): The cursor is malformed or was
            issued for a different query.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Error'
                  - properties:
                      error:
                        description: The error this operation returns with this status.
                        properties:
                          code:
                            description: >-
                              One of the registered codes listed in this
                              response's description.
                            enum:
                              - INVALID_QUERY
                              - INVALID_CURSOR
                          retry:
                            description: >-
                              The retry rule the registry fixes for the returned
                              code.
                            enum:
                              - NEVER
        '401':
          description: >-
            The partner server key is missing, unknown or revoked, or your
            partner is suspended.


            - `UNAUTHENTICATED` (retry `NEVER`): The credential is missing,
            invalid, expired or revoked.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Error'
                  - properties:
                      error:
                        description: The error this operation returns with this status.
                        properties:
                          code:
                            description: >-
                              One of the registered codes listed in this
                              response's description.
                            enum:
                              - UNAUTHENTICATED
                          retry:
                            description: >-
                              The retry rule the registry fixes for the returned
                              code.
                            enum:
                              - NEVER
        '403':
          description: >-
            Any credential but a partner server key, or any request with an
            `Origin`, is refused: read fills from your server.


            - `FORBIDDEN` (retry `NEVER`): The credential is valid but lacks the
            scope, permission or role this operation needs.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Error'
                  - properties:
                      error:
                        description: The error this operation returns with this status.
                        properties:
                          code:
                            description: >-
                              One of the registered codes listed in this
                              response's description.
                            enum:
                              - FORBIDDEN
                          retry:
                            description: >-
                              The retry rule the registry fixes for the returned
                              code.
                            enum:
                              - NEVER
        '429':
          description: >-
            - `RATE_LIMITED` (retry `BACKOFF`): The request quota for this
            credential or route is exhausted.
          headers:
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Error'
                  - properties:
                      error:
                        description: The error this operation returns with this status.
                        properties:
                          code:
                            description: >-
                              One of the registered codes listed in this
                              response's description.
                            enum:
                              - RATE_LIMITED
                          retry:
                            description: >-
                              The retry rule the registry fixes for the returned
                              code.
                            enum:
                              - BACKOFF
        '503':
          description: >-
            Fills are temporarily unavailable; resend after `Retry-After`.


            - `AUTHORIZATION_UNAVAILABLE` (retry `BACKOFF`): Identity or
            credential authority storage is unavailable.

            - `SOURCE_UNAVAILABLE` (retry `BACKOFF`): The account-read or stream
            source is unavailable.
          headers:
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Error'
                  - properties:
                      error:
                        description: The error this operation returns with this status.
                        properties:
                          code:
                            description: >-
                              One of the registered codes listed in this
                              response's description.
                            enum:
                              - AUTHORIZATION_UNAVAILABLE
                              - SOURCE_UNAVAILABLE
                          retry:
                            description: >-
                              The retry rule the registry fixes for the returned
                              code.
                            enum:
                              - BACKOFF
      security:
        - partnerServerKey: []
components:
  schemas:
    PageCursor:
      type: string
      minLength: 1
      maxLength: 2048
      description: >-
        Opaque list cursor. Send a previous response's next_cursor back
        unchanged; never build or parse one.
    PartnerFillPage:
      type: object
      required:
        - fills
        - next_cursor
        - has_more
      properties:
        fills:
          type: array
          maxItems: 200
          items:
            $ref: '#/components/schemas/PartnerFill'
          description: Fills, oldest first.
        next_cursor:
          $ref: '#/components/schemas/NextCursor'
          description: >-
            Send it as cursor for the fills after this page. It follows the last
            fill even when has_more is false, so keep it and read again later,
            with the same from and a later to, for new fills. Null only when no
            fill has been returned yet.
        has_more:
          type: boolean
          description: Whether more fills follow in the range.
    Error:
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
          description: The one error this request failed with.
      required:
        - error
      type: object
    PageLimit:
      type: integer
      minimum: 1
      maximum: 200
      default: 50
      description: >-
        Maximum items in one page. A page may hold fewer, even none, while
        has_more is true.
    PartnerFill:
      type: object
      required:
        - kind
        - wallet
        - position_id
        - legs
        - amount
        - fee
        - stake
        - payout
        - share_bps
        - time
        - block_number
        - log_index
        - transaction_hash
      description: >-
        One fee event on a position opened through your builder codes. Amounts
        are atomic USDC (6 decimals) decimal strings.
      properties:
        kind:
          type: string
          enum:
            - ACCEPT
            - CLAIM
            - CASH_OUT
          description: >-
            ACCEPT: the position opened, and amount is its stake with the taker
            fee. CLAIM: a claim paid amount, before the profit fee. CASH_OUT:
            the vault bought the position back for amount.
        wallet:
          $ref: '#/components/schemas/LowercaseNonZeroAddress'
          description: >-
            The wallet that acted: the one that opened or claimed, or the
            seller.
        position_id:
          $ref: '#/components/schemas/Bytes32'
          description: The position, as GET /v1/me/positions names it.
        legs:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/CommonLeg'
          description: 'The position''s legs: one for a single, more for a Combo.'
        amount:
          $ref: '#/components/schemas/CommonAmount'
          description: What the event moved, as kind says.
        fee:
          $ref: '#/components/schemas/CommonAmount'
          description: >-
            The fee the vault took: the taker fee on ACCEPT, the profit fee on
            CLAIM and CASH_OUT. Zero when none was due.
        stake:
          $ref: '#/components/schemas/CommonAmount'
          description: The position's stake after the taker fee, as it opened.
        payout:
          $ref: '#/components/schemas/CommonAmount'
          description: >-
            What the position pays if every leg wins; stake over payout is the
            price it opened at.
        share_bps:
          anyOf:
            - type: integer
              minimum: 0
              maximum: 10000
            - type: 'null'
          description: >-
            Your share of fees, in basis points, under the terms in force on the
            fill's UTC day; null before your first terms. Each terms period's
            share is rounded down once, so per-fill shares do not add up exactly
            to what you are owed.
        time:
          $ref: '#/components/schemas/CommonTimestamp'
          description: HyperEVM block time.
        block_number:
          type: integer
          minimum: 0
          description: HyperEVM block.
        log_index:
          type: integer
          minimum: 0
          description: >-
            The event's log index in its block; with block_number it identifies
            the fill.
        transaction_hash:
          $ref: '#/components/schemas/Bytes32'
          description: The HyperEVM transaction.
    NextCursor:
      type:
        - string
        - 'null'
      minLength: 1
      maxLength: 2048
      description: Opaque cursor for the next page, or null when has_more is false.
    ErrorDetail:
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
          description: Stable registered code; branch on this, not on message or status.
        field_violations:
          description: >-
            Each invalid input by JSON pointer; empty when the error is not
            about a specific input.
          items:
            $ref: '#/components/schemas/FieldViolation'
          type: array
        message:
          description: Human-readable; may change without notice.
          minLength: 1
          type: string
        request_id:
          description: >-
            UUIDv7 of this request, also returned in the X-Request-ID header.
            Quote it when reporting a problem.
          format: uuid
          pattern: >-
            ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
          type: string
        retry:
          $ref: '#/components/schemas/Retry'
          description: What the caller should do next; fixed by the registry for each code.
      required:
        - code
        - message
        - retry
        - request_id
        - field_violations
      type: object
    LowercaseNonZeroAddress:
      type: string
      pattern: ^0x[0-9a-f]{40}$
      not:
        const: '0x0000000000000000000000000000000000000000'
    Bytes32:
      type: string
      pattern: ^0x[0-9a-f]{64}$
    CommonLeg:
      type: object
      additionalProperties: false
      required:
        - outcome_id
        - side
      properties:
        outcome_id:
          $ref: '#/components/schemas/UInt32String'
          description: >-
            HIP-4 outcome ID the leg is on, as a decimal string. The signed Leg
            encodes it as uint32.
        side:
          $ref: '#/components/schemas/Side'
          description: >-
            Outcome side the leg backs. The signed Leg encodes YES as 0 and NO
            as 1.
      description: One (outcome, side) pair, as markets and positions name it.
    CommonAmount:
      type: string
      pattern: ^(0|[1-9][0-9]*)$
      maxLength: 39
      format: uint128-decimal
    CommonTimestamp:
      type: string
      format: date-time
      pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}([.][0-9]{1,9})?Z$
      maxLength: 30
    ErrorCode:
      description: >-
        Stable HTTP error code. Each code has one HTTP status and one retry
        value.
      enum:
        - INVALID_REQUEST
        - INVALID_QUERY
        - INVALID_CURSOR
        - INVALID_IDEMPOTENCY_KEY
        - ORIGIN_REQUIRED
        - SUBPROTOCOL_REQUIRED
        - UNSUPPORTED_BROWSE_CONTRACT
        - UNAUTHENTICATED
        - FORBIDDEN
        - ORIGIN_NOT_ALLOWED
        - ACCESS_REQUIRED
        - SIGN_IN_REQUIRED
        - NOT_FOUND
        - IDENTITY_NOT_FOUND
        - QUOTE_NOT_FOUND
        - INVITE_CODE_NOT_FOUND
        - IDEMPOTENCY_KEY_REUSED
        - STATE_CONFLICT
        - INVITE_CODE_EXHAUSTED
        - STALE_CURSOR
        - CURSOR_EXPIRED
        - CURSOR_RESET
        - RECURRING_DEFINITION_CONFLICT
        - EMBEDDED_WALLET_CONFLICT
        - SECRET_UNAVAILABLE
        - ROTATION_IN_PROGRESS
        - TELEMETRY_CONFLICT
        - RFQ_NOT_CANCELLABLE
        - RFQ_NOT_OPEN
        - RFQ_GENERATION_STALE
        - RFQ_GENERATION_IN_FLIGHT
        - QUOTE_EXPIRED
        - QUOTE_CANCELLED
        - QUOTE_REPLACED
        - QUOTE_SIGNER_CHANGED
        - QUOTE_CAPACITY_EXCEEDED
        - CORE_ACCOUNT_NOT_READY
        - CORE_ACCOUNT_ACTIVATION_REQUIRED
        - CORE_EXIT_ABANDONED
        - CORE_MOVE_IN_FLIGHT
        - ACCEPTANCE_IN_FLIGHT
        - USERNAME_TAKEN
        - USERNAME_ALREADY_SET
        - USERNAME_REQUIRED
        - GOLDEN_TICKET_NONE
        - GOLDEN_TICKET_USED
        - GOLDEN_TICKET_EXPIRED
        - GOLDEN_PLACEMENT_IN_FLIGHT
        - GOLDEN_PROMO_BUSY
        - GOLDEN_CASHOUT_REFUSED
        - GOLDEN_OFFER_BELOW_FLOOR
        - GOLDEN_GIFT_TERMS_EXPIRED
        - GOLDEN_UNLOCK_REQUIRED
        - GOLDEN_GIVEN_OUT
        - GOLDEN_CODE_DISABLED
        - X_REQUIRED
        - X_ALREADY_CLAIMED
        - GOLDEN_NOT_ELIGIBLE
        - INVALID_SIGNATURE
        - WALLET_CONTRACT_UNSUPPORTED
        - WRONG_AUTHORITY
        - KEY_LIMIT_REACHED
        - USERNAME_NOT_ALLOWED
        - FOLLOW_SELF
        - FOLLOW_LIMIT_REACHED
        - GOLDEN_LEG_COUNT
        - GOLDEN_LEG_NOT_ELIGIBLE
        - GOLDEN_QUOTE_NOT_HOUSE
        - RATE_LIMITED
        - CONNECTION_LIMIT
        - RFQ_INTENT_LIMIT
        - QUOTE_EXPOSURE_LIMIT
        - DEPENDENCY_STALE
        - AUTHORIZATION_UNAVAILABLE
        - SOURCE_UNAVAILABLE
        - CONTRACT_UNAVAILABLE
        - MARKET_DATA_UNAVAILABLE
        - BROWSE_UNAVAILABLE
        - FINANCIAL_ACTIONS_DISABLED
        - CORE_EXIT_UNAVAILABLE
        - COLLATERAL_REDUCTION_UNAVAILABLE
        - SPONSORSHIP_UNAVAILABLE
        - CONTRACT_SIGNATURE_OVERLOADED
        - QUOTE_EXPOSURE_STALE
        - COMBO_AUTOMATIC_DISABLED
        - GAS_PRICE_ABOVE_CEILING
        - EXECUTION_BACKLOG_FULL
        - EMBEDDED_WALLET_UNAVAILABLE
        - GOLDEN_PROMO_FUNDS_LOW
        - X_VERIFICATION_UNAVAILABLE
        - CONNECTION_DRAIN
      type: string
    FieldViolation:
      properties:
        code:
          description: >-
            REQUIRED: the input is missing. INVALID: it is present but malformed
            or out of range. UNEXPECTED: the input is not accepted here.
          enum:
            - REQUIRED
            - INVALID
            - UNEXPECTED
          type: string
        field:
          description: >-
            JSON pointer into the body, or into the query parameters as one flat
            object for requests without a body, for example /legs/0/stake or
            /limit.
          pattern: ^(/([^~/]|~[01])*)+$
          type: string
      required:
        - field
        - code
      type: object
    Retry:
      description: >-
        NEVER: stop. BACKOFF: resend the same request with the same
        Idempotency-Key after Retry-After. REFRESH: re-read state, then send a
        new request with a new Idempotency-Key.
      enum:
        - NEVER
        - BACKOFF
        - REFRESH
      type: string
    UInt32String:
      type: string
      pattern: >-
        ^(0|[1-9][0-9]{0,8}|[1-3][0-9]{9}|4[01][0-9]{8}|42[0-8][0-9]{7}|429[0-3][0-9]{6}|4294[0-8][0-9]{5}|42949[0-5][0-9]{4}|429496[0-6][0-9]{3}|4294967[0-1][0-9]{2}|42949672[0-8][0-9]|429496729[0-5])$
      maxLength: 10
    Side:
      type: string
      enum:
        - 'YES'
        - 'NO'
  parameters:
    Limit:
      name: limit
      in: query
      schema:
        $ref: '#/components/schemas/PageLimit'
      description: >-
        Maximum items per page, 1 to 200, default 50. A page may hold fewer,
        even none, while has_more is true.
      example: 50
  headers:
    RetryAfter:
      description: Seconds to wait before resending the same request
      schema:
        type: integer
        minimum: 1
  securitySchemes:
    partnerServerKey:
      type: http
      scheme: bearer
      bearerFormat: tpk_
      description: >-
        Partner server key (`tpk_...`), issued by Totalis to a registered
        partner. It calls only `POST /v1/partner/wallet-admissions`, `GET
        /v1/partner/report`, `GET /v1/partner/fills`, `GET
        /v1/partner/webhook-events` and `GET
        /v1/partner/accounts/{wallet}/account-value`, from the partner's server
        with no `Origin`. It reads the value of an account the partner admitted
        but cannot act for an account. Never ship it to a browser: pages use the
        publishable browser key (`X-Totalis-Partner: tpb_...`), which labels
        traffic but authorizes nothing.

````

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