Bank

Generated from cosmos/cosmos-sdk@2086680ff8b0 on ref release/v0.55.x.

Queries

A node exposes only the services its application registers:

gRPC on port 9090
REST on port 1317, if the method has an HTTP binding

Run grpcurl -plaintext localhost:9090 list to see what a node serves. Queries are read-only and never pass through consensus. See Queries. Replace <string> placeholders with real values and omit unused filters. Payloads use protobuf JSON, and some string fields accept enum constants listed under Types. Field tables give the encoding each value takes. Examples assume a local node. For TLS endpoints, use port 443 and omit -plaintext. See gRPC services for reflection, address formats, and decimal encoding.

AllBalances

AllBalances queries the balance of all coins for a single account. When called from another module, this query might consume a high amount of gas if the pagination field is incorrectly set.


gRPC	`cosmos.bank.v1beta1.Query/AllBalances`
REST	`GET /cosmos/bank/v1beta1/balances/{address}`

Request QueryAllBalancesRequest:

Field	Type	Description
`address`	`string`	address is the address to query balances for. Encoded as cosmos.AddressString.
`pagination`	`PageRequest`	pagination defines an optional pagination for the request.
`resolve_denom`	`bool`	resolve_denom is the flag to resolve the denom into a human-readable form from the metadata.

Response QueryAllBalancesResponse:

Field	Type	Description
`balances`	`Coin`[]	balances is the balances of all the coins.
`pagination`	`PageResponse`	pagination defines the pagination in the response.

grpcurl -plaintext -d '{"address":"<string>","pagination":{"limit":"1"},"resolve_denom":false}' \
  localhost:9090 cosmos.bank.v1beta1.Query/AllBalances

Balance

Balance queries the balance of a single coin for a single account.


gRPC	`cosmos.bank.v1beta1.Query/Balance`
REST	`GET /cosmos/bank/v1beta1/balances/{address}/by_denom`

Request QueryBalanceRequest:

Field	Type	Description
`address`	`string`	address is the address to query balances for. Encoded as cosmos.AddressString.
`denom`	`string`	denom is the coin denom to query balances for.

Response QueryBalanceResponse:

Field	Type	Description
`balance`	`Coin`	balance is the balance of the coin.

grpcurl -plaintext -d '{"address":"<string>","denom":"<string>"}' \
  localhost:9090 cosmos.bank.v1beta1.Query/Balance

DenomMetadata

DenomMetadata queries the client metadata of a given coin denomination.


gRPC	`cosmos.bank.v1beta1.Query/DenomMetadata`
REST	`GET /cosmos/bank/v1beta1/denoms_metadata/{denom}`

Request QueryDenomMetadataRequest:

Field	Type	Description
`denom`	`string`	denom is the coin denom to query the metadata for.

Response QueryDenomMetadataResponse:

Field	Type	Description
`metadata`	`Metadata`	metadata describes and provides all the client information for the requested token.

grpcurl -plaintext -d '{"denom":"<string>"}' \
  localhost:9090 cosmos.bank.v1beta1.Query/DenomMetadata

DenomMetadataByQueryString

DenomMetadataByQueryString queries the client metadata of a given coin denomination.


gRPC	`cosmos.bank.v1beta1.Query/DenomMetadataByQueryString`
REST	`GET /cosmos/bank/v1beta1/denoms_metadata_by_query_string`

Request QueryDenomMetadataByQueryStringRequest:

Field	Type	Description
`denom`	`string`	denom is the coin denom to query the metadata for.

Response QueryDenomMetadataByQueryStringResponse:

Field	Type	Description
`metadata`	`Metadata`	metadata describes and provides all the client information for the requested token.

grpcurl -plaintext -d '{"denom":"<string>"}' \
  localhost:9090 cosmos.bank.v1beta1.Query/DenomMetadataByQueryString

DenomOwners

DenomOwners queries for all account addresses that own a particular token denomination. When called from another module, this query might consume a high amount of gas if the pagination field is incorrectly set.


gRPC	`cosmos.bank.v1beta1.Query/DenomOwners`
REST	`GET /cosmos/bank/v1beta1/denom_owners/{denom}`

Request QueryDenomOwnersRequest:

Field	Type	Description
`denom`	`string`	denom defines the coin denomination to query all account holders for.
`pagination`	`PageRequest`	pagination defines an optional pagination for the request.

Response QueryDenomOwnersResponse:

Field	Type	Description
`denom_owners`	`DenomOwner`[]
`pagination`	`PageResponse`	pagination defines the pagination in the response.

grpcurl -plaintext -d '{"denom":"<string>","pagination":{"limit":"1"}}' \
  localhost:9090 cosmos.bank.v1beta1.Query/DenomOwners

