Skip to main content
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
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
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
message MsgSendResponse {}

​
MsgMultiSend

MsgMultiSend represents an arbitrary multi-in, multi-out send message.
tx.proto
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
message MsgMultiSendResponse {}

​
Queries

Query defines the gRPC querier service.
query.proto
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
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
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
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
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
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
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
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
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
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
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
message QueryParamsRequest {}

​
QueryParamsResponse

QueryParamsResponse defines the response type for querying x/bank parameters.
query.proto
message QueryParamsResponse {
  Params params = 1 [(gogoproto.nullable) = false];
}

​
QueryDenomMetadataRequest

QueryDenomMetadataRequest is the request type for the Query/DenomMetadata RPC method.
query.proto
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
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
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
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
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
message QueryDenomOwnersResponse {
  repeated DenomOwner denom_owners = 1;

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