Hedera Balances API

openapi: 3.2.0
info:
  title: Mirror Node REST Balances API
  version: 0.156.0
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  description: 'The REST API offers the ability to query transactions and entity information from a mirror node.


    Base url: /api/v1


    OpenAPI Spec: /api/v1/docs/openapi.yml'
  contact:
    name: Mirror Node Team
    email: mirrornode@hedera.com
    url: https://github.com/hiero-ledger/hiero-mirror-node
servers:
- description: The current REST API server
  url: ''
- description: The production REST API servers
  url: '{scheme}://{network}.mirrornode.hedera.com'
  variables:
    scheme:
      default: https
      description: The URI scheme
      enum:
      - http
      - https
    network:
      default: testnet
      description: The Hedera network in use
      enum:
      - mainnet-public
      - mainnet
      - previewnet
      - testnet
tags:
- name: Balances
  description: The balance object represents the balance of accounts on the Hedera network.
  externalDocs:
    url: https://docs.hedera.com/guides/docs/mirror-node-api/cryptocurrency-api#balances
paths:
  /api/v1/balances:
    get:
      summary: List account balances
      description: Returns a list of account and token balances on the network. The latest balance information is returned when there is no timestamp query parameter, otherwise, the information is retrieved from snapshots with 15-minute granularity. This information is limited to at most 50 token balances per account as outlined in HIP-367. As such, it's not recommended for general use and we instead recommend using either `/api/v1/accounts/{id}/tokens` or `/api/v1/tokens/{id}/balances` to obtain the current token balance information and `/api/v1/accounts/{id}` to return the current account balance.
      operationId: getBalances
      parameters:
      - $ref: '#/components/parameters/accountIdOrAliasOrEvmAddressQueryParam'
      - $ref: '#/components/parameters/accountBalanceQueryParam'
      - $ref: '#/components/parameters/accountPublicKeyQueryParam'
      - $ref: '#/components/parameters/limitQueryParam'
      - $ref: '#/components/parameters/orderQueryParamDesc'
      - $ref: '#/components/parameters/timestampQueryParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalancesResponse'
        '400':
          $ref: '#/components/responses/InvalidParameterError'
      tags:
      - Balances
