# Unstaking NEAR

Unstaking NEAR is a simple process. We will collect:

- The delegating address
- The signing address
- The validator address to undelegate from
- Amount of NEAR to be undelegated
- Optionally, a maximum Boolean if you wish to undelegate the full amount without having to check the current balance
- Optionally, a max gas amount (upper limit of the transaction fee to be paid)

Once the undelegation transaction is confirmed on-chain, the unbonding process will begin immediately.

NEAR has an unbonding period of four epochs (≈ 48-60h). During this time, the unbonding NEAR will be illiquid and will not earn rewards. Upon completion of the unbonding period, the NEAR will be available to be withdrawn.

If you have a balance waiting to be withdrawn and do not wish to undelegate more NEAR, you can use the `create_withdraw_tx` action to withdraw from that balance without first unbonding any NEAR.

## Create New Unstaking Flow

To initiate the undelegation process, create a new flow with a `POST` request to `/flows`.

### URL

`https://api.figment.io/flows`

### Request

- `protocol`\*: `string` Protocol this flow operates on (ex. `near`).
- `network`\*: `string` Network this flow operates on (ex. `testnet`).
- `operation`\*: `string` The operation to perform (ex. `unstaking`).

JSON

```json
{
  "protocol": "near",
  "network": "testnet",
  "operation": "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 NEAR.

- `delegator_address` : The delegator address.
    - `delegator_pubkey` : The public key of the signing account.
    - `validator_address` : Validator address from which NEAR will be undelegated.
    - `undelegate_amount` : The amount of NEAR to be undelegated.
    - `undelegate_maximum` : Set to `true` if you wish to unbond the full delegated balance without needing to know the exact delegated balance.
    - `max_gas` : The maximum transaction fee.
- `data` : `object` Flow & transaction data.

JSON

```json
{
  "id": "4f866b7f-2e79-4c61-9bb4-398777c12a0b",
  "state": "initialized",
  "actions": [
    {
      "name": "create_withdraw_tx",
      "inputs": [
        {
          "name": "delegator_address",
          "display": "Delegator Address",
          "type": "string",
          "validations": [
            {"type": "presence", "options": {}}
          ]
        },
        {
          "name": "delegator_pubkey",
          "display": "Delegator Pubkey",
          "type": "string",
          "validations": [
            {"type": "presence", "options": {}}
          ]
        },
        {
          "name": "validator_address",
          "display": "Validator Address",
          "type": "string",
          "validations": [
            {"type": "presence", "options": {}}
          ]
        },
        {
          "name": "withdraw_amount",
          "display": "Withdraw Amount",
          "type": "decimal",
          "validations": [
            {"type": "presence", "options": {"unless": "withdraw_maximum"}},
            {"type": "numericality", "options": {"unless": "withdraw_maximum", "greater_than": 0}}
          ]
        },
        {
          "name": "withdraw_maximum",
          "display": "Withdraw Maximum",
          "type": "boolean",
          "validations": []
        },
        {
          "name": "max_gas",
          "display": "Max Gas",
          "type": "decimal",
          "validations": []
        }
      ]
    },
    {
      "name": "create_undelegate_tx",
      "inputs": [
        {
          "name": "delegator_address",
          "display": "Delegator Address",
          "type": "string",
          "validations": [
            {"type": "presence", "options": {}}
          ]
        },
        {
          "name": "delegator_pubkey",
          "display": "Delegator Pubkey",
          "type": "string",
          "validations": [
            {"type": "presence", "options": {}}
          ]
        },
        {
          "name": "validator_address",
          "display": "Validator Address",
          "type": "string",
          "validations": [
            {"type": "presence", "options": {}}
          ]
        },
        {
          "name": "undelegate_amount",
          "display": "Undelegate Amount",
          "type": "decimal",
          "validations": [
            {"type": "presence", "options": {"unless": "undelegate_maximum"}},
            {"type": "numericality", "options": {"unless": "undelegate_maximum", "greater_than": 0}}
          ]
        },
        {
          "name": "undelegate_maximum",
          "display": "Undelegate Maximum",
          "type": "boolean",
          "validations": []
        },
        {
          "name": "max_gas",
          "display": "Max Gas",
          "type": "decimal",
          "validations": []
        }
      ]
    }
  ],
  "data": {
    "delegator_address": null,
    "delegator_pubkey": null,
    "validator_address": null,
    "max_gas": null,
    "undelegate_amount": null,
    "undelegate_maximum": null,
    "undelegate_transaction": null,
    "estimated_inactive_at": null,
    "withdraw_amount": null,
    "withdraw_maximum": null,
    "withdraw_transaction": null
  },
  "protocol": "near",
  "network": "testnet",
  "created_at": "2023-02-27T17:51:08.550Z",
  "updated_at": "2023-02-27T17:51:08.550Z"
}
```

## Submit Undelegate Data

After collecting the required inputs, send a `PUT` request to `/flows/[:flow_id]/next` to proceed to the next step.

### URL

`https://api.figment.io/flows/[:flow_id]/next`

