App Login

How to Use the Cosmos Staking API

Typical user journeys when interacting with the Cosmos Staking API

📘

Info:

Note that plan_id is an optional field for all request. If it's not specified, the staking API will generate transactions for the default validator address.

How to Stake

Staking on Cosmos mainnet and testnet is initiated through the Post Stake Intent endpoint. The endpoint returns an unsigned transaction that must be signed and broadcasted to the network by the private key corresponding to the public key provided in the stake intent.

Example 1

Here's an example request for staking on Cosmos:

curl --request POST \
     --url https://svc.blockdaemon.com/boss/v1/cosmos/network/stake-intents \
     --header 'X-API-KEY: Your_API_Key' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "amount": "100",
  "delegator_address": "cosmos1wvvhhfm387xvfnqshmdaunnpujjrdxznr5d5x9",
  "plan_id": "plan_Wgx98Rbi8nQuL9ddn3mTk1"
}

This is what a typical response will look like:

{  
 "cosmos": {  
    "amount": "1000000",  
    "delegator_address": "cosmos1xtxlklggls94phsqhzn4fan535rr9snp33cqkp",  
    "unsigned_transaction": "CqEBCp4BCiMvY29zbW9zLnN0YWtpbmcudjFiZXRhMS5Nc2dEZWxlZ2F0ZRJ3Ci1jb3Ntb3MxeHR4bGtsZ2dsczk0cGhzcWh6bjRmYW41MzVycjlzbnAzM2Nxa3ASNGNvc21vc3ZhbG9wZXIxcXdsODc5bng5dDZrZWY0c3VweWF6YXlmN3ZqaGVubnloNTY4eXMaEAoFdWF0b20SBzEwMDAwMDASZQpOCkYKHy9jb3Ntb3MuY3J5cHRvLnNlY3AyNTZrMS5QdWJLZXkSIwohAvO1oyNXjux0ejNGpnSNvG337ci1jm4XcblzV3VBERZVEgQKAggBEhMKDQoFdWF0b20SBDQzMDgQksIKGg50aGV0YS1sb2NhbG5ldCCjwyo=",  
    "validator_address": "cosmosvaloper1qwl879nx9t6kef4supyazayf7vjhennyh568ys"  
  },  
  "customer_id": "ac6ade11fbe77fc80f922a70888bfbb15f3cdb92d41b4dcbfcc31e11649",  
  "network": "testnet",  
  "protocol": "cosmos",  
  "stake_intent_id": "bb17832c-a169-4d4a-80d6-c9ef4f2d0277"  
}

Example 2

The example below shows the scenario when the transaction is the initial one for the current delegator address:

curl --request POST \
     --url https://svc.blockdaemon.com/boss/v1/cosmos/network/stake-intents \
     --header 'X-API-KEY: Your_API_Key' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "public_key": {
    "type": "ed25519",
    "value": "MTIzMDl3c2hka2Fqc2RoYXNramQ4OTEyM25oamtzaGRrcWplZ"
  },
  "amount": "100",
  "delegator_address": "cosmos1wvvhhfm387xvfnqshmdaunnpujjrdxznr5d5x9",
  "plan_id": "plan_Wgx98Rbi8nQuL9ddn3mTk1"
}

It will return the following response:

{  
 "cosmos": {  
    "amount": "1000000",  
    "delegator_address": "cosmos1xtxlklggls94phsqhzn4fan535rr9snp33cqkp",  
    "unsigned_transaction": "CqEBCp4BCiMvY29zbW9zLnN0YWtpbmcudjFiZXRhMS5Nc2dEZWxlZ2F0ZRJ3Ci1jb3Ntb3MxeHR4bGtsZ2dsczk0cGhzcWh6bjRmYW41MzVycjlzbnAzM2Nxa3ASNGNvc21vc3ZhbG9wZXIxcXdsODc5bng5dDZrZWY0c3VweWF6YXlmN3ZqaGVubnloNTY4eXMaEAoFdWF0b20SBzEwMDAwMDASZQpOCkYKHy9jb3Ntb3MuY3J5cHRvLnNlY3AyNTZrMS5QdWJLZXkSIwohAvO1oyNXjux0ejNGpnSNvG337ci1jm4XcblzV3VBERZVEgQKAggBEhMKDQoFdWF0b20SBDQzMDgQksIKGg50aGV0YS1sb2NhbG5ldCCjwyo=",  
    "validator_address": "cosmosvaloper1qwl879nx9t6kef4supyazayf7vjhennyh568ys"  
  },  
  "customer_id": "ac6ade11fbe77fc80f922a70888bfbb15f3cdb92d41b4dcbfcc31e11649",  
  "network": "testnet",  
  "protocol": "cosmos",  
  "stake_intent_id": "bb17832c-a169-4d4a-80d6-c9ef4f2d0277"  
}

