gateway_balances
The gateway_balances
command calculates the total balances issued by a given account, optionally excluding amounts held by operational addresses.
Caution: Some public servers disable this API method because it can require a large amount of processing.
Request Format
An example of the request format:
Note
There is no commandline syntax for this method. You can use the json method to access this method from the commandline instead.
{ "id": "example_gateway_balances_1", "command": "gateway_balances", "account": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q", "strict": true, "hotwallet": ["rKm4uWpg9tfwbVSeATv4KxDe6mpE9yPkgJ","ra7JkEzrgeKHdzKgo4EUUVBnxggY4z37kt"], "ledger_index": "validated" }
The request includes the following parameters:
Field | Type | Description |
---|---|---|
account | String | The Address to check. This should be the issuing address |
strict | Boolean | (Optional) If true, only accept an address or public key for the account parameter. Defaults to false. |
hotwallet | String or Array | (Optional) An operational address to exclude from the balances issued, or an array of such addresses. |
ledger_hash | String | (Optional) A 20-byte hex string for the ledger version to use. (See Specifying Ledgers) |
ledger_index | String or Unsigned Integer | (Optional) The ledger index of the ledger version to use, or a shortcut string to choose a ledger automatically. (See Specifying Ledgers) |
Response Format
An example of a successful response:
{ "id": 3, "status": "success", "type": "response", "result": { "account": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q", "assets": { "r9F6wk8HkXrgYWoJ7fsv4VrUBVoqDVtzkH": [ { "currency": "BTC", "value": "5444166510000000e-26" } ], "rPFLkxQk6xUGdGYEykqe7PR25Gr7mLHDc8": [ { "currency": "EUR", "value": "4000000000000000e-27" } ], "rPU6VbckqCLW4kb51CWqZdxvYyQrQVsnSj": [ { "currency": "BTC", "value": "1029900000000000e-26" } ], "rpR95n1iFkTqpoy1e878f4Z1pVHVtWKMNQ": [ { "currency": "BTC", "value": "4000000000000000e-30" } ], "rwmUaXsWtXU4Z843xSYwgt1is97bgY8yj6": [ { "currency": "BTC", "value": "8700000000000000e-30" } ] }, "balances": { "rKm4uWpg9tfwbVSeATv4KxDe6mpE9yPkgJ": [ { "currency": "EUR", "value": "29826.1965999999" } ], "ra7JkEzrgeKHdzKgo4EUUVBnxggY4z37kt": [ { "currency": "USD", "value": "13857.70416" } ] }, "ledger_hash": "61DDBF304AF6E8101576BF161D447CA8E4F0170DDFBEAFFD993DC9383D443388", "ledger_index": 14483195, "obligations": { "BTC": "5908.324927635318", "EUR": "992471.7419793958", "GBP": "4991.38706013193", "USD": "1997134.20229482" }, "validated": true } }
The response follows the standard format, with a successful result containing the following fields:
Field | Type | Description |
---|---|---|
account | String - Address | The address of the account that issued the balances. |
obligations | Object | (Omitted if empty) Total amounts issued to addresses not excluded, as a map of currencies to the total value issued. |
balances | Object | (Omitted if empty) Amounts issued to the hotwallet addresses from the request. The keys are addresses and the values are arrays of currency amounts they hold. |
assets | Object | (Omitted if empty) Total amounts held that are issued by others. In the recommended configuration, the issuing address should have none. |
ledger_hash | String - Hash | (May be omitted) The identifying hash of the ledger version that was used to generate this response. |
ledger_index | Number - Ledger Index | (May be omitted) The ledger index of the ledger version that was used to generate this response. |
ledger_current_index | Number - Ledger Index | (Omitted if ledger_current_index is provided) The ledger index of the current in-progress ledger version, which was used to retrieve this information. |
Possible Errors
- Any of the universal error types.
invalidParams
- One or more fields are specified incorrectly, or one or more required fields are missing.invalidHotWallet
- One or more of the addresses specified in thehotwallet
field is not the Address of an account holding currency issued by the account from the request.actNotFound
- The Address specified in theaccount
field of the request does not correspond to an account in the ledger.lgrNotFound
- The ledger specified by theledger_hash
orledger_index
does not exist, or it does exist but the server does not have it.