> ## 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 account value

> Everything your account holds at Totalis, all read at one HyperEVM block: wallet USDC, your cash in the vault and in vaults running off, what you paid for your open positions, and the profit you can still claim, net of the fee.

Requires a key for your account with `account:read`.

A wallet session for the account also works, with no scope limit, sent from its `Origin`.



## OpenAPI

````yaml /hyperliquid/openapi.json get /v1/me/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/me/account-value:
    get:
      tags:
        - Account
      summary: Get account value
      description: >-
        Everything your account holds at Totalis, all read at one HyperEVM
        block: wallet USDC, your cash in the vault and in vaults running off,
        what you paid for your open positions, and the profit you can still
        claim, net of the fee.


        Requires a key for your account with `account:read`.


        A wallet session for the account also works, with no scope limit, sent
        from its `Origin`.
      operationId: getAccountValue
      responses:
        '200':
          description: >-
            Your 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: '0x1111111111111111111111111111111111111653'
                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
        '401':
          description: >-
            - `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: >-
            - `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: >-
            - `IDENTITY_NOT_FOUND` (retry `NEVER`): The account has no venue
            identity yet; bind the embedded wallet first.
          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:
                              - IDENTITY_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: >-
            - `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.

            - `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
                              - SOURCE_UNAVAILABLE
                          retry:
                            description: >-
                              The retry rule the registry fixes for the returned
                              code.
                            enum:
                              - BACKOFF
      security:
        - apiKey:
            - account:read
        - walletSession: []
components:
  schemas:
    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:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: ttk_
      description: >-
        Scoped API key (`ttk_...`), created in the Totalis app or by a
        wallet-session user through the API keys routes with a fresh wallet
        signature; those routes never accept a key. Each key acts for one
        account, yours or a maker's, and holds only scopes that account can use.
        Each operation lists the scopes it requires. Send no `Origin`.
    walletSession:
      type: http
      scheme: bearer
      description: >-
        Wallet session: the `access_token` from `POST /v1/auth/wallet-sessions`,
        for a user who brings their own wallet to a partner's web page. It acts
        for that wallet's account with no scope limit, and is bound to the
        `Origin` it signed in from: send exactly one `Origin` header with that
        value, or the request is `ORIGIN_REQUIRED` or `UNAUTHENTICATED`. It
        lasts at most 30 days and ends after 7 idle days or at `DELETE
        /v1/auth/wallet-sessions/current`.

````

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