Cosmos / Claim Rewards

The Cosmos claim rewards flow allows you to withdraw your staking rewards in a very easy way.

To claim rewards paid in ATOM tokens, you will need:

The delegator_address from which ATOM was delegated, which will sign the transaction.
The validator_addresses from which you want to withdraw the staking rewards.
An optional memo.
An optional gas_limit and gas_price in ATOM.
The pubkey (public key) of the delegator_address.

Follow the steps in this guide for the details on this process.

Flow Diagram

Below is a complete diagram for the Cosmos Claim Rewards flow:

Actions

Create New Claim Rewards Flow
Submit Claim Rewards Data
Submit Signed Claim Rewards Transaction for Broadcast
Get Claim Rewards Flow Status

Create New Claim Rewards Flow

To initiate the rewards claim process, create a new flow with a POST request to /api/v1/flows.

URL

https://cosmos-slate.datahub.figment.io/api/v1/flows

Request

flow : object
- network_code* : string Network this flow operates on (ex. cosmos).
- chain_code* : string Chain this flow operates on (ex. testnet).
- operation* : string The operation to perform (ex. claim_rewards).

Response

id : string ID of the flow.
operation : string The Staking API operation being performed by this flow.
state : string The current state of the flow.
actions : array It includes the name & inputs of all next possible actions.
- create_withdraw_tx : Use this action to transfer ATOM.
  - delegator_address : The address from which ATOM was delegated.
  - validator_addresses : Validator addresses from which staking rewards to be withdrawn.
  - memo : an optional message to record on-chain with your transaction.
  - gas_limit : the total amount of gas you're willing to let this transaction consume.
    - If you do not include this, we'll use a Cosmos library to select a good default for you.
  - gas_price : how many ATOM you're willing to pay per unit of gas consumed by this transaction.
    - If you do not include this, we'll use a Cosmos library to select a good default for you.
  - pubkey : Pubkey value will be retrieved from the chain but if you're using a fresh account (that does not have any outgoing activity) then this information is not available and it requires the user to pass it.
data : object Flow & transaction data.

Request

{
  "flow": {
    "network_code": "cosmos",
    "chain_code": "testnet",
    "operation": "claim_rewards"
  }
}

{
  "flow": {
    "network_code": "cosmos",
    "chain_code": "testnet",
    "operation": "claim_rewards"
  }
}

Example Response
{
  "id": "15a26af4-6c71-4d6a-9dc5-934ebdb095c7",
  "operation": "claim_rewards",
  "state": "initialized",
  "actions": [
    {
      "name": "create_withdraw_tx",
      "inputs": [
        {
          "name": "delegator_address",
          "display": "Delegator Address",
          "description": "",
          "type": "string",
          "validations": [
            {
              "type": "presence",
              "options": {}
            }
          ],
          "array": false,
          "default_value": null
        },
        {
          "name": "validator_addresses",
          "display": "Validator Addresses",
          "description": "",
          "type": "array_of_strings",
          "validations": [
            {
              "type": "array",
              "options": {
                "allow_empty": true,
                "allow_duplicates": false
              }
            }
          ],
          "array": false,
          "default_value": null
        },
        {
          "name": "memo",
          "display": "Memo",
          "description": "",
          "type": "string",
          "validations": [],
          "array": false,
          "default_value": null
        },
        {
          "name": "gas_price",
          "display": "Gas Price",
          "description": "",
          "type": "decimal",
          "validations": [],
          "array": false,
          "default_value": null
        },
        {
          "name": "gas_limit",
          "display": "Gas Limit",
          "description": "",
          "type": "decimal",
          "validations": [],
          "array": false,
          "default_value": null
        },
        {
          "name": "account_number",
          "display": "Account Number",
          "description": "",
          "type": "integer",
          "validations": [],
          "array": false,
          "default_value": null
        },
        {
          "name": "pubkey",
          "display": "Pubkey",
          "description": "",
          "type": "string",
          "validations": [
            {
              "type": "presence",
              "options": {}
            }
          ],
          "array": false,
          "default_value": null
        }
      ]
    }
  ],
  "data": {
    "delegator_address": null,
    "validator_addresses": null,
    "memo": null,
    "gas_price": null,
    "gas_limit": null,
    "pubkey": null,
    "withdraw_transaction": null
  },
  "network_code": "cosmos",
  "chain_code": "testnet",
  "created_at": "2023-02-28T11:39:46.810Z",
  "updated_at": "2023-02-28T11:39:46.810Z"
}

