> ## 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 webhook events

> Every webhook event Totalis queued for you in the last 30 days, delivered or not, in the order it queued them, each with the body it posts and how its delivery stands, so you can recover events your endpoint missed.

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/webhook-events
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/webhook-events:
    get:
      tags:
        - Partners & wallet sign-in
      summary: List webhook events
      description: >-
        Every webhook event Totalis queued for you in the last 30 days,
        delivered or not, in the order it queued them, each with the body it
        posts and how its delivery stands, so you can recover events your
        endpoint missed.


        Requires your partner server key (`tpk_`), sent from your server with no
        `Origin`; an API key cannot call it.
      operationId: listPartnerWebhookEvents
      parameters:
        - name: since
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: List only events queued at or after this RFC 3339 time.
          example: '2026-11-13T00:00:00Z'
        - name: cursor
          in: query
          required: false
          description: >-
            Omit for the oldest events kept; then send a previous response's
            next_cursor unchanged.
          schema:
            $ref: '#/components/schemas/PageCursor'
          example: v1:812:balance_01933a5e-6f1c-7c3a-9b1e-2f4d5c6b7a81
        - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A page of your webhook events. No caching.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerWebhookEventPage'
              example:
                events:
                  - event:
                      id: >-
                        settle_7a3c9e1f00000000000000000000000000000000000000000000000000000001
                      type: position.settled
                      created_at: '2026-11-13T09:12:40Z'
                      data:
                        position_id: >-
                          0x7a3c9e1f00000000000000000000000000000000000000000000000000000001
                        owner: '0x1111111111111111111111111111111111111111'
                        legs:
                          - outcome_id: '1201'
                            side: 'YES'
                        settlement_kind: WIN
                        stake: '24962500'
                        payout: '61000000'
                        settled_amount: '61000000'
                        credited: '24962500'
                        claimable: '36037500'
                        claim_fee: '540562'
                        share_bps: 2000
                        time: '2026-11-13T09:12:40Z'
                        block_number: 22101877
                        log_index: 2
                        transaction_hash: >-
                          0x5b0e8d2a00000000000000000000000000000000000000000000000000000003
                    status: FAILED
                    attempts: 8
                    queued_at: '2026-11-13T09:12:43.118Z'
                    delivered_at: null
                  - event:
                      id: balance_01933a5e-6f1c-7c3a-9b1e-2f4d5c6b7a81
                      type: balance.updated
                      created_at: '2026-11-13T09:12:41.020Z'
                      data:
                        account: '0x1111111111111111111111111111111111111111'
                        state: CURRENT
                        amount: '61000000'
                        block_number: '22101878'
                        wallet_usdc: '0'
                        vault_cash: '24962500'
                        run_off_cash: '0'
                        open_positions: 0
                        open_cost: '0'
                        claimable_profit: '35496938'
                        checkpoint:
                          block_number: '22101878'
                          projection_state: CURRENT
                    status: DELIVERED
                    attempts: 1
                    queued_at: '2026-11-13T09:12:43.120Z'
                    delivered_at: '2026-11-13T09:12:43.402Z'
                next_cursor: v1:812:balance_01933a5e-6f1c-7c3a-9b1e-2f4d5c6b7a81
                has_more: false
        '400':
          description: >-
            `INVALID_QUERY`: since is not an RFC 3339 time, 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 webhook events 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: >-
            Webhook events 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.
    PartnerWebhookEventPage:
      type: object
      required:
        - events
        - next_cursor
        - has_more
      properties:
        events:
          type: array
          maxItems: 200
          items:
            $ref: '#/components/schemas/PartnerWebhookEvent'
          description: Events in the order Totalis queued them, oldest first.
        next_cursor:
          $ref: '#/components/schemas/NextCursor'
          description: >-
            Send it as cursor for the events after this page. It follows the
            last event even when has_more is false, so keep it and read again
            later for new events. Null only when no event has been returned yet.
        has_more:
          type: boolean
          description: Whether more events follow.
    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.
    PartnerWebhookEvent:
      type: object
      required:
        - event
        - status
        - attempts
        - queued_at
        - delivered_at
      properties:
        event:
          type: object
          required:
            - id
            - type
            - created_at
            - data
          properties:
            id:
              type: string
              description: >-
                The event's id, as the webhook-id header carried it; dedupe on
                it.
            type:
              type: string
              description: The event type, such as position.opened or balance.updated.
            created_at:
              type: string
              description: When the event happened.
            data:
              description: The event's data, as posted.
          description: The event body exactly as Totalis posts it to the webhook.
        status:
          type: string
          enum:
            - PENDING
            - DELIVERED
            - FAILED
          description: >-
            PENDING while Totalis still sends it, DELIVERED once the webhook
            answered 2xx, FAILED after the last attempt failed.
        attempts:
          type: integer
          minimum: 0
          maximum: 8
          description: How many times Totalis has sent it.
        queued_at:
          $ref: '#/components/schemas/CommonTimestamp'
          description: When Totalis queued it.
        delivered_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When the webhook accepted it, or null.
    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
    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
  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.