> ## Documentation Index
> Fetch the complete documentation index at: https://developers.avacloud.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Get balances
> Gets primary network balances for one of the Primary Network chains for the supplied addresses.
C-Chain balances returned are only the shared atomic memory balance. For EVM balance, use the `/v1/chains/:chainId/addresses/:addressId/balances:getNative` endpoint.
## OpenAPI
````yaml get /v1/networks/{network}/blockchains/{blockchainId}/balances
openapi: 3.1.0
info:
title: Data API
description: >-
The Data API provides web3 application developers with multi-chain data
related to Avalanche's primary network, Avalanche subnets, and Ethereum.
With Data API, you can easily build products that leverage real-time and
historical transaction and transfer history, native and token balances, and
various types of token metadata. The API is in Beta and may be subject to
change.If you have feedback or feature requests for the API,
please submit them here.
Bug reports can be submitted here,
and any potential security issues can be reported here.
version: 1.0.0
contact: {}
servers:
- url: https://glacier-api.avax.network
security:
- apiKey: []
- {}
tags:
- name: EVM Chains
description: >-
Find information about indexed EVM-compatible chains, such as the
Avalanche C-Chain.
- name: EVM Blocks
description: >-
Find information about blocks on EVM-compatible chains, such as the
Avalanche C-Chain.
- name: EVM Transactions
description: >-
Find information about transactions on EVM-compatible chains, such as the
Avalanche C-Chain.
- name: EVM Balances
description: >-
Find information about balances on EVM-compatible chains, such as the
Avalanche C-Chain.
- name: EVM Contracts
description: >-
Find information about contracts on EVM-compatible chains, such as the
Avalanche C-Chain.
- name: Primary Network
- name: Primary Network Blocks
description: >-
Find information about blocks on Avalanche's Primary Network Chains - the
P-Chain, the X-Chain, and the C-Chain.
- name: Primary Network Vertices
description: Find information about vertices on Avalanche's X-Chain.
- name: Primary Network Transactions
description: >-
Find information about transactions on Avalanche's Primary Network Chains
- the P-Chain, the X-Chain, and the C-Chain.
- name: Primary Network Balances
description: >-
Find information about balances on Avalanche's Primary Network Chains -
the P-Chain, the X-Chain, and the C-Chain.
- name: Primary Network UTXOs
description: >-
Find information about utxos on Avalanche's Primary Network Chains - the
P-Chain, the X-Chain, and the C-Chain.
- name: Primary Network Rewards
description: Find information about rewards on Avalanche's Primary Network.
- name: NFTs
- name: Operations
- name: Health Check
- name: Teleporter
description: Find information about Teleporter transactions.
- name: Interchain Messaging
description: Find information about Interchain Messaging transactions.
- name: Webhooks
description: Manage webhooks and get notified for various onchain activities.
- name: RPC
description: Interact with chain nodes using JSON-RPC.
- name: Data API Usage Metrics
description: Usage metrics and logs for the Data API.
- name: Signature Aggregator
description: Request signatures for a Warp message from Subnet validators
- name: Notifications
description: Get notifications for validator status and activity issues.
- name: AVAX Supply
description: Find information about AVAX supply.
paths:
/v1/networks/{network}/blockchains/{blockchainId}/balances:
get:
tags:
- Primary Network Balances
summary: Get balances
description: >-
Gets primary network balances for one of the Primary Network chains for
the supplied addresses.
C-Chain balances returned are only the shared atomic memory balance. For
EVM balance, use the
`/v1/chains/:chainId/addresses/:addressId/balances:getNative` endpoint.
operationId: getBalancesByAddresses
parameters:
- name: blockTimestamp
required: false
in: query
description: >-
An epoch timestamp in seconds. Balance will be calculated at this
timestamp.
example: '1599696000'
schema:
type: integer
- name: addresses
required: false
in: query
description: >-
A comma separated list of X-Chain or P-Chain wallet addresses,
starting with "avax"/"fuji", "P-avax"/"P-fuji" or "X-avax"/"X-fuji".
example: avax1h2ccj9f5ay5acl6tyn9mwmw32p8wref8vl8ctg
schema:
type: string
- name: blockchainId
required: true
in: path
description: A primary network blockchain id or alias.
example: p-chain
schema:
$ref: '#/components/schemas/BlockchainId'
- name: network
required: true
in: path
description: Either mainnet or testnet/fuji.
example: mainnet
schema:
$ref: '#/components/schemas/Network'
responses:
'200':
description: Successful response
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ListPChainBalancesResponse'
- $ref: '#/components/schemas/ListXChainBalancesResponse'
- $ref: '#/components/schemas/ListCChainAtomicBalancesResponse'
'400':
description: |-
Bad requests generally mean the client has passed invalid
or malformed parameters. Error messages in the response could help in
evaluating the error.
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
'401':
description: |-
When a client attempts to access resources that require
authorization credentials but the client lacks proper authentication
in the request, the server responds with 401.
content:
application/json:
schema:
$ref: '#/components/schemas/Unauthorized'
'403':
description: |-
When a client attempts to access resources with valid
credentials but doesn't have the privilege to perform that action,
the server responds with 403.
content:
application/json:
schema:
$ref: '#/components/schemas/Forbidden'
'404':
description: |-
The error is mostly returned when the client requests
with either mistyped URL, or the passed resource is moved or deleted,
or the resource doesn't exist.
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
'429':
description: |-
This error is returned when the client has sent too many,
and has hit the rate limit.
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequests'
'500':
description: |-
The error is a generic server side error that is
returned for any uncaught and unexpected issues on the server side.
This should be very rare, and you may reach out to us if the problem
persists for a longer duration.
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
'502':
description: |-
This is an internal error indicating invalid response
received by the client-facing proxy or gateway from the upstream server.
content:
application/json:
schema:
$ref: '#/components/schemas/BadGateway'
'503':
description: |-
The error is returned for certain routes on a particular
Subnet. This indicates an internal problem with our Subnet node, and may
not necessarily mean the Subnet is down or affected.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceUnavailable'
x-codeSamples:
- lang: javascript
label: JavaScript
source: |-
import { Avalanche } from "@avalanche-sdk/chainkit";
const avalanche = new Avalanche({
network: "mainnet",
});
async function run() {
const result = await avalanche.data.primaryNetwork.balances.listByAddresses({
blockTimestamp: 1599696000,
addresses: "avax1h2ccj9f5ay5acl6tyn9mwmw32p8wref8vl8ctg",
blockchainId: "p-chain",
});
console.log(result);
}
run();
components:
schemas:
BlockchainId:
type: string
enum:
- 11111111111111111111111111111111LpoYY
- 2oYMBNV4eNHyqk2fjjV5nVQLDbtmNJzq5s3qs3Lo6ftnC6FByM
- 2JVSBoinj9C2J33VntvzYtVJNZdN2NKiwwKjcumHUWEb5DbBrm
- 2q9e4r6Mu3U68nU1fYjgbR6JvwrRx36CohpAX5UQxse55x1Q5
- yH8D7ThNJkxmtkuv2jgBa4P1Rn3Qpr4pPr7QYNfcdoS6k6HWp
- p-chain
- x-chain
- c-chain
Network:
type: string
enum:
- mainnet
- fuji
- testnet
ListPChainBalancesResponse:
type: object
properties:
balances:
$ref: '#/components/schemas/PChainBalance'
chainInfo:
$ref: '#/components/schemas/PrimaryNetworkChainInfo'
required:
- balances
- chainInfo
ListXChainBalancesResponse:
type: object
properties:
balances:
$ref: '#/components/schemas/XChainBalances'
chainInfo:
$ref: '#/components/schemas/PrimaryNetworkChainInfo'
required:
- balances
- chainInfo
ListCChainAtomicBalancesResponse:
type: object
properties:
balances:
$ref: '#/components/schemas/CChainAtomicBalances'
chainInfo:
$ref: '#/components/schemas/PrimaryNetworkChainInfo'
required:
- balances
- chainInfo
BadRequest:
type: object
properties:
message:
description: The error message describing the reason for the exception
oneOf:
- type: string
- type: array
items:
type: string
statusCode:
type: number
description: The HTTP status code of the response
examples:
- 400
error:
type: string
description: The type of error
examples:
- Bad Request
required:
- message
- statusCode
- error
Unauthorized:
type: object
properties:
message:
description: The error message describing the reason for the exception
oneOf:
- type: string
- type: array
items:
type: string
statusCode:
type: number
description: The HTTP status code of the response
examples:
- 401
error:
type: string
description: The type of error
examples:
- Unauthorized
required:
- message
- statusCode
- error
Forbidden:
type: object
properties:
message:
description: The error message describing the reason for the exception
oneOf:
- type: string
- type: array
items:
type: string
statusCode:
type: number
description: The HTTP status code of the response
examples:
- 403
error:
type: string
description: The type of error
examples:
- Forbidden
required:
- message
- statusCode
- error
NotFound:
type: object
properties:
message:
description: The error message describing the reason for the exception
oneOf:
- type: string
- type: array
items:
type: string
statusCode:
type: number
description: The HTTP status code of the response
examples:
- 404
error:
type: string
description: The type of error
examples:
- Not Found
required:
- message
- statusCode
- error
TooManyRequests:
type: object
properties:
message:
description: The error message describing the reason for the exception
oneOf:
- type: string
- type: array
items:
type: string
statusCode:
type: number
description: The HTTP status code of the response
examples:
- 429
error:
type: string
description: The type of error
examples:
- Too Many Requests
required:
- message
- statusCode
- error
InternalServerError:
type: object
properties:
message:
description: The error message describing the reason for the exception
oneOf:
- type: string
- type: array
items:
type: string
statusCode:
type: number
description: The HTTP status code of the response
examples:
- 500
error:
type: string
description: The type of error
examples:
- Internal Server Error
required:
- message
- statusCode
- error
BadGateway:
type: object
properties:
message:
description: The error message describing the reason for the exception
oneOf:
- type: string
- type: array
items:
type: string
statusCode:
type: number
description: The HTTP status code of the response
examples:
- 502
error:
type: string
description: The type of error
examples:
- Bad Gateway
required:
- message
- statusCode
- error
ServiceUnavailable:
type: object
properties:
message:
description: The error message describing the reason for the exception
oneOf:
- type: string
- type: array
items:
type: string
statusCode:
type: number
description: The HTTP status code of the response
examples:
- 503
error:
type: string
description: The type of error
examples:
- Service Unavailable
required:
- message
- statusCode
- error
PChainBalance:
type: object
properties:
unlockedUnstaked:
description: >-
A list of objects containing P-chain Asset basic info, amount, and
utxo count of that Asset ID. Denotes the amount of unstaked Avax
that is consumable by any transaction.
type: array
items:
$ref: '#/components/schemas/AggregatedAssetAmount'
unlockedStaked:
description: >-
A list of objects containing P-chain Asset basic info, amount, and
utxo count of that Asset ID. Denotes the amount of staked Avax that
is consumable by any transaction when the staking period ends.
type: array
items:
$ref: '#/components/schemas/AggregatedAssetAmount'
lockedPlatform:
description: >-
A list of objects containing P-chain Asset basic info, amount, and
utxo count of that Asset ID. Denotes the amount of unstaked Avax
that is locked at the platform level and not consumable by any
transaction at the current time.
type: array
items:
$ref: '#/components/schemas/AggregatedAssetAmount'
lockedStakeable:
description: >-
A list of objects containing P-chain Asset basic info, amount, and
utxo count of that Asset ID. Denotes the amount of unstaked Avax
that is locked at the platform level and only consumeable for
staking transactions.
type: array
items:
$ref: '#/components/schemas/AggregatedAssetAmount'
lockedStaked:
description: >-
A list of objects containing P-chain Asset basic info, amount, and
utxo count of that Asset ID. Denotes the amount of staked Avax that
will be locked when the staking period ends.
type: array
items:
$ref: '#/components/schemas/AggregatedAssetAmount'
pendingStaked:
description: >-
A list of objects containing P-chain Asset basic info, amount, and
utxo count of that Asset ID. Denotes the amount of staked Avax
whose staking period has not yet started.
type: array
items:
$ref: '#/components/schemas/AggregatedAssetAmount'
atomicMemoryUnlocked:
description: >-
A list of objects containing P-chain Asset basic info, amount and
utxo count of that Asset ID. Denotes the amount of unlocked Avax in
the atomic memory between P-Chain and other chain.
type: array
items:
$ref: '#/components/schemas/PChainSharedAsset'
atomicMemoryLocked:
description: >-
A list of objects containing P-chain Asset basic info, amount and
utxo count of that Asset ID. Denotes the amount of locked Avax in
the atomic memory between P-Chain and other chain.
type: array
items:
$ref: '#/components/schemas/PChainSharedAsset'
required:
- unlockedUnstaked
- unlockedStaked
- lockedPlatform
- lockedStakeable
- lockedStaked
- pendingStaked
- atomicMemoryUnlocked
- atomicMemoryLocked
PrimaryNetworkChainInfo:
type: object
properties:
chainName:
$ref: '#/components/schemas/PrimaryNetworkChainName'
network:
$ref: '#/components/schemas/Network'
required:
- chainName
- network
XChainBalances:
type: object
properties:
locked:
description: A list of objects containing X-chain Asset balance information.
type: array
items:
$ref: '#/components/schemas/AggregatedAssetAmount'
unlocked:
description: A list of objects containing X-chain Asset balance information.
type: array
items:
$ref: '#/components/schemas/AggregatedAssetAmount'
atomicMemoryUnlocked:
type: array
items:
$ref: '#/components/schemas/XChainSharedAssetBalance'
atomicMemoryLocked:
type: array
items:
$ref: '#/components/schemas/XChainSharedAssetBalance'
required:
- locked
- unlocked
- atomicMemoryUnlocked
- atomicMemoryLocked
CChainAtomicBalances:
type: object
properties:
atomicMemoryUnlocked:
type: array
items:
$ref: '#/components/schemas/CChainSharedAssetBalance'
atomicMemoryLocked:
type: array
items:
$ref: '#/components/schemas/CChainSharedAssetBalance'
required:
- atomicMemoryUnlocked
- atomicMemoryLocked
AggregatedAssetAmount:
type: object
properties:
assetId:
type: string
description: Unique ID for an asset.
examples:
- th5aLdWLi32yS9ED6uLGoMMubqHjzMsXhKWwzP6yZTYQKYzof
name:
type: string
description: Name of this asset.
examples:
- Avalanche
symbol:
type: string
description: Symbol for this asset (max 4 characters).
examples:
- AVAX
denomination:
type: number
description: Denomination of this asset to represent fungibility.
examples:
- 9
type:
$ref: '#/components/schemas/PrimaryNetworkAssetType'
examples:
- secp256k1
amount:
type: string
description: Amount of the asset.
examples:
- '5001000'
utxoCount:
type: number
examples:
- 1
required:
- assetId
- name
- symbol
- denomination
- type
- amount
- utxoCount
PChainSharedAsset:
type: object
properties:
assetId:
type: string
description: Unique ID for an asset.
examples:
- th5aLdWLi32yS9ED6uLGoMMubqHjzMsXhKWwzP6yZTYQKYzof
name:
type: string
description: Name of this asset.
examples:
- Avalanche
symbol:
type: string
description: Symbol for this asset (max 4 characters).
examples:
- AVAX
denomination:
type: number
description: Denomination of this asset to represent fungibility.
examples:
- 9
type:
$ref: '#/components/schemas/PrimaryNetworkAssetType'
examples:
- secp256k1
amount:
type: string
description: Amount of the asset.
examples:
- '5001000'
utxoCount:
type: number
examples:
- 1
sharedWithChainId:
type: string
examples:
- 2oYMBNV4eNHyqk2fjjV5nVQLDbtmNJzq5s3qs3Lo6ftnC6FByM
status:
type: string
required:
- assetId
- name
- symbol
- denomination
- type
- amount
- utxoCount
- sharedWithChainId
- status
PrimaryNetworkChainName:
type: string
enum:
- p-chain
- x-chain
- c-chain
XChainSharedAssetBalance:
type: object
properties:
assetId:
type: string
description: Unique ID for an asset.
examples:
- th5aLdWLi32yS9ED6uLGoMMubqHjzMsXhKWwzP6yZTYQKYzof
name:
type: string
description: Name of this asset.
examples:
- Avalanche
symbol:
type: string
description: Symbol for this asset (max 4 characters).
examples:
- AVAX
denomination:
type: number
description: Denomination of this asset to represent fungibility.
examples:
- 9
type:
$ref: '#/components/schemas/PrimaryNetworkAssetType'
examples:
- secp256k1
amount:
type: string
description: Amount of the asset.
examples:
- '5001000'
utxoCount:
type: number
examples:
- 1
sharedWithChainId:
type: string
required:
- assetId
- name
- symbol
- denomination
- type
- amount
- utxoCount
- sharedWithChainId
CChainSharedAssetBalance:
type: object
properties:
assetId:
type: string
description: Unique ID for an asset.
examples:
- th5aLdWLi32yS9ED6uLGoMMubqHjzMsXhKWwzP6yZTYQKYzof
name:
type: string
description: Name of this asset.
examples:
- Avalanche
symbol:
type: string
description: Symbol for this asset (max 4 characters).
examples:
- AVAX
denomination:
type: number
description: Denomination of this asset to represent fungibility.
examples:
- 9
type:
$ref: '#/components/schemas/PrimaryNetworkAssetType'
examples:
- secp256k1
amount:
type: string
description: Amount of the asset.
examples:
- '5001000'
utxoCount:
type: number
examples:
- 1
sharedWithChainId:
type: string
required:
- assetId
- name
- symbol
- denomination
- type
- amount
- utxoCount
- sharedWithChainId
PrimaryNetworkAssetType:
type: string
description: Type of asset like SECP256K1 or NFT.
enum:
- secp256k1
- nft
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-glacier-api-key
description: >-
Api keys provide higher access to rate limits. To obtain an api key,
sign up for an account at https://avacloud.io/.
````