Submit Claim Rewards Data

After creating the new claim rewards flow, we need to submit the claim rewards data.

URL

https://cosmos-slate.datahub.figment.io/api/v1/flows/[:flow_id]/next

After collecting the required inputs as mentioned below, send a PUT request to /api/v1/flows/[:flow_id]/next to proceed to the next step.

Request

name* : create_withdraw_tx
inputs* : object
- delegator_address* : The address from which ATOM was delegated.
- validator_addresses* : Validator addresses from which staking rewards to be withdrawn.
- memo : string A message to record on-chain with your transfer.
- gas_limit : number The total amount of gas you're willing to let this transaction consume.
- gas_price : number How many ATOM you're willing to pay per unit of gas consumed by this transaction.
- pubkey : string Required only if you're using a fresh account (that does not have any outgoing activity) else optional.

Response

id : string ID of the flow.
operation : string The Staking API operation being performed by this flow.
state : string The current state of the flow.
actions : array It includes the name & inputs of all next possible actions.
- refresh_withdraw_tx — If you need to get a fresh version of the transaction payload (i.e., the nonce has increased).
- sign_withdraw_tx : Submit a signed transaction payload or an array of signatures to continue the flow. Refer to the guides Signing Transactions with Figment's npm Package and Signing Transactions with the Fireblocks API for details.
- confirm_withdraw_tx_by_hash : Submit a previously completed transaction hash to continue the flow. Refer to the guide Advance Flows Using a Transaction Hash.
data : object Claim rewards flow & transaction data.

Request

{
  "name": "create_withdraw_tx",
  "inputs": {
    "delegator_address": "cosmos1u85upk2v7pr65g0wv2976zleu6v8qjl9qprvzl",
    "validator_addresses": [
      "cosmosvaloper1tflk30mq5vgqjdly92kkhhq3raev2hnz6eete3"
    ],
    "pubkey": "02db33d72ee215f1a61e5f4ffa098b9325cc1da6f5c3557974ad0f21a5ec9fe235"
  }
}

{
  "name": "create_withdraw_tx",
  "inputs": {
    "delegator_address": "cosmos1u85upk2v7pr65g0wv2976zleu6v8qjl9qprvzl",
    "validator_addresses": [
      "cosmosvaloper1tflk30mq5vgqjdly92kkhhq3raev2hnz6eete3"
    ],
    "pubkey": "02db33d72ee215f1a61e5f4ffa098b9325cc1da6f5c3557974ad0f21a5ec9fe235"
  }
}