DenomOwnersByQuery

DenomOwnersByQuery queries for all account addresses that own a particular token denomination.


gRPC	`cosmos.bank.v1beta1.Query/DenomOwnersByQuery`
REST	`GET /cosmos/bank/v1beta1/denom_owners_by_query`

Request QueryDenomOwnersByQueryRequest:

Field	Type	Description
`denom`	`string`	denom defines the coin denomination to query all account holders for.
`pagination`	`PageRequest`	pagination defines an optional pagination for the request.

Response QueryDenomOwnersByQueryResponse:

Field	Type	Description
`denom_owners`	`DenomOwner`[]
`pagination`	`PageResponse`	pagination defines the pagination in the response.

grpcurl -plaintext -d '{"denom":"<string>","pagination":{"limit":"1"}}' \
  localhost:9090 cosmos.bank.v1beta1.Query/DenomOwnersByQuery

DenomsMetadata

DenomsMetadata queries the client metadata for all registered coin denominations.


gRPC	`cosmos.bank.v1beta1.Query/DenomsMetadata`
REST	`GET /cosmos/bank/v1beta1/denoms_metadata`

Request QueryDenomsMetadataRequest:

Field	Type	Description
`pagination`	`PageRequest`	pagination defines an optional pagination for the request.

Response QueryDenomsMetadataResponse:

Field	Type	Description
`metadatas`	`Metadata`[]	metadata provides the client information for all the registered tokens.
`pagination`	`PageResponse`	pagination defines the pagination in the response.

grpcurl -plaintext -d '{"pagination":{"limit":"1"}}' \
  localhost:9090 cosmos.bank.v1beta1.Query/DenomsMetadata

Params

Params queries the parameters of x/bank module.


gRPC	`cosmos.bank.v1beta1.Query/Params`
REST	`GET /cosmos/bank/v1beta1/params`

Request QueryParamsRequest: This message has no fields. Response QueryParamsResponse:

Field	Type	Description
`params`	`Params`	params provides the parameters of the bank module.

grpcurl -plaintext localhost:9090 cosmos.bank.v1beta1.Query/Params

SendEnabled

SendEnabled queries for SendEnabled entries. This query only returns denominations that have specific SendEnabled settings. Any denomination that does not have a specific setting will use the default params.default_send_enabled, and will not be returned by this query.


gRPC	`cosmos.bank.v1beta1.Query/SendEnabled`
REST	`GET /cosmos/bank/v1beta1/send_enabled`

Request QuerySendEnabledRequest:

Field	Type	Description
`denoms`	`string`[]	denoms is the specific denoms you want look up. Leave empty to get all entries.
`pagination`	`PageRequest`	pagination defines an optional pagination for the request. This field is only read if the denoms field is empty.

Response QuerySendEnabledResponse:

Field	Type	Description
`send_enabled`	`SendEnabled`[]
`pagination`	`PageResponse`	pagination defines the pagination in the response. This field is only populated if the denoms field in the request is empty.

grpcurl -plaintext -d '{"denoms":["<string>"],"pagination":{"limit":"1"}}' \
  localhost:9090 cosmos.bank.v1beta1.Query/SendEnabled

SpendableBalanceByDenom

SpendableBalanceByDenom queries the spendable balance of a single denom for a single account. When called from another module, this query might consume a high amount of gas if the pagination field is incorrectly set.


gRPC	`cosmos.bank.v1beta1.Query/SpendableBalanceByDenom`
REST	`GET /cosmos/bank/v1beta1/spendable_balances/{address}/by_denom`

Request QuerySpendableBalanceByDenomRequest:

Field	Type	Description
`address`	`string`	address is the address to query balances for. Encoded as cosmos.AddressString.
`denom`	`string`	denom is the coin denom to query balances for.

Response QuerySpendableBalanceByDenomResponse:

Field	Type	Description
`balance`	`Coin`	balance is the balance of the coin.

grpcurl -plaintext -d '{"address":"<string>","denom":"<string>"}' \
  localhost:9090 cosmos.bank.v1beta1.Query/SpendableBalanceByDenom

SpendableBalances

SpendableBalances queries the spendable balance of all coins for a single account. When called from another module, this query might consume a high amount of gas if the pagination field is incorrectly set.


gRPC	`cosmos.bank.v1beta1.Query/SpendableBalances`
REST	`GET /cosmos/bank/v1beta1/spendable_balances/{address}`

Request QuerySpendableBalancesRequest:

