Skip to main content

Cosmos / Unstaking

The Cosmos Unstaking flow allows you to unstake your ATOM tokens from the validator. With the Staking API, you can unstake your ATOM tokens within a few steps.

To unstake ATOM tokens, you will need:

  • The delegator_address from which ATOM was delegated, which will sign the transaction.
  • The validator_address from which ATOM is being undelegated.
  • The amount of ATOM to be undelegated.
  • 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 section for the details on this process.

Flow Diagram

Below is a complete diagram for the Cosmos Unstaking flow:

Cosmos Unstaking Flow Diagram

Actions


Create New Unstaking Flow

To initiate the unstaking process with Staking API, create a new flow with POST /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. unstaking).

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_undelegate_tx : Use this action to generate an undelegation transaction to unstake your ATOM.
      • delegator_address : The address from which ATOM was delegated.
      • validator_address : The validator address from which ATOM will be undelegated.
      • amount : The amount of ATOM to be undelegated.
      • 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
Example Response
{
"id": "f624c185-afb0-46d5-aa63-4d7649a2690a",
"operation": "unstaking",
"state": "initialized",
"actions": [
{
"name": "create_undelegate_tx",
"inputs": [
{
"name": "delegator_address",
"display": "Delegator Address",
"description": "",
"type": "string",
"validations": [
{
"type": "presence",
"options": {}
}
],
"array": false,
"default_value": null
},
{
"name": "validator_address",
"display": "Validator Address",
"description": "",
"type": "string",
"validations": [
{
"type": "presence",
"options": {}
},
{
"type": "presence",
"options": {}
},
{
"type": "format",
"options": {
"with": "(?-mix:\\Acosmosvaloper.*)",
"message": "should start with `cosmosvaloper`"
}
}
],
"array": false,
"default_value": null
},
{
"name": "amount",
"display": "Amount",
"description": "",
"type": "decimal",
"validations": [],
"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": "pubkey",
"display": "Pubkey",
"description": "Value will be retrieved from the chain if available",
"type": "string",
"validations": [
{
"type": "presence",
"options": {}
}
],
"array": false,
"default_value": null
}
]
}
],
"data": {
"delegator_address": null,
"validator_address": null,
"amount": null,
"memo": null,
"gas_price": null,
"gas_limit": null,
"undelegate_transaction": null,
"estimated_unbonded_at": null,
"pubkey": null
},
"network_code": "cosmos",
"chain_code": "testnet",
"created_at": "2023-02-28T11:02:24.657Z",
"updated_at": "2023-02-28T11:02:24.657Z"
}


Submit Undelegate Data

After creating the new undelegation flow, we need to submit the undelegate 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_undelegate_tx.
  • inputs* : object
    • delegator_address* : string The address from which ATOM was delegated.
    • validator_address* : string The validator address from which ATOM will be undelegated.
    • amount* : number The amount of ATOM to be undelegated.
    • 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.
  • data : object Flow & transaction data.