Example Response
{
  "id": "15a26af4-6c71-4d6a-9dc5-934ebdb095c7",
  "operation": "claim_rewards",
  "state": "withdraw_tx_signature",
  "actions": [
    {
      "name": "refresh_withdraw_tx",
      "inputs": [
        {
          "name": "delegator_address",
          "display": "Delegator Address",
          "description": "",
          "type": "string",
          "validations": [
            {
              "type": "presence",
              "options": {}
            }
          ],
          "array": false,
          "default_value": "cosmos1u85upk2v7pr65g0wv2976zleu6v8qjl9qprvzl"
        },
        {
          "name": "validator_addresses",
          "display": "Validator Addresses",
          "description": "",
          "type": "array_of_strings",
          "validations": [
            {
              "type": "array",
              "options": {
                "allow_empty": true,
                "allow_duplicates": false
              }
            }
          ],
          "array": false,
          "default_value": [
            "cosmosvaloper1tflk30mq5vgqjdly92kkhhq3raev2hnz6eete3"
          ]
        },
        {
          "name": "memo",
          "display": "Memo",
          "description": "",
          "type": "string",
          "validations": [],
          "array": false,
          "default_value": null
        },
        {
          "name": "gas_price",
          "display": "Gas Price",
          "description": "",
          "type": "decimal",
          "validations": [],
          "array": false,
          "default_value": null
        },
        {
          "name": "gas_limit",
          "display": "Gas Limit",
          "description": "",
          "type": "decimal",
          "validations": [],
          "array": false,
          "default_value": null
        },
        {
          "name": "account_number",
          "display": "Account Number",
          "description": "",
          "type": "integer",
          "validations": [],
          "array": false,
          "default_value": null
        },
        {
          "name": "pubkey",
          "display": "Pubkey",
          "description": "",
          "type": "string",
          "validations": [
            {
              "type": "presence",
              "options": {}
            }
          ],
          "array": false,
          "default_value": "02db33d72ee215f1a61e5f4ffa098b9325cc1da6f5c3557974ad0f21a5ec9fe235"
        }
      ]
    },
    {
      "name": "sign_withdraw_tx",
      "inputs": [
        {
          "name": "transaction_payload",
          "display": "Transaction Payload",
          "description": "",
          "type": "signed_transaction",
          "validations": [
            {
              "type": "sign_payload",
              "options": {}
            }
          ],
          "array": false,
          "default_value": null,
          "signers": [
            "cosmos1u85upk2v7pr65g0wv2976zleu6v8qjl9qprvzl"
          ],
          "transaction_payload": "7b226d65737361676573223a5b7b227479706555726c223a222f636f736d6f732e646973747269627574696f6e2e763162657461312e4d7367576974686472617744656c656761746f72526577617264222c2276616c7565223a7b2264656c656761746f7241646472657373223a22636f736d6f733175383575706b3276377072363567307776323937367a6c6575367638716a6c39717072767a6c222c2276616c696461746f7241646472657373223a22636f736d6f7376616c6f7065723174666c6b33306d71357667716a646c7939326b6b686871337261657632686e7a366565746533227d7d5d2c22666565223a7b22616d6f756e74223a5b7b22616d6f756e74223a2233353931222c2264656e6f6d223a227561746f6d227d5d2c22676173223a22313433363331227d2c226d656d6f223a22227d"
        },
        {
          "name": "signatures",
          "display": "Signatures",
          "description": "",
          "type": "array_of_signatures",
          "validations": [],
          "array": true,
          "default_value": null,
          "element_type": "signature_data",
          "signers": [
            "cosmos1u85upk2v7pr65g0wv2976zleu6v8qjl9qprvzl"
          ],
          "transaction_payload": "7b226d65737361676573223a5b7b227479706555726c223a222f636f736d6f732e646973747269627574696f6e2e763162657461312e4d7367576974686472617744656c656761746f72526577617264222c2276616c7565223a7b2264656c656761746f7241646472657373223a22636f736d6f733175383575706b3276377072363567307776323937367a6c6575367638716a6c39717072767a6c222c2276616c696461746f7241646472657373223a22636f736d6f7376616c6f7065723174666c6b33306d71357667716a646c7939326b6b686871337261657632686e7a366565746533227d7d5d2c22666565223a7b22616d6f756e74223a5b7b22616d6f756e74223a2233353931222c2264656e6f6d223a227561746f6d227d5d2c22676173223a22313433363331227d2c226d656d6f223a22227d",
          "signing_payload": "c67009f9018391e00842e4b793a2bb5e02b0f27713010960071a28356b30b0d7",
          "inputs": [
            {
              "name": "account_address",
              "display": "Account Address",
              "description": "",
              "type": "string",
              "validations": [
                {
                  "type": "presence",
                  "options": {}
                }
              ],
              "array": false,
              "default_value": null
            },
            {
              "name": "signature",
              "display": "Signature",
              "description": "",
              "type": "string",
              "validations": [
                {
                  "type": "presence",
                  "options": {}
                }
              ],
              "array": false,
              "default_value": null
            }
          ]
        }
      ]
    },
    {
      "name": "confirm_withdraw_tx_by_hash",
      "inputs": [
        {
          "name": "hash",
          "display": "Hash",
          "description": "",
          "type": "string",
          "validations": [
            {
              "type": "presence",
              "options": {}
            }
          ],
          "array": false,
          "default_value": null
        },
        {
          "name": "block_number",
          "display": "Block Number",
          "description": "",
          "type": "integer",
          "validations": [],
          "array": false,
          "default_value": null
        }
      ]
    }
  ],
  "data": {
    "delegator_address": "cosmos1u85upk2v7pr65g0wv2976zleu6v8qjl9qprvzl",
    "validator_addresses": [
      "cosmosvaloper1tflk30mq5vgqjdly92kkhhq3raev2hnz6eete3"
    ],
    "memo": "",
    "gas_price": null,
    "gas_limit": null,
    "pubkey": "02db33d72ee215f1a61e5f4ffa098b9325cc1da6f5c3557974ad0f21a5ec9fe235",
    "withdraw_transaction": {
      "raw": "7b226d65737361676573223a5b7b227479706555726c223a222f636f736d6f732e646973747269627574696f6e2e763162657461312e4d7367576974686472617744656c656761746f72526577617264222c2276616c7565223a7b2264656c656761746f7241646472657373223a22636f736d6f733175383575706b3276377072363567307776323937367a6c6575367638716a6c39717072767a6c222c2276616c696461746f7241646472657373223a22636f736d6f7376616c6f7065723174666c6b33306d71357667716a646c7939326b6b686871337261657632686e7a366565746533227d7d5d2c22666565223a7b22616d6f756e74223a5b7b22616d6f756e74223a2233353931222c2264656e6f6d223a227561746f6d227d5d2c22676173223a22313433363331227d2c226d656d6f223a22227d",
      "signing_payload": "c67009f9018391e00842e4b793a2bb5e02b0f27713010960071a28356b30b0d7",
      "signed": null,
      "hash": null,
      "status": null,
      "error": null,
      "signatures": null,
      "block_time": null
    }
  },
  "network_code": "cosmos",
  "chain_code": "testnet",
  "created_at": "2023-02-28T11:39:46.810Z",
  "updated_at": "2023-02-28T11:41:23.208Z"
}