Field	Type	Description
`address`	`string`	address is the address to query spendable balances for. Encoded as cosmos.AddressString.
`pagination`	`PageRequest`	pagination defines an optional pagination for the request.

Response QuerySpendableBalancesResponse:

Field	Type	Description
`balances`	`Coin`[]	balances is the spendable balances of all the coins.
`pagination`	`PageResponse`	pagination defines the pagination in the response.

grpcurl -plaintext -d '{"address":"<string>","pagination":{"limit":"1"}}' \
  localhost:9090 cosmos.bank.v1beta1.Query/SpendableBalances

SupplyOf

SupplyOf queries the supply of a single coin. When called from another module, this query might consume a high amount of gas if the pagination field is incorrectly set.


gRPC	`cosmos.bank.v1beta1.Query/SupplyOf`
REST	`GET /cosmos/bank/v1beta1/supply/by_denom`

Request QuerySupplyOfRequest:

Field	Type	Description
`denom`	`string`	denom is the coin denom to query balances for.

Response QuerySupplyOfResponse:

Field	Type	Description
`amount`	`Coin`	amount is the supply of the coin.

grpcurl -plaintext -d '{"denom":"<string>"}' \
  localhost:9090 cosmos.bank.v1beta1.Query/SupplyOf

TotalSupply

TotalSupply queries the total supply of all coins. When called from another module, this query might consume a high amount of gas if the pagination field is incorrectly set.


gRPC	`cosmos.bank.v1beta1.Query/TotalSupply`
REST	`GET /cosmos/bank/v1beta1/supply`

Request QueryTotalSupplyRequest:

Field	Type	Description
`pagination`	`PageRequest`	pagination defines an optional pagination for the request.

Response QueryTotalSupplyResponse:

Field	Type	Description
`supply`	`Coin`[]	supply is the supply of the coins
`pagination`	`PageResponse`	pagination defines the pagination in the response.

grpcurl -plaintext -d '{"pagination":{"limit":"1"}}' \
  localhost:9090 cosmos.bank.v1beta1.Query/TotalSupply

Transaction messages

These messages are included in signed transactions, not called as endpoints. See Transactions for the execution model, and Sending transactions for the envelope they go into. Examples use CLI transaction JSON. Decimal fields use values such as "0.05", even when their proto type is bytes. The gRPC TxEncode method instead requires the scaled value "50000000000000000". See scalar encodings.

Handler: Generated client method
Signer: Account that must sign
Amino name: Legacy identifier used by hardware wallets and other Amino signers

MultiSend

MultiSend defines a method for sending coins from some accounts to other accounts.


Type URL	`/cosmos.bank.v1beta1.MsgMultiSend`
Handler	`cosmos.bank.v1beta1.Msg/MultiSend`
Signer	`inputs`
Amino name	`cosmos-sdk/MsgMultiSend`

Field	Type	Description
`inputs`	`Input`[]	Inputs, despite being `repeated`, only allows one sender input. This is checked in MsgMultiSend’s ValidateBasic.
`outputs`	`Output`[]

In a transaction:

{
  "@type": "/cosmos.bank.v1beta1.MsgMultiSend",
  "inputs": [
    {
      "address": "<string>",
      "coins": [
        {
          "denom": "<string>",
          "amount": "<string>"
        }
      ]
    }
  ],
  "outputs": [
    {
      "address": "<string>",
      "coins": [
        {
          "denom": "<string>",
          "amount": "<string>"
        }
      ]
    }
  ]
}

Response MsgMultiSendResponse: This message has no fields.

Send

Send defines a method for sending coins from one account to another account.


Type URL	`/cosmos.bank.v1beta1.MsgSend`
Handler	`cosmos.bank.v1beta1.Msg/Send`
Signer	`from_address`
Amino name	`cosmos-sdk/MsgSend`

Field	Type	Description
`from_address`	`string`	Encoded as cosmos.AddressString.
`to_address`	`string`	Encoded as cosmos.AddressString.
`amount`	`Coin`[]

In a transaction:

{
  "@type": "/cosmos.bank.v1beta1.MsgSend",
  "from_address": "<string>",
  "to_address": "<string>",
  "amount": [
    {
      "denom": "<string>",
      "amount": "<string>"
    }
  ]
}

Response MsgSendResponse: This message has no fields.

SetSendEnabled

SetSendEnabled is a governance operation for setting the SendEnabled flag on any number of Denoms. Only the entries to add or update should be included. Entries that already exist in the store, but that aren’t included in this message, will be left unchanged.


Type URL	`/cosmos.bank.v1beta1.MsgSetSendEnabled`
Handler	`cosmos.bank.v1beta1.Msg/SetSendEnabled`
Signer	`authority`
Amino name	`cosmos-sdk/MsgSetSendEnabled`