Request
Example Response
{
"id": "f624c185-afb0-46d5-aa63-4d7649a2690a",
"operation": "unstaking",
"state": "undelegate_tx_signature",
"actions": [
{
"name": "refresh_undelegate_tx",
"inputs": [
{
"name": "delegator_address",
"display": "Delegator Address",
"description": "",
"type": "string",
"validations": [
{
"type": "presence",
"options": {}
}
],
"array": false,
"default_value": "cosmos1u85upk2v7pr65g0wv2976zleu6v8qjl9qprvzl"
},
{
"name": "validator_address",
"display": "Validator Address",
"description": "",
"type": "string",
"validations": [
{
"type": "presence",
"options": {}
},
{
"type": "presence",
"options": {}
},
{
"type": "format",
"options": {
"with": "(?-mix:\\Acosmosvaloper.*)",
"message": "should start with `cosmosvaloper`"
}
}
],
"array": false,
"default_value": "cosmosvaloper1tflk30mq5vgqjdly92kkhhq3raev2hnz6eete3"
},
{
"name": "amount",
"display": "Amount",
"description": "",
"type": "decimal",
"validations": [],
"array": false,
"default_value": "1.0"
},
{
"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": "pubkey",
"display": "Pubkey",
"description": "Value will be retrieved from the chain if available",
"type": "string",
"validations": [
{
"type": "presence",
"options": {}
}
],
"array": false,
"default_value": "02db33d72ee215f1a61e5f4ffa098b9325cc1da6f5c3557974ad0f21a5ec9fe235"
}
]
},
{
"name": "sign_undelegate_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": "7b226d65737361676573223a5b7b227479706555726c223a222f636f736d6f732e7374616b696e672e763162657461312e4d7367556e64656c6567617465222c2276616c7565223a7b2264656c656761746f7241646472657373223a22636f736d6f733175383575706b3276377072363567307776323937367a6c6575367638716a6c39717072767a6c222c2276616c696461746f7241646472657373223a22636f736d6f7376616c6f7065723174666c6b33306d71357667716a646c7939326b6b686871337261657632686e7a366565746533222c22616d6f756e74223a7b2264656e6f6d223a227561746f6d222c22616d6f756e74223a2231303030303030227d7d7d5d2c22666565223a7b22616d6f756e74223a5b7b22616d6f756e74223a2236323937222c2264656e6f6d223a227561746f6d227d5d2c22676173223a22323531383435227d2c226d656d6f223a22227d"
},
{
"name": "signatures",
"display": "Signatures",
"description": "",
"type": "array_of_signatures",
"validations": [],
"array": true,
"default_value": null,
"element_type": "signature_data",
"signers": [
"cosmos1u85upk2v7pr65g0wv2976zleu6v8qjl9qprvzl"
],
"transaction_payload": "7b226d65737361676573223a5b7b227479706555726c223a222f636f736d6f732e7374616b696e672e763162657461312e4d7367556e64656c6567617465222c2276616c7565223a7b2264656c656761746f7241646472657373223a22636f736d6f733175383575706b3276377072363567307776323937367a6c6575367638716a6c39717072767a6c222c2276616c696461746f7241646472657373223a22636f736d6f7376616c6f7065723174666c6b33306d71357667716a646c7939326b6b686871337261657632686e7a366565746533222c22616d6f756e74223a7b2264656e6f6d223a227561746f6d222c22616d6f756e74223a2231303030303030227d7d7d5d2c22666565223a7b22616d6f756e74223a5b7b22616d6f756e74223a2236323937222c2264656e6f6d223a227561746f6d227d5d2c22676173223a22323531383435227d2c226d656d6f223a22227d",
"signing_payload": "53ff624a7b8fb60956f3d88d249ff95e14202fe7185262802141cb3496a2e208",
"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_undelegate_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_address": "cosmosvaloper1tflk30mq5vgqjdly92kkhhq3raev2hnz6eete3",
"amount": "1.0",
"memo": "",
"gas_price": null,
"gas_limit": null,
"undelegate_transaction": {
"raw": "7b226d65737361676573223a5b7b227479706555726c223a222f636f736d6f732e7374616b696e672e763162657461312e4d7367556e64656c6567617465222c2276616c7565223a7b2264656c656761746f7241646472657373223a22636f736d6f733175383575706b3276377072363567307776323937367a6c6575367638716a6c39717072767a6c222c2276616c696461746f7241646472657373223a22636f736d6f7376616c6f7065723174666c6b33306d71357667716a646c7939326b6b686871337261657632686e7a366565746533222c22616d6f756e74223a7b2264656e6f6d223a227561746f6d222c22616d6f756e74223a2231303030303030227d7d7d5d2c22666565223a7b22616d6f756e74223a5b7b22616d6f756e74223a2236323937222c2264656e6f6d223a227561746f6d227d5d2c22676173223a22323531383435227d2c226d656d6f223a22227d",
"signing_payload": "53ff624a7b8fb60956f3d88d249ff95e14202fe7185262802141cb3496a2e208",
"signed": null,
"hash": null,
"status": null,
"error": null,
"signatures": null,
"block_time": null,
"block_number": null
},
"estimated_unbonded_at": null,
"pubkey": "02db33d72ee215f1a61e5f4ffa098b9325cc1da6f5c3557974ad0f21a5ec9fe235"
},
"network_code": "cosmos",
"chain_code": "testnet",
"created_at": "2023-02-28T11:02:24.657Z",
"updated_at": "2023-02-28T11:20:48.379Z"
}


Submit Signed Undelegate 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_undelegate_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.
    • undelegate_tx_broadcasting : Transaction broadcasting and waiting for confirmation.
    • unbonding : Transaction successfully broadcast and stake is subject to unbonding period.
    • completed : Unbonding period is complete and tokens are successfully unstaked.
  • actions : array It includes the name & inputs of all next possible actions.
  • data : object Flow & transaction data.
Request
Example Response
{
"id": "f624c185-afb0-46d5-aa63-4d7649a2690a",
"operation": "unstaking",
"state": "undelegate_tx_broadcasting",
"actions": [
{
"name": "wait",
"estimated_state_change_at": "2023-02-28T11:22:30.864Z",
"inputs": []
}
],
"data": {
"delegator_address": "cosmos1u85upk2v7pr65g0wv2976zleu6v8qjl9qprvzl",
"validator_address": "cosmosvaloper1tflk30mq5vgqjdly92kkhhq3raev2hnz6eete3",
"amount": "1.0",
"memo": "",
"gas_price": null,
"gas_limit": null,
"undelegate_transaction": {
"raw": "7b226d65737361676573223a5b7b227479706555726c223a222f636f736d6f732e7374616b696e672e763162657461312e4d7367556e64656c6567617465222c2276616c7565223a7b2264656c656761746f7241646472657373223a22636f736d6f733175383575706b3276377072363567307776323937367a6c6575367638716a6c39717072767a6c222c2276616c696461746f7241646472657373223a22636f736d6f7376616c6f7065723174666c6b33306d71357667716a646c7939326b6b686871337261657632686e7a366565746533222c22616d6f756e74223a7b2264656e6f6d223a227561746f6d222c22616d6f756e74223a2231303030303030227d7d7d5d2c22666565223a7b22616d6f756e74223a5b7b22616d6f756e74223a2236323937222c2264656e6f6d223a227561746f6d227d5d2c22676173223a22323531383435227d2c226d656d6f223a22227d",
"signing_payload": "53ff624a7b8fb60956f3d88d249ff95e14202fe7185262802141cb3496a2e208",
"signed": "0aa3010aa0010a252f636f736d6f732e7374616b696e672e763162657461312e4d7367556e64656c656761746512770a2d636f736d6f733175383575706b3276377072363567307776323937367a6c6575367638716a6c39717072767a6c1234636f736d6f7376616c6f7065723174666c6b33306d71357667716a646c7939326b6b686871337261657632686e7a3665657465331a100a057561746f6d12073130303030303012670a500a460a1f2f636f736d6f732e63727970746f2e736563703235366b312e5075624b657912230a2102db33d72ee215f1a61e5f4ffa098b9325cc1da6f5c3557974ad0f21a5ec9fe23512040a020801180812130a0d0a057561746f6d12043632393710c5af0f1a4025126da1bb487a6a0e54081c6cde716f169b3c1e22247f147cf2d5eb244d189b220528ae3de60c2f04db07435eb893deb263fb315c00e238450c03221a53932e",
"hash": "C69560EAF192B82A6826972205A049CF80FF327E62737A246DEC4BC26EF4F6A2",
"status": null,
"error": null,
"signatures": [
{
"account_address": "cosmos1u85upk2v7pr65g0wv2976zleu6v8qjl9qprvzl",
"signature": ""
}
],
"block_time": null,
"block_number": null
},
"estimated_unbonded_at": null,
"pubkey": "02db33d72ee215f1a61e5f4ffa098b9325cc1da6f5c3557974ad0f21a5ec9fe235"
},
"network_code": "cosmos",
"chain_code": "testnet",
"created_at": "2023-02-28T11:02:24.657Z",
"updated_at": "2023-02-28T11:21:30.105Z"
}


Get Unstaking 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.
    • undelegate_tx_broadcasting : Transaction has been broadcast and is waiting for confirmation.
    • unbonding : Transaction successfully broadcast and stake is under unbonding period.
    • completed : Unbonding period is over and tokens are successfully undelegated.
  • actions : array It includes the name & inputs of all next possible actions.
  • data : object Flow & transaction data.
Request
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"
}