components:
  parameters:
    accountIdOrAliasOrEvmAddressQueryParam:
      name: account.id
      in: query
      description: Account id or account alias with no shard realm or evm address with no shard realm
      examples:
        aliasOnly:
          value: HIQQEXWKW53RKN4W6XXC4Q232SYNZ3SZANVZZSUME5B5PRGXL663UAQA
        accountNumOnly:
          value: 8
        realmAccountNum:
          value: 0.8
        shardRealmAccountNum:
          value: 0.0.8
        evmAddress:
          value: ac384c53f03855fa1b3616052f8ba32c6c2a2fec
        evmAddressWithPrefix:
          value: 9.832019034092927e+47
      schema:
        pattern: ^(\d{1,10}\.){0,2}(\d{1,10}|(0x)?[A-Fa-f0-9]{40}|(?:[A-Z2-7]{8})*(?:[A-Z2-7]{2}|[A-Z2-7]{4,5}|[A-Z2-7]{7,8}))$
        type: string
    accountPublicKeyQueryParam:
      name: account.publickey
      in: query
      description: The account's public key to compare against
      example: 3c3d546321ff6f63d701d2ec5c277095874e19f4a235bee1e6bb19258bf362be
      schema:
        type: string
    limitQueryParam:
      name: limit
      in: query
      description: The maximum number of items to return
      example: 2
      schema:
        format: int32
        type: integer
        default: 25
        minimum: 1
        maximum: 100
    orderQueryParamDesc:
      name: order
      in: query
      description: The order in which items are listed
      example: asc
      schema:
        enum:
        - asc
        - desc
        default: desc
    accountBalanceQueryParam:
      name: account.balance
      in: query
      description: The optional balance value to compare against
      explode: true
      examples:
        noValue:
          summary: --
          value: ''
        noOperator:
          summary: Example of equals with no operator
          value: 100
        eqOperator:
          summary: Example of equals operator
          value: eq:200
        neOperator:
          summary: Example of not equals operator
          value: ne:300
        gtOperator:
          summary: Example of greater than operator
          value: gt:400
        gteOperator:
          summary: Example of greater than or equals operator
          value: gte:500
        ltOperator:
          summary: Example of less than operator
          value: lt:600
        lteOperator:
          summary: Example of less than or equals operator
          value: lte:700
      schema:
        type: string
        pattern: ^((gte?|lte?|eq|ne)\:)?\d{1,10}$
    timestampQueryParam:
      description: The consensus timestamp as a Unix timestamp in seconds.nanoseconds format with an optional comparison operator. See [unixtimestamp.com](https://www.unixtimestamp.com/) for a simple way to convert a date to the 'seconds' part of the Unix time.
      name: timestamp
      in: query
      explode: true
      examples:
        noValue:
          summary: --
          value: ''
        secondsNoOperator:
          summary: Example of seconds equals with no operator
          value: 1234567890
        timestampNoOperator:
          summary: Example of timestamp equals with no operator
          value: 1234567890
        secondsEqOperator:
          summary: Example of seconds equals with operator
          value: eq:1234567890
        timestampEqOperator:
          summary: Example of timestamp equals with operator
          value: eq:1234567890.000000200
        secondsNeOperator:
          summary: Example of seconds not equals operator
          value: ne:1234567890
        timestampNeOperator:
          summary: Example of timestamp not equals operator
          value: ne:1234567890.000000300
        secondsGtOperator:
          summary: Example of seconds greater than operator
          value: gt:1234567890
        timestampGtOperator:
          summary: Example of timestamp greater than operator
          value: gt:1234567890.000000400
        secondsGteOperator:
          summary: Example of seconds greater than or equals operator
          value: gte:1234567890
        timestampGteOperator:
          summary: Example of timestamp greater than or equals operator
          value: gte:1234567890.000000500
        secondsLtOperator:
          summary: Example of seconds less than operator
          value: lt:1234567890
        timestampLtOperator:
          summary: Example of timestamp less than operator
          value: lt:1234567890.000000600
        secondsLteOperator:
          summary: Example of seconds less than or equals operator
          value: lte:1234567890
        timestampLteOperator:
          summary: Example of timestamp less than or equals operator
          value: lte:1234567890.000000700
      schema:
        type: array
        items:
          type: string
          pattern: ^((eq|gt|gte|lt|lte|ne):)?\d{1,10}(\.\d{1,9})?$
  responses:
    InvalidParameterError:
      description: Invalid parameter
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            _status:
              messages:
              - message: 'Invalid parameter: account.id'
              - message: Invalid Transaction id. Please use \shard.realm.num-sss-nnn\ format where sss are seconds and nnn are nanoseconds
  schemas:
    Error:
      type: object
      properties:
        _status:
          type: object
          properties:
            messages:
              type: array
              items:
                type: object
                properties:
                  data:
                    description: Error message in hexadecimal
                    example: '0x3000'
                    format: binary
                    pattern: ^0x[0-9a-fA-F]+$
                    type:
                    - string
                    - 'null'
                  detail:
                    description: Detailed error message
                    example: Generic detailed error message
                    type:
                    - string
                    - 'null'
                  message:
                    description: Error message
                    example: Generic error message
                    type: string
    AccountBalance:
      type: object
      required:
      - account
      - balance
      - tokens
      properties:
        account:
          $ref: '#/components/schemas/EntityId'
        balance:
          format: int64
          type: integer
        tokens:
          type: array
          items:
            $ref: '#/components/schemas/TokenBalance'
      example:
        account: 0.15.10
        balance: 80
        tokens:
        - token_id: 0.0.200001
          balance: 8
    TokenBalance:
      type: object
      required:
      - token_id
      - balance
      properties:
        token_id:
          $ref: '#/components/schemas/EntityId'
        balance:
          format: int64
          type: integer
      example:
        token_id: 0.0.200001
        balance: 8
    BalancesResponse:
      type: object
      properties:
        timestamp:
          $ref: '#/components/schemas/TimestampNullable'
        balances:
          type: array
          items:
            $ref: '#/components/schemas/AccountBalance'
        links:
          $ref: '#/components/schemas/Links'
    TimestampNullable:
      description: A Unix timestamp in seconds.nanoseconds format
      type:
      - string
      - 'null'
      example: '1586567700.453054000'
      pattern: ^\d{1,10}(\.\d{1,9})?$
    EntityId:
      type:
      - string
      - 'null'
      description: Network entity ID in the format of `shard.realm.num`
      pattern: ^\d{1,10}\.\d{1,10}\.\d{1,10}$
      example: 0.0.2
    Links:
      type: object
      properties:
        next:
          example: null
          type:
          - string
          - 'null'
externalDocs:
  description: REST API Docs
  url: https://docs.hedera.com/guides/docs/mirror-node-api/cryptocurrency-api
x-provenance:
  method: harvested
  publisher: Hedera
  source: https://docs.hedera.com/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)