Search
# REST Endpoints Migration
Migrate to gRPC-Gateway REST endpoints. Legacy REST endpoints were marked as deprecated in v0.40 and will be removed in v0.45.
Two Legacy REST endpoints (POST /txs and POST /txs/encode) were removed ahead of schedule in v0.44 due to a security vulnerability.
# Deprecation of Legacy REST Endpoints
Cosmos SDK versions v0.39 and earlier registered REST endpoints using a package called gorilla/mux. These REST endpoints were marked as deprecated in v0.40 and have since been referred to as legacy REST endpoints. Legacy REST endpoints will be officially removed in v0.45.
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. Most of the legacy REST endpoints have been replaced by REST endpoints generated from gRPC Query services using grpc-gateway (opens new window). We usually call them gRPC-gateway REST endpoints.
Previously, some modules exposed legacy POST endpoints to generate unsigned transactions for their Msgs. These POST endpoints were removed in v0.40. We recommend using Protobuf Msg service directly 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 above, the Cosmos 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 can be found here.