gateway_balances

[Source]

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 the hotwallet field is not the Address of an account holding currency issued by the account from the request.
actNotFound - The Address specified in the account field of the request does not correspond to an account in the ledger.
lgrNotFound - The ledger specified by the ledger_hash or ledger_index does not exist, or it does exist but the server does not have it.