Account endpoints are used to fetch the state of an account (identified by a network-specific identifier).

/account/balance

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.

Request

Schema

{
    "network_identifier": {
        "blockchain": "bitcoin",
        "network": "mainnet",
        "sub_network_identifier": {
            "network": "shard 1",
            "metadata": {
                "producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
            }
        }
    },
    "account_identifier": {
        "address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
        "sub_account": {
            "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
            "metadata": {}
        },
        "metadata": {}
    },
    "block_identifier": {
        "index": 1123941,
        "hash": "0x1f2cc6c5027d2f201a5453ad1119574d2aed23a392654742ac3c78783c071f85"
    },
    "currencies": [
        {
            "symbol": "BTC",
            "decimals": 8,
            "metadata": {
                "Issuer": "Satoshi"
            }
        }
    ]
}

Response

200 - OK

Schema

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

500 - Error

Schema

{
    "code": 12,
    "message": "Invalid account format",
    "description": "This error is returned when the requested AccountIdentifier is improperly formatted.",
    "retriable": true,
    "details": {
        "address": "0x1dcc4de8dec75d7aab85b567b6",
        "error": "not base64"
    }
}

/account/coins

Get an Account's Unspent Coins

Get an array of all unspent coins for an AccountIdentifier and the BlockIdentifier at which the lookup was performed. If your implementation does not support coins (i.e. it is for an account-based blockchain), you do not need to implement this endpoint. If you implementation does support coins (i.e. it is fro a UTXO-based blockchain), you MUST also complete the /account/balance endpoint. It is important to note that making a coins request for an account without populating the SubAccountIdentifier should not result in the coins of all possible SubAccountIdentifiers being returned. Rather, it should result in the coins pertaining to no SubAccountIdentifiers being returned. To get all coins associated with an account, it may be necessary to perform multiple coin requests with unique AccountIdentifiers. Optionally, an implementation may choose to support updating an AccountIdentifier's unspent coins based on the contents of the mempool. Note, using this functionality breaks any guarantee of idempotency.

Request

Schema

{
    "network_identifier": {
        "blockchain": "bitcoin",
        "network": "mainnet",
        "sub_network_identifier": {
            "network": "shard 1",
            "metadata": {
                "producer": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
            }
        }
    },
    "account_identifier": {
        "address": "0x3a065000ab4183c6bf581dc1e55a605455fc6d61",
        "sub_account": {
            "address": "0x6b175474e89094c44da98b954eedeac495271d0f",
            "metadata": {}
        },
        "metadata": {}
    },
    "include_mempool": true,
    "currencies": [
        {
            "symbol": "BTC",
            "decimals": 8,
            "metadata": {
                "Issuer": "Satoshi"
            }
        }
    ]
}

Response

200 - OK

Schema

{
    "block_identifier": {
        "index": 1123941,
        "hash": "0x1f2cc6c5027d2f201a5453ad1119574d2aed23a392654742ac3c78783c071f85"
    },
    "coins": [
        {
            "coin_identifier": {
                "identifier": "0x2f23fd8cca835af21f3ac375bac601f97ead75f2e79143bdf71fe2c4be043e8f:1"
            },
            "amount": {
                "value": "1238089899992",
                "currency": {
                    "symbol": "BTC",
                    "decimals": 8,
                    "metadata": {
                        "Issuer": "Satoshi"
                    }
                },
                "metadata": {}
            }
        }
    ],
    "metadata": {
        "sequence_number": 23
    }
}

500 - Error

Schema

{
    "code": 12,
    "message": "Invalid account format",
    "description": "This error is returned when the requested AccountIdentifier is improperly formatted.",
    "retriable": true,
    "details": {
        "address": "0x1dcc4de8dec75d7aab85b567b6",
        "error": "not base64"
    }
}