Submit Signed Claim Rewards Transaction for Broadcast

Before broadcasting the transaction, you must sign the transaction_payload you received in the previous step. After signing the transaction, send a PUT request to /api/v1/flows/[:flow_id]/next and the Staking API will broadcast the transaction to the network.

URL

https://cosmos-slate.datahub.figment.io/api/v1/flows/[:flow_id]/next

Request

name* : sign_withdraw_tx
inputs* : object
- transaction_payload* : Signed transaction payload from the previous step's response.
- signatures : array of object The signatures array can be used instead of sending a transaction payload when the signing keys are kept in a custodial solution, such as Fireblocks. Refer to the guide Signing Transactions with the Fireblocks API for details.

Response

id : string ID of the flow.
operation : string The Staking API operation being performed by this flow.
state : string The current state of the flow.
- withdraw_tx_broadcasting : Transaction has been broadcast and is waiting for confirmation.
- completed : Transaction has been confirmed and rewards claimed successfully.
actions : array It includes the name & inputs of all next possible actions.
data : object Flow & transaction data.

Request

{
  "name": "sign_withdraw_tx",
  "inputs": {
    "transaction_payload": "0aa3010aa0010a372f636f736d6f732e646973747269627574696f6e2e763162657461312e4d7367576974686472617744656c656761746f7252657761726412650a2d636f736d6f733175383575706b3276377072363567307776323937367a6c6575367638716a6c39717072767a6c1234636f736d6f7376616c6f7065723174666c6b33306d71357667716a646c7939326b6b686871337261657632686e7a36656574653312670a500a460a1f2f636f736d6f732e63727970746f2e736563703235366b312e5075624b657912230a2102db33d72ee215f1a61e5f4ffa098b9325cc1da6f5c3557974ad0f21a5ec9fe23512040a020801180912130a0d0a057561746f6d120433353931108fe2081a400f39e63b287138ece0e3d78f4bf8bfeb95b354191abc3545c61f78d1009083880648187192980f87aadfb94bb82f97ff9a5ba6b3d99fc38eb1adbdec2e12e3e4"
  }
}

