# REST Endpoints Migration

Migrate your REST endpoints to the Stargate ones.

# Deprecation of Legacy REST Endpoints

The Cosmos SDK versions v0.39 and earlier provided REST endpoints to query the state and broadcast transactions. These endpoints are kept in Cosmos SDK v0.40 (Stargate), but they are marked as deprecated, and will be removed in v0.41. We therefore call these endpoints legacy REST endpoints.

Some important information concerning all legacy REST endpoints:

  • Most of these endpoints are backwards-comptatible. All breaking changes are described in the next section.
  • In particular, these endpoints still output Amino JSON. Cosmos v0.40 introduced Protobuf as the default encoding library throughout the codebase, but legacy REST endpoints are one of the few places where the encoding is hardcoded to Amino. For more information about Protobuf and Amino, please read our encoding guide.
  • All legacy REST endpoints include a HTTP deprecation header (opens new window) which links to this document.

# Breaking Changes in Legacy REST Endpoints

Legacy REST Endpoint Description Breaking Change
POST /txs Broadcast tx Endpoint will error when trying to broadcast transactions that don't support Amino serialization (e.g. IBC txs)1.
POST /txs/encode, POST /txs/decode Encode/decode Amino txs from JSON to binary Endpoint will error when trying to encode/decode transactions that don't support Amino serialization (e.g. IBC txs)1.
GET /txs/{hash} Query tx by hash Endpoint will error when trying to output transactions that don't support Amino serialization (e.g. IBC txs)1.
GET /txs Query tx by events Endpoint will error when trying to output transactions that don't support Amino serialization (e.g. IBC txs)1.
GET /gov/proposals/{id}/votes, GET /gov/proposals/{id}/votes/{voter} Gov endpoints for querying votes All gov endpoints which return votes return int32 in the option field instead of string: 1=VOTE_OPTION_YES, 2=VOTE_OPTION_ABSTAIN, 3=VOTE_OPTION_NO, 4=VOTE_OPTION_NO_WITH_VETO.
GET /staking/* Staking query endpoints All staking endpoints which return validators have two breaking changes. First, the validator's consensus_pubkey field returns an Amino-encoded struct representing an Any instead of a Bech32-encoded string representing the pubkey. The value field of the Any is the pubkey's raw key as base64-encoded bytes. Second, the validator's status field now returns an int32 instead of string: 1=BOND_STATUS_UNBONDED, 2=BOND_STATUS_UNBONDING, 3=BOND_STATUS_BONDED.
GET /staking/validators Get all validators BondStatus is now a protobuf enum instead of an int32, and JSON serialized using its protobuf name, so expect query parameters like ?status=BOND_STATUS_{BONDED,UNBONDED,UNBONDING} as opposed to ?status={bonded,unbonded,unbonding}.

1: Transactions that don't support Amino serialization are the ones that contain one or more Msgs that are not registered with the Amino codec. Currently in the SDK, only IBC Msgs fall into this case.

# Migrating to New REST Endpoints

Thanks to the Protocol Buffers migration in v0.40, we are able to take advantage of a vast number of gRPC tools and solutions. For most of the legacy REST endpoints, Cosmos SDK v0.40 provides new REST endpoints generated from gRPC Query services using grpc-gateway (opens new window). We usually call them gRPC-gateway REST endpoints.

Some modules expose legacy POST endpoints to generate unsigned transactions for their Msgs. These POST endpoints have been removed. We recommend to use service Msgs directly, and use Protobuf to do client-side transaction generation. A guide can be found here.

Legacy REST Endpoint Description New gRPC-gateway REST Endpoint
GET /txs/{hash} Query tx by hash GET /cosmos/tx/v1beta1/txs/{hash}
GET /txs Query tx by events GET /cosmos/tx/v1beta1/txs
POST /txs Broadcast tx POST /cosmos/tx/v1beta1/txs
POST /txs/encode Encodes an Amino JSON tx to an Amino binary tx N/A, use Protobuf directly
POST /txs/decode Decodes an Amino binary tx into an Amino JSON tx N/A, use Protobuf directly
POST /bank/* Create unsigned Msgs for bank tx N/A, use Protobuf directly
GET /bank/balances/{address} Get the balance of an address GET /cosmos/bank/v1beta1/balances/{address}
GET /bank/total Get the total supply of all coins GET /cosmos/bank/v1beta1/supply
GET /bank/total/{denom} Get the total supply of one coin GET /cosmos/bank/v1beta1/supply/{denom}
POST /distribution/delegators/{delegatorAddr}/rewards Withdraw all delegator rewards N/A, use Protobuf directly
POST /distribution/* Create unsigned Msgs for distribution N/A, use Protobuf directly
GET /distribution/delegators/{delegatorAddr}/rewards Get the total rewards balance from all delegations GET /cosmos/distribution/v1beta1/v1beta1/delegators/{delegator_address}/rewards
GET /distribution/delegators/{delegatorAddr}/rewards/{validatorAddr} Query a delegation reward GET /cosmos/distribution/v1beta1/delegators/{delegatorAddr}/rewards/{validatorAddr}
GET /distribution/delegators/{delegatorAddr}/withdraw_address Get the rewards withdrawal address GET /cosmos/distribution/v1beta1/delegators/{delegatorAddr}/withdraw_address
GET /distribution/validators/{validatorAddr} Validator distribution information N/A
GET /distribution/validators/{validatorAddr}/rewards Commission and outstanding rewards of a single a validator GET /cosmos/distribution/v1beta1/validators/{validatorAddr}/commission
GET /cosmos/distribution/v1beta1/validators/{validatorAddr}/outstanding_rewards
GET /distribution/validators/{validatorAddr}/outstanding_rewards Outstanding rewards of a single validator GET /cosmos/distribution/v1beta1/validators/{validatorAddr}/outstanding_rewards
GET /distribution/parameters Get the current distribution parameter values GET /cosmos/distribution/v1beta1/params
GET /distribution/community_pool Get the amount held in the community pool GET /cosmos/distribution/v1beta1/community_pool
GET /evidence/{evidence-hash} Get evidence by hash GET /cosmos/evidence/v1beta1/evidence/{evidence_hash}
GET /evidence Get all evidence GET /cosmos/evidence/v1beta1/evidence
POST /gov/* Create unsigned Msgs for gov N/A, use Protobuf directly
GET /gov/parameters/{type} Get government parameters GET /cosmos/gov/v1beta1/params/{type}
GET /gov/proposals Get all proposals GET /cosmos/gov/v1beta1/proposals
GET /gov/proposals/{proposal-id} Get proposal by id GET /cosmos/gov/v1beta1/proposals/{proposal-id}
GET /gov/proposals/{proposal-id}/proposer Get proposer of a proposal GET /cosmos/gov/v1beta1/proposals/{proposal-id} (Get proposer from Proposal struct)
GET /gov/proposals/{proposal-id}/deposits Get deposits of a proposal GET /cosmos/gov/v1beta1/proposals/{proposal-id}/deposits
GET /gov/proposals/{proposal-id}/deposits/{depositor} Get depositor a of deposit GET /cosmos/gov/v1beta1/proposals/{proposal-id}/deposits/{depositor}
GET /gov/proposals/{proposal-id}/tally Get tally of a proposal GET /cosmos/gov/v1beta1/proposals/{proposal-id}/tally
GET /gov/proposals/{proposal-id}/votes Get votes of a proposal GET /cosmos/gov/v1beta1/proposals/{proposal-id}/votes
GET /gov/proposals/{proposal-id}/votes/{vote} Get a particular vote GET /cosmos/gov/v1beta1/proposals/{proposal-id}/votes/{vote}
GET /minting/parameters Get parameters for minting GET /cosmos/minting/v1beta1/params
GET /minting/inflation Get minting inflation GET /cosmos/minting/v1beta1/inflation
GET /minting/annual-provisions Get minting annual provisions GET /cosmos/minting/v1beta1/annual_provisions
POST /slashing/* Create unsigned Msgs for slashing N/A, use Protobuf directly
GET /slashing/validators/{validatorPubKey}/signing_info Get validator signing info GET /cosmos/slashing/v1beta1/signing_infos/{cons_address} (Use consensus address instead of pubkey)
GET /slashing/signing_infos Get all signing infos GET /cosmos/slashing/v1beta1/signing_infos
GET /slashing/parameters Get slashing parameters GET /cosmos/slashing/v1beta1/params
POST /staking/* Create unsigned Msgs for staking N/A, use Protobuf directly
GET /staking/delegators/{delegatorAddr}/delegations Get all delegations from a delegator GET /cosmos/staking/v1beta1/delegations/{delegatorAddr}
GET /staking/delegators/{delegatorAddr}/unbonding_delegations Get all unbonding delegations from a delegator GET /cosmos/staking/v1beta1/delegators/{delegatorAddr}/unbonding_delegations
GET /staking/delegators/{delegatorAddr}/txs Get all staking txs (i.e msgs) from a delegator Removed
GET /staking/delegators/{delegatorAddr}/validators Query all validators that a delegator is bonded to GET /cosmos/staking/v1beta1/delegators/{delegatorAddr}/validators
GET /staking/delegators/{delegatorAddr}/validators/{validatorAddr} Query a validator that a delegator is bonded to GET /cosmos/staking/v1beta1/delegators/{delegatorAddr}/validators/{validatorAddr}
GET /staking/delegators/{delegatorAddr}/delegations/{validatorAddr} Query a delegation between a delegator and a validator GET /cosmos/staking/v1beta1/validators/{validatorAddr}/delegations/{delegatorAddr}
GET /staking/delegators/{delegatorAddr}/unbonding_delegations/{validatorAddr} Query all unbonding delegations between a delegator and a validator GET /cosmos/staking/v1beta1/delegators/{delegatorAddr}/unbonding_delegations/{validatorAddr}
GET /staking/redelegations Query redelegations GET /cosmos/staking/v1beta1/v1beta1/delegators/{delegator_addr}/redelegations
GET /staking/validators Get all validators GET /cosmos/staking/v1beta1/validators
GET /staking/validators/{validatorAddr} Get a single validator info GET /cosmos/staking/v1beta1/validators/{validatorAddr}
GET /staking/validators/{validatorAddr}/delegations Get all delegations to a validator GET /cosmos/staking/v1beta1/validators/{validatorAddr}/delegations
GET /staking/validators/{validatorAddr}/unbonding_delegations Get all unbonding delegations from a validator GET /cosmos/staking/v1beta1/validators/{validatorAddr}/unbonding_delegations
GET /staking/historical_info/{height} Get HistoricalInfo at a given height GET /cosmos/staking/v1beta1/historical_info/{height}
GET /staking/pool Get the current state of the staking pool GET /cosmos/staking/v1beta1/pool
GET /staking/parameters Get the current staking parameter values GET /cosmos/staking/v1beta1/params
POST /upgrade/* Create unsigned Msgs for upgrade N/A, use Protobuf directly
GET /upgrade/current Get the current plan GET /cosmos/upgrade/v1beta1/current_plan
GET /upgrade/applied_plan/{name} Get a previously applied plan GET /cosmos/upgrade/v1beta1/applied/{name}

# Migrating to gRPC

Instead of hitting REST endpoints as described in the previous paragraph, the SDK also exposes a gRPC server. Any client can use gRPC instead of REST to interact with the node. An overview of different ways to communicate with a node can be found here, and a concrete tutorial for setting up a gRPC client here.