> ## 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.

# Get user account value

> The value of an account your admission of this wallet opened, the body Get account value returns to the user, read with your server key so you can keep a user's history after their own key lapses.

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/accounts/{wallet}/account-value
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/accounts/{wallet}/account-value:
    get:
      tags:
        - Partners & wallet sign-in
      summary: Get user account value
      description: >-
        The value of an account your admission of this wallet opened, the body
        Get account value returns to the user, read with your server key so you
        can keep a user's history after their own key lapses.


        Requires your partner server key (`tpk_`), sent from your server with no
        `Origin`; an API key cannot call it.
      operationId: getPartnerAccountValue
      parameters:
        - name: wallet
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/Address'
          description: The wallet you admitted, still signing for the account it opened.
          example: '0x8ba1f109551bD432803012645Ac136ddd64DBA72'
      responses:
        '200':
          description: >-
            The account's value and its parts. When state is UNKNOWN every
            amount is null; read again later. No caching.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountValue'
              example:
                account: '0x8ba1f109551bd432803012645ac136ddd64dba72'
                state: CURRENT
                amount: '64357000'
                block_number: '31552212'
                wallet_usdc: '12500000'
                vault_cash: '35000000'
                run_off_cash: '4200000'
                open_positions: 2
                open_cost: '10857000'
                claimable_profit: '1800000'
                checkpoint:
                  block_number: '31552212'
                  projection_state: CURRENT
        '400':
          description: >-
            `INVALID_REQUEST`: wallet is not a 0x-prefixed 20-byte hex address.


            - `INVALID_REQUEST` (retry `NEVER`): The body, a path parameter or a
            header is malformed or fails validation. `field_violations` names
            invalid body fields; for an RFQ leg whose market refuses new
            positions now, `/legs/{i}/outcome_id`, with the reason in the
            message. `NEVER` means the same request will fail again; the leg's
            market can become eligible later, so before a new RFQ read its live
            `eligibility` and, for a Combo leg, `combo.state` and `combo.reason`
            (`combo.opens_at` is set only for an `OUTSIDE_WINDOW` refusal whose
            window has a known time).
          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_REQUEST
                          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 account values 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
        '404':
          description: >-
            `NOT_FOUND`: you did not admit this wallet, it has no account yet,
            or it no longer signs for the account it opened. A wallet another
            partner admitted, or no partner, answers the same.


            - `NOT_FOUND` (retry `NEVER`): The resource does not exist or is not
            visible to this credential.
          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:
                              - NOT_FOUND
                          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: >-
            The value is temporarily unavailable; resend after `Retry-After`.


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

            - `DEPENDENCY_STALE` (retry `BACKOFF`): A projection or upstream the
            request depends on (chain projection, HyperCore state, database) is
            behind its freshness bound or unavailable.

            - `FINANCIAL_ACTIONS_DISABLED` (retry `BACKOFF`): Financial actions
            are disabled for this deployment.

            - `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
                              - DEPENDENCY_STALE
                              - FINANCIAL_ACTIONS_DISABLED
                              - SOURCE_UNAVAILABLE
                          retry:
                            description: >-
                              The retry rule the registry fixes for the returned
                              code.
                            enum:
                              - BACKOFF
      security:
        - partnerServerKey: []
components:
  schemas:
    Address:
      type: string
      pattern: ^0x[0-9a-fA-F]{40}$
      format: eip55-address
    AccountValue:
      description: >-
        What the account holds at Totalis at one HyperEVM block, in atomic USDC
        (6 decimals, "1000000" = 1 USDC): wallet USDC, its cash in the vault and
        in vaults running off, what it paid for its open positions, and the
        profit it can still claim, net of the fee. Every amount is read from the
        chain at block_number. HyperCore balances are not included; read them
        from Hyperliquid.
      type: object
      required:
        - account
        - state
        - amount
        - block_number
        - wallet_usdc
        - vault_cash
        - run_off_cash
        - open_positions
        - open_cost
        - claimable_profit
        - checkpoint
      properties:
        account:
          $ref: '#/components/schemas/LowercaseNonZeroAddress'
          description: The account's wallet, lowercase.
        state:
          description: >-
            CURRENT when every amount was read at block_number; UNKNOWN when the
            chain could not be read, or the projection did not reach that block
            in time, and every amount is null. Read again later.
          enum:
            - CURRENT
            - UNKNOWN
        amount:
          description: >-
            The account's value: wallet_usdc + vault_cash + run_off_cash +
            open_cost + claimable_profit. Null unless state is CURRENT.
          oneOf:
            - $ref: '#/components/schemas/CommonAmount'
            - type: 'null'
        block_number:
          description: >-
            The HyperEVM block every amount was read at. Null unless state is
            CURRENT.
          oneOf:
            - $ref: '#/components/schemas/UInt64String'
            - type: 'null'
        wallet_usdc:
          description: >-
            USDC in the account's wallet on HyperEVM, including any already
            committed to a Totalis withdrawal or stake that has not landed. Null
            unless state is CURRENT.
          oneOf:
            - $ref: '#/components/schemas/CommonAmount'
            - type: 'null'
        vault_cash:
          description: >-
            All the account's cash in the vault, including any held for an
            operation that has not landed, so it can exceed GET /v1/me/balances'
            free vault cash. Null unless state is CURRENT.
          oneOf:
            - $ref: '#/components/schemas/CommonAmount'
            - type: 'null'
        run_off_cash:
          description: >-
            The account's cash in vaults running off, all together; GET
            /v1/me/balances lists it per vault. Null unless state is CURRENT.
          oneOf:
            - $ref: '#/components/schemas/CommonAmount'
            - type: 'null'
        open_positions:
          description: >-
            How many positions the account holds that have not settled: OPEN and
            AWAITING_SETTLEMENT in GET /v1/me/positions. Null unless state is
            CURRENT.
          oneOf:
            - type: integer
              minimum: 0
            - type: 'null'
        open_cost:
          description: >-
            What the account paid for those positions: the sum of their
            acquisition_cost. Null unless state is CURRENT.
          oneOf:
            - $ref: '#/components/schemas/CommonAmount'
            - type: 'null'
        claimable_profit:
          description: >-
            What claiming every SETTLED_UNCLAIMED position would pay the
            account: each one's unclaimed_profit minus floor(unclaimed_profit *
            fee_bps / 10000). Null unless state is CURRENT.
          oneOf:
            - $ref: '#/components/schemas/CommonAmount'
            - type: 'null'
        checkpoint:
          $ref: '#/components/schemas/Checkpoint'
          description: >-
            The vault projection the read used to find the account's positions.
            When state is CURRENT it has reached block_number.
    Error:
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
          description: The one error this request failed with.
      required:
        - error
      type: object
    LowercaseNonZeroAddress:
      type: string
      pattern: ^0x[0-9a-f]{40}$
      not:
        const: '0x0000000000000000000000000000000000000000'
    CommonAmount:
      type: string
      pattern: ^(0|[1-9][0-9]*)$
      maxLength: 39
      format: uint128-decimal
    UInt64String:
      type: string
      pattern: >-
        ^(0|[1-9][0-9]{0,18}|1[0-7][0-9]{18}|18[0-3][0-9]{17}|184[0-3][0-9]{16}|1844[0-5][0-9]{15}|18446[0-6][0-9]{14}|184467[0-3][0-9]{13}|1844674[0-3][0-9]{12}|184467440[0-6][0-9]{10}|1844674407[0-2][0-9]{9}|18446744073[0-6][0-9]{8}|1844674407370[0-8][0-9]{6}|18446744073709[0-4][0-9]{5}|184467440737095[0-4][0-9]{4}|18446744073709550[0-9]{3}|18446744073709551[0-5][0-9]{2}|1844674407370955160[0-9]|1844674407370955161[0-5])$
      maxLength: 20
      format: uint64-decimal
    Checkpoint:
      type: object
      required:
        - block_number
        - projection_state
      properties:
        block_number:
          $ref: '#/components/schemas/UInt64String'
          description: >-
            Last HyperEVM block the vault projection has indexed; the read
            reflects chain state up to and including this block.
        projection_state:
          description: >-
            CURRENT when the projection is within 32 blocks of a chain head
            observed in the last two minutes; STALE when it lags, so figures may
            be behind.
          enum:
            - CURRENT
            - STALE
    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
    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
  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.