❗️

Note:

If it's the first transaction on the chain for the current delegator account, the user should provide the public key or execute any transaction on the chain to initialize it.

How to Deactivate a Stake

Deactivating your stake from the validator is initiated through the Post Deactivation Intent endpoint. The endpoint returns an unsigned transaction that the private key of the delegator must sign.

Here's a request example:

curl --request POST \
     --url https://svc.blockdaemon.com/boss/v1/cosmos/network/deactivation-intents \
     --header 'X-API-KEY: Your_API_Key' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "delegator_address": "cosmos1wvvhhfm387xvfnqshmdaunnpujjrdxznr5d5x9",
  "amount": "100",
  "plan_id": "plan_Wgx98Rbi8nQuL9ddn3mTk1"
}

It will return the following response:

{  
    "cosmos": {  
      "amount": "1000000",  
      "delegator_address": "cosmos1wvvhhfm387xvfnqshmdaunnpujjrdxznr5d5x9",  
      "unsigned_transaction": "CqMBCqABCiUvY29zbW9zLnN0YWtpbmcudjFiZXRhMS5Nc2dVbmRlbGVnYXRlEncKLWNvc21vczF3dnZoaGZtMzg3eHZmbnFzaG1kYXVubnB1ampyZHh6bnI1ZDV4ORI0Y29zbW9zdmFsb3BlcjFxd2w4NzlueDl0NmtlZjRzdXB5YXpheWY3dmpoZW5ueWg1Njh5cxoQCgV1YXRvbRIHMTAwMDAwMBJoClEKRgofL2Nvc21vcy5jcnlwdG8uc2VjcDI1NmsxLlB1YktleRIjCiECkM5TJ9xqYOadsQ7s7hgqcpBCpD3f6Cq4t8Z/uHlyVfsSBAoCCAEYygQSEwoNCgV1YXRvbRIENTU3NBDQzQ0aDnRoZXRhLWxvY2FsbmV0IOTzAQ==",  
      "validator_address": "cosmosvaloper1qwl879nx9t6kef4supyazayf7vjhennyh568ys"  
    },  
    "customer_id": "7af49f794fc757794186288bb6f4b44b091a5765738bafdb7f3c369e06f88",  
    "deactivate_intent_id": "a670b937-616c-4c0f-bfd5-155b884fa8ec",  
    "network": "testnet",  
    "protocol": "cosmos"  
}

How to Withdraw Rewards

Rewards withdrawal is initiated through the Post Rewards Withdrawal intent endpoint. It returns an unsigned transaction, which the delegator needs to sign with their private key and then broadcast to the network.

🚧

Remember!

Rewards should be withdrawn and staked again because Cosmos doesn't support auto-compounding.

Here's an example request:

curl --request POST \
     --url https://svc.blockdaemon.com/boss/v1/cosmos/network/rewards/withdrawal-intents \
     --header 'X-API-KEY: Your_API_Key' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "delegator_address": "cosmos1wvvhhfm387xvfnqshmdaunnpujjrdxznr5d5x9",
  "plan_id": "plan_Wgx98Rbi8nQuL9ddn3mTk1"
}

It will return the following response:

{  
  "cosmos": {  
    "amount": "1000000",  
    "delegator_address": "cosmos18yqqd3d6fhgkd7u7xgtvmsjcmmy950umg40w40",  
    "unsigned_transaction": "CqMBCqABCjcvY29zbW9zLmRpc3RyaWJ1dGlvbi52MWJldGExLk1zZ1dpdGhkcmF3RGVsZWdhdG9yUmV3YXJkEmUKLWNvc21vczE4eXFxZDNkNmZoZ2tkN3U3eGd0dm1zamNtbXk5NTB1bWc0MHc0MBI0Y29zbW9zdmFsb3BlcjFxd2w4NzlueDl0NmtlZjRzdXB5YXpheWY3dmpoZW5ueWg1Njh5cxJnClAKRgofL2Nvc21vcy5jcnlwdG8uc2VjcDI1NmsxLlB1YktleRIjCiEDLid+eYodi56jC7H+bn186ZlOc+HxADlbdCaMZ3k94GgSBAoCCAEYARITCg0KBXVhdG9tEgQzMDc0EKnABxoOdGhldGEtbG9jYWxuZXQgp8Mq",  
    "validator_address": "cosmosvaloper1qwl879nx9t6kef4supyazayf7vjhennyh568ys"  
  },  
  "customer_id": "31eaba6b8ee09a5eaf48519c4fa388d24ac9ef865d4297ee9db0143b5d6c8489",  
  "network": "testnet",  
  "protocol": "cosmos"  
}

Example Code

👋 Need Help?

Contact us through email or our support page for any issues, bugs, or assistance you may need.