ListBalances

ListBalances lists asset balances

Source: taprootassets.proto

gRPC

rpc ListBalances (ListBalancesRequest) returns (ListBalancesResponse);

REST

HTTP Method	Path
GET	/v1/taproot-assets/assets/balance

Code Samples

gRPC

Javascript

const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');

const GRPC_HOST = 'localhost:10029'
const MACAROON_PATH = 'TAPROOT-ASSETS_DIR/regtest/taproot-assets.macaroon'
const TLS_PATH = 'TAPROOT-ASSETS_DIR/tls.cert'

const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true,
};
const packageDefinition = protoLoader.loadSync('taprootassets.proto', loaderOptions);
const taprpc = grpc.loadPackageDefinition(packageDefinition).taprpc;
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const tlsCert = fs.readFileSync(TLS_PATH);
const sslCreds = grpc.credentials.createSsl(tlsCert);
const macaroon = fs.readFileSync(MACAROON_PATH).toString('hex');
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
  let metadata = new grpc.Metadata();
  metadata.add('macaroon', macaroon);
  callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let client = new taprpc.TaprootAssets(GRPC_HOST, creds);
let request = {
  asset_id: <bool>,
  group_key: <bool>,
  asset_filter: <bytes>,
  group_key_filter: <bytes>,
};
client.listBalances(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "asset_balances": <AssetBalancesEntry>,
//    "asset_group_balances": <AssetGroupBalancesEntry>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the taprootassets.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import taprootassets_pb2 as taprpc, taprootassets_pb2_grpc as taprootassetsstub

GRPC_HOST = 'localhost:10029'
MACAROON_PATH = 'TAPROOT-ASSETS_DIR/regtest/taproot-assets.macaroon'
TLS_PATH = 'TAPROOT-ASSETS_DIR/tls.cert'

# create macaroon credentials
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
def metadata_callback(context, callback):
  callback([('macaroon', macaroon)], None)
auth_creds = grpc.metadata_call_credentials(metadata_callback)
# create SSL credentials
os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
cert = open(TLS_PATH, 'rb').read()
ssl_creds = grpc.ssl_channel_credentials(cert)
# combine macaroon and SSL credentials
combined_creds = grpc.composite_channel_credentials(ssl_creds, auth_creds)
# make the request
channel = grpc.secure_channel(GRPC_HOST, combined_creds)
stub = taprootassetsstub.TaprootAssetsStub(channel)
request = taprpc.ListBalancesRequest(
  asset_id=<bool>,
  group_key=<bool>,
  asset_filter=<bytes>,
  group_key_filter=<bytes>,
)
response = stub.ListBalances(request)
print(response)
# {
#    "asset_balances": <AssetBalancesEntry>,
#    "asset_group_balances": <AssetGroupBalancesEntry>,
# }

REST

Javascript

const fs = require('fs');
const request = require('request');

const REST_HOST = 'localhost:8089'
const MACAROON_PATH = 'TAPROOT-ASSETS_DIR/regtest/taproot-assets.macaroon'

let options = {
  url: `https://${REST_HOST}/v1/taproot-assets/assets/balance`,
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': fs.readFileSync(MACAROON_PATH).toString('hex'),
  },
}
request.get(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  {
//    "asset_balances": <object>, // <AssetBalancesEntry> 
//    "asset_group_balances": <object>, // <AssetGroupBalancesEntry> 
//  }

Python

import base64, codecs, json, requests

REST_HOST = 'localhost:8089'
MACAROON_PATH = 'TAPROOT-ASSETS_DIR/regtest/taproot-assets.macaroon'
TLS_PATH = 'TAPROOT-ASSETS_DIR/tls.cert'

url = f'https://{REST_HOST}/v1/taproot-assets/assets/balance'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
r = requests.get(url, headers=headers, verify=TLS_PATH)
print(r.json())
# {
#    "asset_balances": <AssetBalancesEntry>,
#    "asset_group_balances": <AssetGroupBalancesEntry>,
# }

Shell

$ tapcli assets balance --help

NAME:
   tapcli assets balance - list asset balances

USAGE:
   tapcli assets balance [command options] [arguments...]

DESCRIPTION:
   list balances for all assets or a selected asset

OPTIONS:
   --by_group         Group asset balances by group key
   --asset_id value   A specific asset ID to run the balance query against
   --group_key value  A specific asset group key to run the balance query against. Must be used together with --by_group
   

Messages

taprpc.ListBalancesRequest

Source: taprootassets.proto

Field	gRPC Type	REST Type	REST Placement
asset_id Group results by asset IDs.	bool	boolean	query
group_key Group results by group keys.	bool	boolean	query
asset_filter If the query results should grouped by asset ids, then an optional asset filter may be provided to query balance of a specific asset.	bytes	string	query
group_key_filter If the query results should be grouped by group keys, then an optional group key filter may be provided to query the balance of a specific asset group.	bytes	string	query

taprpc.ListBalancesResponse

Source: taprootassets.proto

Field	gRPC Type	REST Type
asset_balances	AssetBalancesEntry[]	object
asset_group_balances	AssetGroupBalancesEntry[]	object

Nested Messages

taprpc.AssetBalance

Field	gRPC Type	REST Type
asset_genesis The base genesis information of an asset. This information never changes.	GenesisInfo	object
balance The balance of the asset owned by the target daemon.	uint64	string

taprpc.AssetGroupBalance

Field	gRPC Type	REST Type
group_key The group key or nil aggregating assets that don't have a group.	bytes	string
balance The total balance of the assets in the group.	uint64	string

taprpc.GenesisInfo

Field	gRPC Type	REST Type
genesis_point The first outpoint of the transaction that created the asset (txid:vout).	string	string
name The name of the asset.	string	string
meta_hash The hash of the meta data for this genesis asset.	bytes	string
asset_id The asset ID that uniquely identifies the asset.	bytes	string
asset_type The type of the asset.	AssetType	string
output_index The index of the output that carries the unique Taproot Asset commitment in the genesis transaction.	uint32	integer

taprpc.ListBalancesResponse.AssetBalancesEntry

Field	gRPC Type	REST Type
key	string	unknown
value	AssetBalance	unknown

taprpc.ListBalancesResponse.AssetGroupBalancesEntry

Field	gRPC Type	REST Type
key	string	unknown
value	AssetGroupBalance	unknown

Enums

taprpc.AssetType

Name	Number
NORMAL Indicates that an asset is capable of being split/merged, with each of the units being fungible, even across a key asset ID boundary (assuming the key group is the same).	0
COLLECTIBLE Indicates that an asset is a collectible, meaning that each of the other items under the same key group are not fully fungible with each other. Collectibles also cannot be split or merged.	1