Skip to main content
logo
BlogForum

bank

The bank module is responsible for handling token transfer functionalities such as multi-asset coin transfers between accounts and tracking special-case pseudo-transfers which must work differently with particular kinds of accounts (notably delegating/undelegating for vesting accounts). It exposes several interfaces with varying capabilities for secure interaction with other modules which must alter user balances.

In addition, the bank module tracks and provides query support for the total supply of all assets used in the application.

For more information, visit https://docs.cosmos.network/main/modules/bank/

Message Types​

Msg defines the bank Msg service.

tx.proto
Copy
service Msg {
// Send defines a method for sending coins from one account to another account.
rpc Send(MsgSend) returns (MsgSendResponse);

// MultiSend defines a method for sending coins from some accounts to other accounts.
rpc MultiSend(MsgMultiSend) returns (MsgMultiSendResponse);
}

MsgSend​

MsgSend represents a message to send coins from one account to another.

tx.proto
Copy
message MsgSend {
option (cosmos.msg.v1.signer) = "from_address";

option (gogoproto.equal) = false;
option (gogoproto.goproto_getters) = false;

string from_address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
string to_address = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"];
repeated cosmos.base.v1beta1.Coin amount = 3
[(gogoproto.nullable) = false, (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.Coins"];
}

MsgSendResponse​

MsgSendResponse defines the Msg/Send response type.

tx.proto
Copy
message MsgSendResponse {}

MsgMultiSend​

MsgMultiSend represents an arbitrary multi-in, multi-out send message.

tx.proto
Copy
message MsgMultiSend {
option (cosmos.msg.v1.signer) = "inputs";

option (gogoproto.equal) = false;

repeated Input inputs = 1 [(gogoproto.nullable) = false];
repeated Output outputs = 2 [(gogoproto.nullable) = false];
}

MsgMultiSendResponse​

MsgMultiSendResponse defines the Msg/MultiSend response type.

tx.proto
Copy
message MsgMultiSendResponse {}

Queries​

Query defines the gRPC querier service.

query.proto
Copy
service Query {
// Balance queries the balance of a single coin for a single account.
rpc Balance(QueryBalanceRequest) returns (QueryBalanceResponse) {
option (google.api.http).get = "/cosmos/bank/v1beta1/balances/{address}/by_denom";
}

// AllBalances queries the balance of all coins for a single account.
rpc AllBalances(QueryAllBalancesRequest) returns (QueryAllBalancesResponse) {
option (google.api.http).get = "/cosmos/bank/v1beta1/balances/{address}";
}

// SpendableBalances queries the spenable balance of all coins for a single
// account.
rpc SpendableBalances(QuerySpendableBalancesRequest) returns (QuerySpendableBalancesResponse) {
option (google.api.http).get = "/cosmos/bank/v1beta1/spendable_balances/{address}";
}

// TotalSupply queries the total supply of all coins.
rpc TotalSupply(QueryTotalSupplyRequest) returns (QueryTotalSupplyResponse) {
option (google.api.http).get = "/cosmos/bank/v1beta1/supply";
}

// SupplyOf queries the supply of a single coin.
rpc SupplyOf(QuerySupplyOfRequest) returns (QuerySupplyOfResponse) {
option (google.api.http).get = "/cosmos/bank/v1beta1/supply/by_denom";
}

// Params queries the parameters of x/bank module.
rpc Params(QueryParamsRequest) returns (QueryParamsResponse) {
option (google.api.http).get = "/cosmos/bank/v1beta1/params";
}

// DenomsMetadata queries the client metadata of a given coin denomination.
rpc DenomMetadata(QueryDenomMetadataRequest) returns (QueryDenomMetadataResponse) {
option (google.api.http).get = "/cosmos/bank/v1beta1/denoms_metadata/{denom}";
}

// DenomsMetadata queries the client metadata for all registered coin
// denominations.
rpc DenomsMetadata(QueryDenomsMetadataRequest) returns (QueryDenomsMetadataResponse) {
option (google.api.http).get = "/cosmos/bank/v1beta1/denoms_metadata";
}

// DenomOwners queries for all account addresses that own a particular token
// denomination.
rpc DenomOwners(QueryDenomOwnersRequest) returns (QueryDenomOwnersResponse) {
option (google.api.http).get = "/cosmos/bank/v1beta1/denom_owners/{denom}";
}
}

QueryBalanceRequest​

QueryBalanceRequest is the request type for the Query/Balance RPC method.

query.proto
Copy
message QueryBalanceRequest {
option (gogoproto.equal) = false;
option (gogoproto.goproto_getters) = false;

// address is the address to query balances for.
string address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];

// denom is the coin denom to query balances for.
string denom = 2;
}

QueryBalanceResponse​

QueryBalanceResponse is the response type for the Query/Balance RPC method.

query.proto
Copy
message QueryBalanceResponse {
// balance is the balance of the coin.
cosmos.base.v1beta1.Coin balance = 1;
}

QueryAllBalanceRequest​

QueryAllBalanceRequest is the request type for the Query/AllBalances RPC method.

query.proto
Copy
message QueryAllBalancesRequest {
option (gogoproto.equal) = false;
option (gogoproto.goproto_getters) = false;

// address is the address to query balances for.
string address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];

// pagination defines an optional pagination for the request.
cosmos.base.query.v1beta1.PageRequest pagination = 2;
}