### Request

- `name`\*: `create_undelegate_tx`
- `inputs`\*: `object`
  - `delegator_address`\*: `string` The delegator address.
  - `delegator_pubkey`\*: `string` The pubkey of the signing account.
  - `validator_address`\*: `string` Validator address from which NEAR will be undelegated.
  - `undelegate_amount`\*: `number` The amount of NEAR to be undelegated.
  - `undelegate_maximum` : `boolean` Set to `true` if you wish to unbond the full delegated balance without needing to know the exact delegated balance.
  - `max_gas` : The maximum transaction fee.

JSON

```json
{
  "name": "create_undelegate_tx",
  "inputs": {
    "validator_address": "01node.pool.f863973.m0",
    "delegator_address": "slate-demo.testnet",
    "delegator_pubkey": "ed25519:5QA46X6NkNmsFdu9xWVBaLNowh9gGeF1c5r9u6NcxaLY",
    "undelegate_amount": "25"
  }
}
```

### Response

- `refresh_undelegate_tx`: If you need to get a fresh version of the transaction payload (i.e., the nonce has increased).
  - `sign_undelegate_tx`: Submit a signed transaction payload or an array of signatures to continue the flow.
  - `confirm_undelegate_tx_by_hash`: Submit a previously completed transaction hash to continue the flow.
- `data` : `object` Flow & transaction data.

JSON