The signer is the governance module account, which no user holds a key for. This message executes only through a passed governance proposal, not as a transaction you submit directly.

Field	Type	Description
`authority`	`string`	authority is the address that controls the module. Encoded as cosmos.AddressString.
`send_enabled`	`SendEnabled`[]	send_enabled is the list of entries to add or update.
`use_default_for`	`string`[]	use_default_for is a list of denoms that should use the params.default_send_enabled value. Denoms listed here will have their SendEnabled entries deleted. If a denom is included that doesn’t have a SendEnabled entry, it will be ignored.

In a transaction:

{
  "@type": "/cosmos.bank.v1beta1.MsgSetSendEnabled",
  "authority": "<string>",
  "send_enabled": [
    {
      "denom": "<string>",
      "enabled": false
    }
  ],
  "use_default_for": [
    "<string>"
  ]
}

Response MsgSetSendEnabledResponse: This message has no fields.

UpdateParams

UpdateParams defines a governance operation for updating the x/bank module parameters. The authority is defined in the keeper.


Type URL	`/cosmos.bank.v1beta1.MsgUpdateParams`
Handler	`cosmos.bank.v1beta1.Msg/UpdateParams`
Signer	`authority`
Amino name	`cosmos-sdk/x/bank/MsgUpdateParams`

The signer is the governance module account, which no user holds a key for. This message executes only through a passed governance proposal, not as a transaction you submit directly.

Field	Type	Description
`authority`	`string`	authority is the address that controls the module (defaults to x/gov unless overwritten). Encoded as cosmos.AddressString.
`params`	`Params`	params defines the x/bank parameters to update. NOTE: All parameters must be supplied.

In a transaction:

{
  "@type": "/cosmos.bank.v1beta1.MsgUpdateParams",
  "authority": "<string>",
  "params": {
    "default_send_enabled": false
  }
}

Response MsgUpdateParamsResponse: This message has no fields.

Types

Messages referenced by the fields above. Protocol buffers version 3 has no required fields, so every field is optional on the wire, and a [] suffix marks a repeated field.

cosmos.bank.v1beta1.DenomOwner

DenomOwner defines structure representing an account that owns or holds a particular denominated token. It contains the account address and account balance of the denominated token.

Field	Type	Description
`address`	`string`	address defines the address that owns a particular denomination. Encoded as cosmos.AddressString.
`balance`	`Coin`	balance is the balance of the denominated coin for an account.

cosmos.bank.v1beta1.DenomUnit

DenomUnit represents a struct that describes a given denomination unit of the basic token.

Field	Type	Description
`denom`	`string`	denom represents the string name of the given denom unit (e.g uatom).
`exponent`	`uint32`	exponent represents power of 10 exponent that one must raise the base_denom to in order to equal the given DenomUnit’s denom 1 denom = 10^exponent base_denom (e.g. with a base_denom of uatom, one can create a DenomUnit of ‘atom’ with exponent = 6, thus: 1 atom = 10^6 uatom).
`aliases`	`string`[]	aliases is a list of string aliases for the given denom

cosmos.bank.v1beta1.Input

Input models transaction input.

Field	Type	Description
`address`	`string`	Encoded as cosmos.AddressString.
`coins`	`Coin`[]

cosmos.bank.v1beta1.Metadata

Metadata represents a struct that describes a basic token.

Field	Type	Description
`description`	`string`
`denom_units`	`DenomUnit`[]	denom_units represents the list of DenomUnit’s for a given coin
`base`	`string`	base represents the base denom (should be the DenomUnit with exponent = 0).
`display`	`string`	display indicates the suggested denom that should be displayed in clients.
`name`	`string`	name defines the name of the token (eg: Cosmos Atom)
`symbol`	`string`	symbol is the token symbol usually shown on exchanges (eg: ATOM). This can be the same as the display.
`uri`	`string`	URI to a document (on or off-chain) that contains additional information. Optional.
`uri_hash`	`string`	URIHash is a sha256 hash of a document pointed by URI. It’s used to verify that the document didn’t change. Optional.

cosmos.bank.v1beta1.Output

Output models transaction outputs.

Field	Type	Description
`address`	`string`	Encoded as cosmos.AddressString.
`coins`	`Coin`[]

cosmos.bank.v1beta1.Params

Params defines the parameters for the bank module.

Field	Type	Description
`send_enabled`	`SendEnabled`[]	Deprecated: Use of SendEnabled in params is deprecated. For genesis, use the newly added send_enabled field in the genesis object. Storage, lookup, and manipulation of this information is now in the keeper. As of cosmos-sdk 0.47, this only exists for backwards compatibility of genesis files. Deprecated.
`default_send_enabled`	`bool`