{
  "name": "sign_withdraw_tx",
  "inputs": {
    "transaction_payload": "0aa3010aa0010a372f636f736d6f732e646973747269627574696f6e2e763162657461312e4d7367576974686472617744656c656761746f7252657761726412650a2d636f736d6f733175383575706b3276377072363567307776323937367a6c6575367638716a6c39717072767a6c1234636f736d6f7376616c6f7065723174666c6b33306d71357667716a646c7939326b6b686871337261657632686e7a36656574653312670a500a460a1f2f636f736d6f732e63727970746f2e736563703235366b312e5075624b657912230a2102db33d72ee215f1a61e5f4ffa098b9325cc1da6f5c3557974ad0f21a5ec9fe23512040a020801180912130a0d0a057561746f6d120433353931108fe2081a400f39e63b287138ece0e3d78f4bf8bfeb95b354191abc3545c61f78d1009083880648187192980f87aadfb94bb82f97ff9a5ba6b3d99fc38eb1adbdec2e12e3e4"
  }
}

Example Response
{
  "id": "15a26af4-6c71-4d6a-9dc5-934ebdb095c7",
  "operation": "claim_rewards",
  "state": "withdraw_tx_broadcasting",
  "actions": [
    {
      "name": "wait",
      "estimated_state_change_at": "2023-02-28T11:43:16.888Z",
      "inputs": []
    }
  ],
  "data": {
    "delegator_address": "cosmos1u85upk2v7pr65g0wv2976zleu6v8qjl9qprvzl",
    "validator_addresses": [
      "cosmosvaloper1tflk30mq5vgqjdly92kkhhq3raev2hnz6eete3"
    ],
    "memo": "",
    "gas_price": null,
    "gas_limit": null,
    "pubkey": "02db33d72ee215f1a61e5f4ffa098b9325cc1da6f5c3557974ad0f21a5ec9fe235",
    "withdraw_transaction": {
      "raw": "7b226d65737361676573223a5b7b227479706555726c223a222f636f736d6f732e646973747269627574696f6e2e763162657461312e4d7367576974686472617744656c656761746f72526577617264222c2276616c7565223a7b2264656c656761746f7241646472657373223a22636f736d6f733175383575706b3276377072363567307776323937367a6c6575367638716a6c39717072767a6c222c2276616c696461746f7241646472657373223a22636f736d6f7376616c6f7065723174666c6b33306d71357667716a646c7939326b6b686871337261657632686e7a366565746533227d7d5d2c22666565223a7b22616d6f756e74223a5b7b22616d6f756e74223a2233353931222c2264656e6f6d223a227561746f6d227d5d2c22676173223a22313433363331227d2c226d656d6f223a22227d",
      "signing_payload": "c67009f9018391e00842e4b793a2bb5e02b0f27713010960071a28356b30b0d7",
      "signed": "0aa3010aa0010a372f636f736d6f732e646973747269627574696f6e2e763162657461312e4d7367576974686472617744656c656761746f7252657761726412650a2d636f736d6f733175383575706b3276377072363567307776323937367a6c6575367638716a6c39717072767a6c1234636f736d6f7376616c6f7065723174666c6b33306d71357667716a646c7939326b6b686871337261657632686e7a36656574653312670a500a460a1f2f636f736d6f732e63727970746f2e736563703235366b312e5075624b657912230a2102db33d72ee215f1a61e5f4ffa098b9325cc1da6f5c3557974ad0f21a5ec9fe23512040a020801180912130a0d0a057561746f6d120433353931108fe2081a400f39e63b287138ece0e3d78f4bf8bfeb95b354191abc3545c61f78d1009083880648187192980f87aadfb94bb82f97ff9a5ba6b3d99fc38eb1adbdec2e12e3e4",
      "hash": "62FBD6133C846A747E58983757545E301CF69D5916A65DC7C9CA755B455B605C",
      "status": null,
      "error": null,
      "signatures": [
        {
          "account_address": "cosmos1u85upk2v7pr65g0wv2976zleu6v8qjl9qprvzl",
          "signature": ""
        }
      ],
      "block_time": null
    }
  },
  "network_code": "cosmos",
  "chain_code": "testnet",
  "created_at": "2023-02-28T11:39:46.810Z",
  "updated_at": "2023-02-28T11:42:16.132Z"
}

Get Claim Rewards Flow Status

To get the current state of the existing flow, send a GET request to /api/v1/flows/[:flow_id] using the flow ID from the previous step.