```json
{
  "id": "4f866b7f-2e79-4c61-9bb4-398777c12a0b",
  "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": "0b81cc09294fc074814ad0de50f31644e5669f856105399b.testnet"
        },
        {
          "name": "delegator_pubkey",
          "display": "Delegator Pubkey",
          "description": "",
          "type": "string",
          "validations": [{"type": "presence", "options": {}}],
          "array": false,
          "default_value": "ed25519:NUbTcj78nHFFm1J8a1GFjenAnCKV32ZdBeeqem8oyLV"
        },
        {
          "name": "validator_address",
          "display": "Validator Address",
          "description": "",
          "type": "string",
          "validations": [{"type": "presence", "options": {}}],
          "array": false,
          "default_value": "legends.pool.f863973.m0"
        },
        {
          "name": "undelegate_amount",
          "display": "Undelegate Amount",
          "description": "",
          "type": "decimal",
          "validations": [{"type": "presence", "options": {"unless": "undelegate_maximum"}}, {"type": "numericality", "options": {"unless": "undelegate_maximum", "greater_than": 0}}],
          "array": false,
          "default_value": "5.0"
        },
        {
          "name": "undelegate_maximum",
          "display": "Undelegate Maximum",
          "description": "",
          "type": "boolean",
          "validations": [],
          "array": false,
          "default_value": null
        },
        {
          "name": "max_gas",
          "display": "Max Gas",
          "description": "in NEAR",
          "type": "decimal",
          "validations": [],
          "array": false,
          "default_value": null
        }
      ]
    },
    {
      "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
        },
        {
          "name": "signatures",
          "display": "Signatures",
          "description": "",
          "type": "array_of_signatures",
          "validations": [],
          "array": true,
          "default_value": null,
          "element_type": "signature_data"
        }
      ]
    },
    {
      "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": "0b81cc09294fc074814ad0de50f31644e5669f856105399b.testnet",
    "delegator_pubkey": "ed25519:NUbTcj78nHFFm1J8a1GFjenAnCKV32ZdBeeqem8oyLV",
    "validator_address": "legends.pool.f863973.m0",
    "max_gas": null,
    "undelegate_amount": "5.0",
    "undelegate_maximum": null,
    "undelegate_transaction": {
      "raw": "380000003062383163633039323934666330373438313461643064653530663331363434653536363966383536313035333939622e746573746e657400058065d39e25bf5038afbacc1b7312c5dc3761770626288020d783f8685058aa422e4c11c36b0000170000006c6567656e64732e706f6f6c2e663836333937332e6d30f95da7beed58598a6e813c1303a2374028fe6cfe76f467ee656899c7400c640d010000000207000000756e7374616b65260000007b22616d6f756e74223a2235303030303030303030303030303030303030303030303030227d00e057eb481b000000000000000000000000000000000000",
      "signing_payload": "ab06236a0916604347fbbfc0c803d374fd28e6eb69f2edce3c2e6ac23e1f0452",
      "signed": null,
      "hash": "CWc9R6SdHVwVHj1rhYiwBgK2sqkVdbBj1wG4QniUXwqT",
      "status": null,
      "error": null,
      "signatures": null
    },
    "estimated_inactive_at": null,
    "withdraw_amount": null,
    "withdraw_maximum": null,
    "withdraw_transaction": null
  },
  "protocol": "near",
  "network": "testnet",
  "created_at": "2023-02-27T17:51:08.550Z",
  "updated_at": "2023-02-27T18:01:39.469Z"
}
```

## 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 `/flows/[:flow_id]/next` with the signed payload. The Staking API will broadcast the transaction to the NEAR network.

### URL

`https://api.figment.io/flows/[:flow_id]/next`

### Request

- `name`\*: `sign_undelegate_tx`
- `inputs`\*: `object`
  - `transaction_payload`\*: `string` 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.

JSON

```json
{
  "name": "sign_undelegate_tx",
  "inputs": {
    "transaction_payload": "12000000736c6174652d64656d6f2e746573746e657400415d57cdf21d28e35e0cfa864e895c18b4bc6a711642d38eb6762af81ec1cf3905cc1038fc5700001600000030316e6f64652e706f6f6c2e663836333937332e6d308e0f6b6bb5b283186516419e2d4c06a47f7d55b456b83947fb5f8fb815957df6010000000207000000756e7374616b65270000007b22616d6f756e74223a223235303030303030303030303030303030303030303030303030227d00e057eb481b00000000000000000000000000000000000000d27fe1cabf4535e130002217b79d743941e22110d0b3b3f446aba92d3416eb5774efb6aa925af5ebc78e459218de9ae0baeee7de0e4fad77d299ace7fcf80107"
  }
}
```

### 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 confirmation.
  - `cool_down` : Transaction has been confirmed and the delegation is unbonding.
- `actions` : `array` It includes the `name` & `inputs` of all next possible actions.
- `data` : `object` Flow & transaction data.

JSON

