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

# Get holdings

> Requires key scope `read`.

Returns a live valuation of idle tokens and every open strategy. The data can be up to 15 seconds old. When `partial` is `true`, at least one price was unavailable. A missing valuation is not zero.



## OpenAPI

````yaml /api-reference/openapi.json get /vaults/{vault}/holdings
openapi: 3.1.0
info:
  title: Hedgin manager bot API
  version: 1.0.0
  description: >-
    Versioned HTTP API for approved manager bots. Reads vault state and builds
    unsigned Solana transactions. The bot signs locally with the vault's current
    authority key. Runs only on Solana mainnet-beta.
servers:
  - url: https://hedgin.xyz/api/external/v1
    description: Production (Solana mainnet-beta)
security:
  - bearerAuth: []
tags:
  - name: Vault reads
  - name: Market reads
  - name: Jupiter transactions
  - name: Meteora DLMM transactions
  - name: Phoenix transactions
  - name: Vault and strategy transactions
  - name: Send and status
paths:
  /vaults/{vault}/holdings:
    get:
      tags:
        - Vault reads
      summary: Get holdings
      description: >-
        Requires key scope `read`.


        Returns a live valuation of idle tokens and every open strategy. The
        data can be up to 15 seconds old. When `partial` is `true`, at least one
        price was unavailable. A missing valuation is not zero.
      operationId: getVaultHoldings
      parameters:
        - name: vault
          in: path
          required: true
          description: >-
            Vault public key. Must be in the key's allowlist when the key has
            one, and the key's manager must be the vault's current on-chain
            authority.
          schema:
            $ref: '#/components/schemas/PublicKey'
      responses:
        '200':
          description: The vault address and its data.
          content:
            application/json:
              schema:
                type: object
                required:
                  - vault
                  - data
                properties:
                  vault:
                    $ref: '#/components/schemas/PublicKey'
                  data:
                    $ref: '#/components/schemas/HoldingsView'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  schemas:
    PublicKey:
      type: string
      description: >-
        Base58 Solana public key. The server decodes it and rejects anything
        that is not 32 bytes.
      pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
      example: So11111111111111111111111111111111111111112
    HoldingsView:
      type: object
      required:
        - depositToken
        - totalValue
        - totalUsd
        - navTotalAssets
        - navDeltaBps
        - partial
        - unpriced
        - tokens
        - positions
      properties:
        depositToken:
          $ref: '#/components/schemas/TokenInfo'
        totalValue:
          $ref: '#/components/schemas/BaseUnitAmount'
          description: Live estimate, deposit base units.
        totalUsd:
          type:
            - number
            - 'null'
        navTotalAssets:
          $ref: '#/components/schemas/BaseUnitAmount'
          description: On-chain NAV total assets, for comparison.
        navDeltaBps:
          type:
            - integer
            - 'null'
        partial:
          type: boolean
          description: >-
            `true` when at least one price was unavailable. A missing valuation
            is not zero.
        unpriced:
          type: array
          items:
            type: string
          description: Symbols of tokens with no price.
        tokens:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/Money'
              - type: object
                properties:
                  token:
                    $ref: '#/components/schemas/TokenInfo'
                  amount:
                    $ref: '#/components/schemas/BaseUnitAmount'
        positions:
          type: array
          items:
            $ref: '#/components/schemas/PositionView'
    TokenInfo:
      type: object
      required:
        - mint
        - symbol
        - decimals
        - logo
        - priceUsd
      properties:
        mint:
          $ref: '#/components/schemas/PublicKey'
        symbol:
          type: string
        name:
          type: string
        decimals:
          type: integer
        logo:
          type:
            - string
            - 'null'
        priceUsd:
          type:
            - number
            - 'null'
          description: USD per whole token (base units / 10^decimals). Display only.
        uiMultiplier:
          type: number
          description: >-
            Token-2022 scaled UI amount multiplier. Absent for unscaled mints.
            Display only.
    BaseUnitAmount:
      type: string
      description: >-
        Non-negative integer in token base units, as a decimal string. Must fit
        in u64 (at most 18446744073709551615). Never a JSON number.
      pattern: ^\d+$
      maxLength: 20
      example: '1000000'
    Money:
      type: object
      properties:
        value:
          type:
            - string
            - 'null'
          description: >-
            Live estimate in deposit base units. `null` when unpriced, which is
            not zero.
        usd:
          type:
            - number
            - 'null'
        shareBps:
          type:
            - integer
            - 'null'
    PositionView:
      description: One holding. `kind` selects the shape.
      oneOf:
        - title: idle
          allOf:
            - $ref: '#/components/schemas/Money'
            - type: object
              properties:
                kind:
                  const: idle
                token:
                  $ref: '#/components/schemas/TokenInfo'
                amount:
                  $ref: '#/components/schemas/BaseUnitAmount'
        - title: swap
          allOf:
            - $ref: '#/components/schemas/Money'
            - type: object
              properties:
                kind:
                  const: swap
                strategy:
                  $ref: '#/components/schemas/PublicKey'
                token:
                  $ref: '#/components/schemas/TokenInfo'
                amount:
                  $ref: '#/components/schemas/BaseUnitAmount'
                lastActionTs:
                  type: integer
                closable:
                  type: boolean
        - title: lp
          allOf:
            - $ref: '#/components/schemas/Money'
            - type: object
              properties:
                kind:
                  const: lp
                strategy:
                  $ref: '#/components/schemas/PublicKey'
                position:
                  $ref: '#/components/schemas/PublicKey'
                lbPair:
                  $ref: '#/components/schemas/PublicKey'
                tokenX:
                  $ref: '#/components/schemas/TokenInfo'
                tokenY:
                  $ref: '#/components/schemas/TokenInfo'
                amountX:
                  $ref: '#/components/schemas/BaseUnitAmount'
                amountY:
                  $ref: '#/components/schemas/BaseUnitAmount'
                feeX:
                  $ref: '#/components/schemas/BaseUnitAmount'
                feeY:
                  $ref: '#/components/schemas/BaseUnitAmount'
                lastActionTs:
                  type: integer
                range:
                  type: object
                  properties:
                    lowerBinId:
                      type: integer
                    upperBinId:
                      type: integer
                      description: Inclusive.
                    activeBinId:
                      type: integer
                    binStep:
                      type: integer
                    lowerPrice:
                      type: string
                    upperPrice:
                      type: string
                    activePrice:
                      type: string
                    inRange:
                      type: boolean
                bins:
                  type: array
                  items:
                    $ref: '#/components/schemas/BinAmounts'
                closable:
                  type: boolean
                pnlUsd:
                  type:
                    - number
                    - 'null'
                pnlPct:
                  type:
                    - number
                    - 'null'
        - title: limit_order
          allOf:
            - $ref: '#/components/schemas/Money'
            - type: object
              properties:
                kind:
                  const: limit_order
                strategy:
                  $ref: '#/components/schemas/PublicKey'
                limitOrder:
                  $ref: '#/components/schemas/PublicKey'
                lbPair:
                  $ref: '#/components/schemas/PublicKey'
                tokenX:
                  $ref: '#/components/schemas/TokenInfo'
                tokenY:
                  $ref: '#/components/schemas/TokenInfo'
                side:
                  type: string
                  enum:
                    - ask
                    - bid
                sells:
                  $ref: '#/components/schemas/TokenInfo'
                buys:
                  $ref: '#/components/schemas/TokenInfo'
                binStep:
                  type: integer
                lowerBinId:
                  type: integer
                upperBinId:
                  type: integer
                activeBinId:
                  type: integer
                lowerPrice:
                  type: string
                upperPrice:
                  type: string
                activePrice:
                  type: string
                binCount:
                  type: integer
                deposited:
                  $ref: '#/components/schemas/BaseUnitAmount'
                unfilled:
                  $ref: '#/components/schemas/BaseUnitAmount'
                proceeds:
                  $ref: '#/components/schemas/BaseUnitAmount'
                feeX:
                  $ref: '#/components/schemas/BaseUnitAmount'
                feeY:
                  $ref: '#/components/schemas/BaseUnitAmount'
                filledBps:
                  type: integer
                lastActionTs:
                  type: integer
                closable:
                  type: boolean
        - title: perp
          allOf:
            - $ref: '#/components/schemas/Money'
            - type: object
              properties:
                kind:
                  const: perp
                strategy:
                  $ref: '#/components/schemas/PublicKey'
                traderAccount:
                  $ref: '#/components/schemas/PublicKey'
                equity:
                  $ref: '#/components/schemas/BaseUnitAmount'
                collateral:
                  $ref: '#/components/schemas/BaseUnitAmount'
                canonicalBalance:
                  $ref: '#/components/schemas/BaseUnitAmount'
                leverage:
                  type:
                    - number
                    - 'null'
                positions:
                  type: array
                  items:
                    $ref: '#/components/schemas/PerpPosition'
                lastActionTs:
                  type: integer
                closable:
                  type: boolean
        - title: error
          type: object
          properties:
            kind:
              const: error
            strategy:
              $ref: '#/components/schemas/PublicKey'
            protocol:
              type: string
              enum:
                - dlmm
                - dlmm_limit_order
                - phoenix
            position:
              $ref: '#/components/schemas/PublicKey'
            reason:
              type: string
            value:
              type: 'null'
            usd:
              type: 'null'
            shareBps:
              type: 'null'
            lastActionTs:
              type: integer
    Error:
      type: object
      description: >-
        Every error response uses this envelope. Responses with status 500, 502,
        or 503 always carry the message `Service temporarily unavailable`.
        Responses with status 422 always carry the message `Transaction rejected
        during simulation or preflight`. In both cases `code` still names the
        cause.
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: >-
                Stable machine-readable code, such as `Validation`, `Forbidden`,
                or a decoded program error name.
              example: Validation
            message:
              type: string
              description: Human-readable detail. Never contains provider logs.
              example: vault must be a public key
    BinAmounts:
      type: object
      properties:
        binId:
          type: integer
        amountX:
          $ref: '#/components/schemas/BaseUnitAmount'
        amountY:
          $ref: '#/components/schemas/BaseUnitAmount'
    PerpPosition:
      type: object
      properties:
        assetId:
          type: integer
        symbol:
          type: string
        logo:
          type:
            - string
            - 'null'
        side:
          type: string
          enum:
            - long
            - short
        size:
          type: string
          description: Whole base units, decimal string.
        entryPrice:
          type: string
        markPrice:
          type: string
        notional:
          type: string
        unrealizedPnl:
          type: string
        accruedFunding:
          type: string
  responses:
    BadRequest:
      description: >-
        Invalid path, query, or body. Builder messages name the field, such as
        `amount: must be a non-negative integer string`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: Validation
              message: vault must be a public key
    Unauthorized:
      description: Missing, malformed, unknown, revoked, or expired API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: Unauthorized
              message: Invalid API key
    Forbidden:
      description: >-
        The key lacks the required scope, the vault is outside the key's
        allowlist, or the key's manager is not the vault's current on-chain
        authority.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: Forbidden
              message: Action is not enabled for this key
    NotFound:
      description: Unknown route, or the vault, mint, pool, or strategy does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: NotFound
              message: Vault not found
    TooManyRequests:
      description: A rate limit is exhausted.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: RateLimited
              message: Too many requests, slow down
    InternalError:
      description: >-
        Internal error, including a builder that returned an invalid transaction
        (`BuildFailed`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: Internal
              message: Service temporarily unavailable
    ServiceUnavailable:
      description: RPC, key store, or service configuration unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: RpcUnavailable
              message: Service temporarily unavailable
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: hv1_<id>_<secret>
      description: >-
        API key issued by a Hedgin administrator, in the form
        `hv1_<id>_<secret>`. `<id>` is 1 to 48 characters and `<secret>` is 32
        to 128 characters, both from `[A-Za-z0-9_-]`.

````

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