QueryAllBalancesResponse​

QueryAllBalancesResponse is the response type for the Query/AllBalances RPC method.

query.proto
Copy
message QueryAllBalancesResponse {
// balances is the balances of all the coins.
repeated cosmos.base.v1beta1.Coin balances = 1
[(gogoproto.nullable) = false, (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.Coins"];

// pagination defines the pagination in the response.
cosmos.base.query.v1beta1.PageResponse pagination = 2;
}

QuerySpendableBalancesRequest​

QuerySpendableBalancesRequest defines the gRPC request structure for querying an account's spendable balances.

query.proto
Copy
message QuerySpendableBalancesRequest {
option (gogoproto.equal) = false;
option (gogoproto.goproto_getters) = false;

// address is the address to query spendable balances for.
string address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];

// pagination defines an optional pagination for the request.
cosmos.base.query.v1beta1.PageRequest pagination = 2;
}

QuerySpendableBalancesResponse​

QuerySpendableBalancesResponse defines the gRPC response structure for querying an account's spendable balances.

query.proto
Copy
message QuerySpendableBalancesResponse {
// balances is the spendable balances of all the coins.
repeated cosmos.base.v1beta1.Coin balances = 1
[(gogoproto.nullable) = false, (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.Coins"];

// pagination defines the pagination in the response.
cosmos.base.query.v1beta1.PageResponse pagination = 2;
}

QueryTotalSupplyRequest​

QueryTotalSupplyRequest is the request type for the Query/TotalSupply RPC method.

query.proto
Copy
message QueryTotalSupplyRequest {
option (gogoproto.equal) = false;
option (gogoproto.goproto_getters) = false;

// pagination defines an optional pagination for the request.
//
// Since: cosmos-sdk 0.43
cosmos.base.query.v1beta1.PageRequest pagination = 1;
}

QueryTotalSupplyResponse​

QueryTotalSupplyResponse is the response type for the Query/TotalSupply RPC method.

query.proto
Copy
message QueryTotalSupplyResponse {
// supply is the supply of the coins
repeated cosmos.base.v1beta1.Coin supply = 1
[(gogoproto.nullable) = false, (gogoproto.castrepeated) = "github.com/cosmos/cosmos-sdk/types.Coins"];

// pagination defines the pagination in the response.
//
// Since: cosmos-sdk 0.43
cosmos.base.query.v1beta1.PageResponse pagination = 2;
}

QuerySupplyOfRequest​

QuerySupplyOfRequest is the request type for the Query/SupplyOf RPC method.

query.proto
Copy
message QuerySupplyOfRequest {
// denom is the coin denom to query balances for.
string denom = 1;
}

QuerySupplyOfResponse​

QuerySupplyOfResponse is the response type for the Query/SupplyOf RPC method.

query.proto
Copy
message QuerySupplyOfResponse {
// amount is the supply of the coin.
cosmos.base.v1beta1.Coin amount = 1 [(gogoproto.nullable) = false];
}

QueryParamsRequest​

QueryParamsRequest defines the request type for querying x/bank parameters.

query.proto
Copy
message QueryParamsRequest {}

QueryParamsResponse​

QueryParamsResponse defines the response type for querying x/bank parameters.

query.proto
Copy
message QueryParamsResponse {
Params params = 1 [(gogoproto.nullable) = false];
}

QueryDenomMetadataRequest​

QueryDenomMetadataRequest is the request type for the Query/DenomMetadata RPC method.

query.proto
Copy
message QueryDenomMetadataRequest {
// denom is the coin denom to query the metadata for.
string denom = 1;
}

QueryDenomMetadataResponse​

QueryDenomMetadataResponse is the response type for the Query/DenomMetadata RPC method.

query.proto
Copy
message QueryDenomMetadataResponse {
// metadata describes and provides all the client information for the requested token.
Metadata metadata = 1 [(gogoproto.nullable) = false];
}

QueryDenomsMetadataRequest​

QueryDenomsMetadataRequest is the request type for the Query/DenomsMetadata RPC method.

query.proto
Copy
message QueryDenomsMetadataRequest {
// pagination defines an optional pagination for the request.
cosmos.base.query.v1beta1.PageRequest pagination = 1;
}

QueryDenomsMetadataResponse​

QueryDenomsMetadataResponse is the response type for the Query/DenomsMetadata RPC method.

query.proto
Copy
message QueryDenomsMetadataResponse {
// metadata provides the client information for all the registered tokens.
repeated Metadata metadatas = 1 [(gogoproto.nullable) = false];

// pagination defines the pagination in the response.
cosmos.base.query.v1beta1.PageResponse pagination = 2;
}

QueryDenomOwnersRequest​

QueryDenomOwnersRequest defines the request type for the DenomOwners RPC query, which queries for a paginated set of all account holders of a particular denomination.

query.proto
Copy
message QueryDenomOwnersRequest {
// denom defines the coin denomination to query all account holders for.
string denom = 1;

// pagination defines an optional pagination for the request.
cosmos.base.query.v1beta1.PageRequest pagination = 2;
}

QueryDenomOwnersResponse​

QueryDenomOwnersResponse defines the RPC response of a DenomOwners RPC query.

query.proto
Copy
message QueryDenomOwnersResponse {
repeated DenomOwner denom_owners = 1;

// pagination defines the pagination in the response.
cosmos.base.query.v1beta1.PageResponse pagination = 2;
}