URL

https://cosmos-slate.datahub.figment.io/api/v1/flows/[:flow_id]

Request

None

Response

id : string ID of the flow.
operation : string The Staking API operation being performed by this flow.
state : string The current state of the flow.
- withdraw_tx_broadcasting : Transaction has been broadcast and is waiting for confirmation.
- completed : Transaction has been confirmed and the delegation is complete.
actions : array It includes the name & inputs of all next possible actions.
data : object Flow & transaction data.

Request

api/v1/flows/{{cosmosStakingFlowId}}

api/v1/flows/{{cosmosStakingFlowId}}

Example Response
{
  "id": "1d823c7f-be8a-430e-85cf-7269206cd867",
  "operation": "staking",
  "state": "completed",
  "actions": [],
  "data": {
    "delegator_address": "cosmos1u85upk2v7pr65g0wv2976zleu6v8qjl9qprvzl",
    "validator_address": "cosmosvaloper1tflk30mq5vgqjdly92kkhhq3raev2hnz6eete3",
    "amount": "2.0",
    "memo": "",
    "gas_price": null,
    "gas_limit": null,
    "delegate_transaction": {
      "raw": "7b226d65737361676573223a5b7b227479706555726c223a222f636f736d6f732e7374616b696e672e763162657461312e4d736744656c6567617465222c2276616c7565223a7b2264656c656761746f7241646472657373223a22636f736d6f733175383575706b3276377072363567307776323937367a6c6575367638716a6c39717072767a6c222c2276616c696461746f7241646472657373223a22636f736d6f7376616c6f7065723174666c6b33306d71357667716a646c7939326b6b686871337261657632686e7a366565746533222c22616d6f756e74223a7b2264656e6f6d223a227561746f6d222c22616d6f756e74223a2232303030303030227d7d7d5d2c22666565223a7b22616d6f756e74223a5b7b22616d6f756e74223a2235313037222c2264656e6f6d223a227561746f6d227d5d2c22676173223a22323034323434227d2c226d656d6f223a22227d",
      "signing_payload": "31a9a1e09389b219435eaf2b0dcbab6a1d6950d95545564be627f86c7dfed956",
      "signed": "0aa1010a9e010a232f636f736d6f732e7374616b696e672e763162657461312e4d736744656c656761746512770a2d636f736d6f733175383575706b3276377072363567307776323937367a6c6575367638716a6c39717072767a6c1234636f736d6f7376616c6f7065723174666c6b33306d71357667716a646c7939326b6b686871337261657632686e7a3665657465331a100a057561746f6d12073230303030303012670a500a460a1f2f636f736d6f732e63727970746f2e736563703235366b312e5075624b657912230a2102db33d72ee215f1a61e5f4ffa098b9325cc1da6f5c3557974ad0f21a5ec9fe23512040a020801180612130a0d0a057561746f6d12043531303710d4bb0c1a4024d0155b8cf9f5fcacb15859b51fc1d895979fce08043362edacd7763e9b85a84c7e98b7390d3279e6b8d6629f60d67a1e6ae751a3ab9158a5350188aafd1166",
      "hash": "09F1F2740CA9265E066299DBCB46DB6AF1A1DAB9CF0764499CFD5D421BB045BA",
      "status": "confirmed",
      "error": null,
      "signatures": [
        {
          "account_address": "cosmos1u85upk2v7pr65g0wv2976zleu6v8qjl9qprvzl",
          "signature": ""
        }
      ],
      "block_time": "2023-02-28T10:51:19.797Z"
    },
    "pubkey": "02db33d72ee215f1a61e5f4ffa098b9325cc1da6f5c3557974ad0f21a5ec9fe235"
  },
  "network_code": "cosmos",
  "chain_code": "testnet",
  "created_at": "2023-02-28T10:45:13.156Z",
  "updated_at": "2023-02-28T10:51:34.001Z"
}

Flow Diagram​

Actions​

Create New Claim Rewards Flow

URL

Request

Response

Submit Claim Rewards Data

URL

Request

Response

Submit Signed Claim Rewards Transaction for Broadcast

URL

Request

Response

Get Claim Rewards Flow Status

URL

Request

Response

Flow Diagram

Actions