```json
{
  "id": "4f866b7f-2e79-4c61-9bb4-398777c12a0b",
  "state": "undelegate_tx_broadcasting",
  "actions": [
    {
      "name": "wait",
      "estimated_state_change_at": "2023-02-27T18:30:37.767Z",
      "inputs": []
    }
  ],
  "data": {
    "delegator_address": "0b81cc09294fc074814ad0de50f31644e5669f856105399b.testnet",
    "delegator_pubkey": "ed25519:NUbTcj78nHFFm1J8a1GFjenAnCKV32ZdBeeqem8oyLV",
    "validator_address": "legends.pool.f863973.m0",
    "max_gas": null,
    "undelegate_amount": "5.0",
    "undelegate_maximum": null,
    "undelegate_transaction": {
      "raw": "380000003062383163633039323934666330373438313461643064653530663331363434653536363966383536313035333939622e746573746e657400058065d39e25bf5038afbacc1b7312c5dc3761770626288020d783f8685058aa422e4c11c36b0000170000006c6567656e64732e706f6f6c2e663836333937332e6d30f95da7beed58598a6e813c1303a2374028fe6cfe76f467ee656899c7400c640d010000000207000000756e7374616b65260000007b22616d6f756e74223a2235303030303030303030303030303030303030303030303030227d00e057eb481b000000000000000000000000000000000000",
      "signing_payload": "ab06236a0916604347fbbfc0c803d374fd28e6eb69f2edce3c2e6ac23e1f0452",
      "signed": null,
      "hash": "CWc9R6SdHVwVHj1rhYiwBgK2sqkVdbBj1wG4QniUXwqT",
      "status": null,
      "error": null,
      "signatures": null
    },
    "estimated_inactive_at": null,
    "withdraw_amount": null,
    "withdraw_maximum": null,
    "withdraw_transaction": null
  },
  "protocol": "near",
  "network": "testnet",
  "created_at": "2023-02-27T17:51:08.550Z",
  "updated_at": "2023-02-27T18:29:37.321Z"
}
```

## Submit Withdraw Data

After collecting the required inputs, send a `PUT` request to `/flows/[:flow_id]/next` to move on to the next step.

### URL

`https://api.figment.io/flows/[:flow_id]/next`

### Request

- `name`\*: `create_withdraw_tx`
- `inputs`\*: `object`
  - `delegator_address`\*: `string` The delegator address.
  - `delegator_pubkey`\*: `string` The pubkey of the signing account.
  - `validator_address`\*: `string` Validator address from which NEAR will be undelegated.
  - `withdraw_amount`\*: `number` The amount of NEAR to be withdrawn.
  - `withdraw_maximum` : `boolean` Set to `true` if you wish to withdraw the full available balance without needing to know the exact available balance.
  - `max_gas` : The maximum transaction fee.

JSON

```json
{
  "name": "create_withdraw_tx",
  "inputs": {
    "validator_address": "01node.pool.f863973.m0",
    "delegator_address": "slate-demo.testnet",
    "delegator_pubkey": "ed25519:5QA46X6NkNmsFdu9xWVBaLNowh9gGeF1c5r9u6NcxaLY",
    "withdraw_amount": "25"
  }
}
```

### Response

- `refresh_withdraw_tx`: If you need to get a fresh version of the transaction payload (i.e., if the nonce needs to be updated)
  - `sign_withdraw_tx`: Submit a signed transaction payload or an array of signatures to continue the flow.
  - `confirm_withdraw_tx_by_hash`: Submit a previously completed transaction hash to continue the flow.
- `data` : `object` Flow & transaction data.

JSON

