Get an Account's Balance

curl --request POST \
  --url https://example.com/account/balance \
  --header 'Content-Type: application/json' \
  --data '{
  "network_identifier": {
    "blockchain": "bitcoin",
    "network": "mainnet",
    "sub_network_identifier": {
      "network": "shard 1",
      "metadata": {
        "producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
      }
    }
  },
  "account_identifier": {
    "address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
    "sub_account": {
      "address": "0x6b175474e89094c44da98b954eedeac495271d0f"
    }
  },
  "block_identifier": {
    "index": 1123941,
    "hash": "0x1f2cc6c5027d2f201a5453ad1119574d2aed23a392654742ac3c78783c071f85"
  },
  "currencies": [
    {
      "symbol": "BTC",
      "decimals": 8,
      "metadata": {
        "Issuer": "Satoshi"
      }
    }
  ]
}'

{
  "block_identifier": {
    "index": 1123941,
    "hash": "0x1f2cc6c5027d2f201a5453ad1119574d2aed23a392654742ac3c78783c071f85"
  },
  "balances": [
    {
      "value": "1238089899992",
      "currency": {
        "symbol": "BTC",
        "decimals": 8,
        "metadata": {
          "Issuer": "Satoshi"
        }
      }
    }
  ],
  "metadata": {
    "sequence_number": 23
  }
}

Account

Get an Account's Balance

Get an array of all AccountBalances for an AccountIdentifier and the BlockIdentifier at which the balance lookup was performed. The BlockIdentifier must always be returned because some consumers of account balance data need to know specifically at which block the balance was calculated to compare balances they compute from operations with the balance returned by the node. It is important to note that making a balance request for an account without populating the SubAccountIdentifier should not result in the balance of all possible SubAccountIdentifiers being returned. Rather, it should result in the balance pertaining to no SubAccountIdentifiers being returned (sometimes called the liquid balance). To get all balances associated with an account, it may be necessary to perform multiple balance requests with unique AccountIdentifiers. It is also possible to perform a historical balance lookup (if the server supports it) by passing in an optional BlockIdentifier.

POST

account

balance

curl --request POST \
  --url https://example.com/account/balance \
  --header 'Content-Type: application/json' \
  --data '{
  "network_identifier": {
    "blockchain": "bitcoin",
    "network": "mainnet",
    "sub_network_identifier": {
      "network": "shard 1",
      "metadata": {
        "producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
      }
    }
  },
  "account_identifier": {
    "address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
    "sub_account": {
      "address": "0x6b175474e89094c44da98b954eedeac495271d0f"
    }
  },
  "block_identifier": {
    "index": 1123941,
    "hash": "0x1f2cc6c5027d2f201a5453ad1119574d2aed23a392654742ac3c78783c071f85"
  },
  "currencies": [
    {
      "symbol": "BTC",
      "decimals": 8,
      "metadata": {
        "Issuer": "Satoshi"
      }
    }
  ]
}'

{
  "block_identifier": {
    "index": 1123941,
    "hash": "0x1f2cc6c5027d2f201a5453ad1119574d2aed23a392654742ac3c78783c071f85"
  },
  "balances": [
    {
      "value": "1238089899992",
      "currency": {
        "symbol": "BTC",
        "decimals": 8,
        "metadata": {
          "Issuer": "Satoshi"
        }
      }
    }
  ],
  "metadata": {
    "sequence_number": 23
  }
}

Body

application/json

An AccountBalanceRequest is utilized to make a balance request on the /account/balance endpoint. If the block_identifier is populated, a historical balance query should be performed.

network_identifier

object

required

The network_identifier specifies which network a particular object is associated with.

Show child attributes

network_identifier.blockchain

string

required

Example:

"bitcoin"

network_identifier.network

string

required

If a blockchain has a specific chain-id or network identifier, it should go in this field. It is up to the client to determine which network-specific identifier is mainnet or testnet.

Example:

"mainnet"

network_identifier.sub_network_identifier

object

In blockchains with sharded state, the SubNetworkIdentifier is required to query some object on a specific shard. This identifier is optional for all non-sharded blockchains.

Show child attributes

network_identifier.sub_network_identifier.network

string

required

Example:

"shard 1"

network_identifier.sub_network_identifier.metadata

object

Example:

{
  "producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
}