cosmos.bank.v1beta1.SendEnabled

SendEnabled maps coin denom to a send_enabled status (whether a denom is sendable).

Field	Type	Description
`denom`	`string`
`enabled`	`bool`

cosmos.base.query.v1beta1.PageRequest

PageRequest is to be embedded in gRPC request messages for efficient pagination. Ex: message SomeRequest { Foo some_parameter = 1; PageRequest pagination = 2; }

Field	Type	Description
`key`	`bytes`	key is a value returned in PageResponse.next_key to begin querying the next page most efficiently. Only one of offset or key should be set.
`offset`	`uint64`	offset is a numeric offset that can be used when key is unavailable. It is less efficient than using key. Only one of offset or key should be set.
`limit`	`uint64`	limit is the total number of results to be returned in the result page. If left empty it will default to a value to be set by each app.
`count_total`	`bool`	count_total is set to true to indicate that the result set should include a count of the total number of items available for pagination in UIs. count_total is only respected when offset is used. It is ignored when key is set.
`reverse`	`bool`	reverse is set to true if results are to be returned in the descending order.

cosmos.base.query.v1beta1.PageResponse

PageResponse is to be embedded in gRPC response messages where the corresponding request message has used PageRequest. message SomeResponse { repeated Bar results = 1; PageResponse page = 2; }

Field	Type	Description
`next_key`	`bytes`	next_key is the key to be passed to PageRequest.key to query the next page most efficiently. It will be empty if there are no more results.
`total`	`uint64`	total is total number of results available if PageRequest.count_total was set, its value is undefined otherwise

cosmos.base.v1beta1.Coin

Coin defines a token with a denomination and an amount. NOTE: The amount field is an Int which implements the custom method signatures required by gogoproto.

Field	Type	Description
`denom`	`string`
`amount`	`string`	Encoded as cosmos.Int.

Overview

gRPC Services

REST (gRPC Gateway)

Queries

AllBalances

Balance

DenomMetadata

DenomMetadataByQueryString

DenomOwners

DenomOwnersByQuery

DenomsMetadata

Params

SendEnabled

SpendableBalanceByDenom

SpendableBalances

SupplyOf

TotalSupply

Transaction messages

MultiSend

Send

SetSendEnabled

UpdateParams

Types

cosmos.bank.v1beta1.DenomOwner

cosmos.bank.v1beta1.DenomUnit

cosmos.bank.v1beta1.Input

cosmos.bank.v1beta1.Metadata

cosmos.bank.v1beta1.Output

cosmos.bank.v1beta1.Params

cosmos.bank.v1beta1.SendEnabled

cosmos.base.query.v1beta1.PageRequest

cosmos.base.query.v1beta1.PageResponse

cosmos.base.v1beta1.Coin

​Queries

​AllBalances

​Balance

​DenomMetadata

​DenomMetadataByQueryString

​DenomOwners

​DenomOwnersByQuery

​DenomsMetadata

​Params

​SendEnabled

​SpendableBalanceByDenom

​SpendableBalances

​SupplyOf

​TotalSupply

​Transaction messages

​MultiSend

​Send

​SetSendEnabled

​UpdateParams

​Types

​cosmos.bank.v1beta1.DenomOwner

​cosmos.bank.v1beta1.DenomUnit

​cosmos.bank.v1beta1.Input

​cosmos.bank.v1beta1.Metadata

​cosmos.bank.v1beta1.Output

​cosmos.bank.v1beta1.Params

​cosmos.bank.v1beta1.SendEnabled

​cosmos.base.query.v1beta1.PageRequest

​cosmos.base.query.v1beta1.PageResponse

​cosmos.base.v1beta1.Coin

Queries

AllBalances

Balance

DenomMetadata

DenomMetadataByQueryString

DenomOwners

DenomOwnersByQuery

DenomsMetadata

Params

SendEnabled

SpendableBalanceByDenom

SpendableBalances

SupplyOf

TotalSupply

Transaction messages

MultiSend

Send

SetSendEnabled

UpdateParams

Types

cosmos.bank.v1beta1.DenomOwner

cosmos.bank.v1beta1.DenomUnit

cosmos.bank.v1beta1.Input

cosmos.bank.v1beta1.Metadata

cosmos.bank.v1beta1.Output

cosmos.bank.v1beta1.Params

cosmos.bank.v1beta1.SendEnabled

cosmos.base.query.v1beta1.PageRequest

cosmos.base.query.v1beta1.PageResponse

cosmos.base.v1beta1.Coin