```json
{
  "id": "4f866b7f-2e79-4c61-9bb4-398777c12a0b",
  "operation": "unstaking",
  "state": "withdraw_tx_signature",
  "actions": [
    {
      "name": "refresh_withdraw_tx",
      "inputs": [
        {
          "name": "delegator_address",
          "display": "Delegator Address",
          "type": "string",
          "validations": [{"type": "presence", "options": {}}],
          "array": false,
          "default_value": "0b81cc09294fc074814ad0de50f31644e5669f856105399b.testnet"
        },
        {
          "name": "delegator_pubkey",
          "display": "Delegator Pubkey",
          "type": "string",
          "validations": [{"type": "presence", "options": {}}],
          "array": false,
          "default_value": "ed25519:NUbTcj78nHFFm1J8a1GFjenAnCKV32ZdBeeqem8oyLV"
        },
        {
          "name": "validator_address",
          "display": "Validator Address",
          "type": "string",
          "validations": [{"type": "presence", "options": {}}],
          "array": false,
          "default_value": "legends.pool.f863973.m0"
        },
        {
          "name": "withdraw_amount",
          "display": "Withdraw Amount",
          "type": "decimal",
          "validations": [{"type": "presence", "options": {"unless": "withdraw_maximum"}}, {"type": "numericality", "options": {"unless": "withdraw_maximum", "greater_than": 0}}],
          "array": false,
          "default_value": "5.0"
        },
        {
          "name": "withdraw_maximum",
          "display": "Withdraw Maximum",
          "type": "boolean",
          "validations": [],
          "array": false,
          "default_value": null
        },
        {
          "name": "max_gas",
          "display": "Max Gas",
          "type": "decimal",
          "validations": [],
          "array": false,
          "default_value": null
        }
      ]
    },
    {
      "name": "sign_withdraw_tx",
      "inputs": [
        {
          "name": "transaction_payload",
          "display": "Transaction Payload",
          "type": "signed_transaction",
          "validations": [{"type": "sign_payload", "options": {}}],
          "array": false,
          "default_value": null
        },
        {
          "name": "signatures",
          "display": "Signatures",
          "type": "array_of_signatures",
          "validations": [],
          "array": true,
          "default_value": null,
          "element_type": "signature_data"
        }
      ]
    },
    {
      "name": "confirm_withdraw_tx_by_hash",
      "inputs": [
        {
          "name": "hash",
          "display": "Hash",
          "type": "string",
          "validations": [{"type": "presence", "options": {}}],
          "array": false,
          "default_value": null
        },
        {
          "name": "block_number",
          "display": "Block Number",
          "type": "integer",
          "validations": [],
          "array": false,
          "default_value": null
        }
      ]
    }
  ],
  "data": {
    "delegator_address": "0b81cc09294fc074814ad0de50f31644e5669f856105399b.testnet",
    "delegator_pubkey": "ed25519:NUbTcj78nHFFm1J8a1GFjenAnCKV32ZdBeeqem8oyLV",
    "validator_address": "legends.pool.f863973.m0",
    "max_gas": null,
    "undelegate_amount": "5.0",
    "undelegate_maximum": null,
    "undelegate_transaction": {
      "raw": "380000003062383163633039323934666330373438313461643064653530663331363434653536363966383536313035333939622e746573746e657400058065d39e25bf5038afbacc1b7312c5dc3761770626288020d783f8685058aa422e4c11c36b0000170000006c6567656e64732e706f6f6c2e663836333937332e6d30d7d1c76dbf0debe82e9e8c6a11ecb54be99e1d288ca1993e5071a2c68cdfaeed0100000002080000007769746864726177260000007b22616d6f756e74223a2235303030303030303030303030303030303030303030303030227d00e057eb481b000000000000000000000000000000000000",
      "signing_payload": "3d86e4c351bc002fd7fbdb0686cc872393c87ffe3a4470cb010857bc739d6784",
      "signed": null,
      "hash": "59BAsPfQtJEzaNJghq6HYDhTBupTUvm63FRNdXG447vb",
      "status": null,
      "error": null,
      "signatures": []
    },
    "estimated_inactive_at": "2023-03-01T18:29:48.741Z",
    "withdraw_amount": "5.0",
    "withdraw_maximum": null,
    "withdraw_transaction": {
      "raw": "380000003062383163633039323934666330373438313461643064653530663331363434653536363966383536313035333939622e746573746e657400058065d39e25bf5038afbacc1b7312c5dc3761770626288020d783f8685058aa442e4c11c36b0000170000006c6567656e64732e706f6f6c2e663836333937332e6d30d7d1c76dbf0debe82e9e8c6a11ecb54be99e1d288ca1993e5071a2c68cdfaeed0100000002080000007769746864726177260000007b22616d6f756e74223a2235303030303030303030303030303030303030303030303030227d00e057eb481b000000000000000000000000000000000000"
    }
  },
  "protocol": "near",
  "network": "testnet",
  "created_at": "2023-02-27T17:51:08.550Z",
  "updated_at": "2023-03-01T18:22:49.608Z"
}
```