account_identifier

object

required

The account_identifier uniquely identifies an account within a network. All fields in the account_identifier are utilized to determine this uniqueness (including the metadata field, if populated).

Show child attributes

account_identifier.address

string

required

The address may be a cryptographic public key (or some encoding of it) or a provided username.

Example:

"0x3a065000ab4183c6bf581dc1e55a605455fc6d61"

account_identifier.sub_account

object

An account may have state specific to a contract address (ERC-20 token) and/or a stake (delegated balance). The sub_account_identifier should specify which state (if applicable) an account instantiation refers to.

Show child attributes

account_identifier.sub_account.address

string

required

The SubAccount address may be a cryptographic value or some other identifier (ex: bonded) that uniquely specifies a SubAccount.

Example:

"0x6b175474e89094c44da98b954eedeac495271d0f"

account_identifier.sub_account.metadata

object

If the SubAccount address is not sufficient to uniquely specify a SubAccount, any other identifying information can be stored here. It is important to note that two SubAccounts with identical addresses but differing metadata will not be considered equal by clients.

account_identifier.metadata

object

Blockchains that utilize a username model (where the address is not a derivative of a cryptographic public key) should specify the public key(s) owned by the address in metadata.

block_identifier

object

When fetching data by BlockIdentifier, it may be possible to only specify the index or hash. If neither property is specified, it is assumed that the client is making a request at the current block.

Show child attributes

block_identifier.index

integer<int64>

Example:

1123941

block_identifier.hash

string

Example:

"0x1f2cc6c5027d2f201a5453ad1119574d2aed23a392654742ac3c78783c071f85"

currencies

object[]

In some cases, the caller may not want to retrieve all available balances for an AccountIdentifier. If the currencies field is populated, only balances for the specified currencies will be returned. If not populated, all available balances will be returned.

Currency is composed of a canonical Symbol and Decimals. This Decimals value is used to convert an Amount.Value from atomic units (Satoshis) to standard units (Bitcoins).

Show child attributes

symbol

string

required

Canonical symbol associated with a currency.

Example:

"BTC"

decimals

integer<int32>

required

Number of decimal places in the standard unit representation of the amount. For example, BTC has 8 decimals. Note that it is not possible to represent the value of some currency in atomic units that is not base 10.

Required range: x >= 0

Example:

8

metadata

object

Any additional information related to the currency itself. For example, it would be useful to populate this object with the contract address of an ERC-20 token.

Example:

{ "Issuer": "Satoshi" }

Response

Expected response to a valid request

An AccountBalanceResponse is returned on the /account/balance endpoint. If an account has a balance for each AccountIdentifier describing it (ex: an ERC-20 token balance on a few smart contracts), an account balance request must be made with each AccountIdentifier. The coins field was removed and replaced by by /account/coins in v1.4.7.

block_identifier

object

required

The block_identifier uniquely identifies a block in a particular network.

Show child attributes

block_identifier.index

integer<int64>

required

This is also known as the block height.

Example:

1123941

block_identifier.hash

string

required

Example:

"0x1f2cc6c5027d2f201a5453ad1119574d2aed23a392654742ac3c78783c071f85"

balances

object[]

required

A single account may have a balance in multiple currencies.

Amount is some Value of a Currency. It is considered invalid to specify a Value without a Currency.

Show child attributes

value

string

required

Value of the transaction in atomic units represented as an arbitrary-sized signed integer. For example, 1 BTC would be represented by a value of 100000000.

Example:

"1238089899992"

currency

object

required

Currency is composed of a canonical Symbol and Decimals. This Decimals value is used to convert an Amount.Value from atomic units (Satoshis) to standard units (Bitcoins).

Show child attributes

currency.symbol

string

required

Canonical symbol associated with a currency.

Example:

"BTC"

currency.decimals

integer<int32>

required

Required range: x >= 0

Example:

8

currency.metadata

object

Any additional information related to the currency itself. For example, it would be useful to populate this object with the contract address of an ERC-20 token.

Example:

{ "Issuer": "Satoshi" }

metadata

object

metadata

object

Account-based blockchains that utilize a nonce or sequence number should include that number in the metadata. This number could be unique to the identifier or global across the account address.

Example:

{ "sequence_number": 23 }

Get an Account's Unspent Coins

⌘I

MESH

Body

Response