Claiming MATIC rewards is a simple process. We will collect:

The address from which MATIC is delegated
The Validator contract to which they are delegated
Optionally, the gas limit & gas price to be paid for the claim transaction

🚧
Important
The amount of MATIC rewards must be greater than 1.0 MATIC before a Claim Rewards transaction is possible using the Staking API.
Attempts to create a Claim Rewards transaction for a given delegator address when the pending reward balance is below 1.0 MATIC will result in the following validation error:
{  
  "code": "invalid",  
  "message": "Request could not be processed due to validation errors!",  
  "errors": {  
    "delegator_address": [  
      {  
        "code": "reward amount has to be greater than 1.0 MATIC",  
        "message": "reward amount has to be greater than 1.0 MATIC",  
        "context": {}  
      }  
    ]  
  }  
}

In the following guide we will illustrate how to claim MATIC rewards.

Create New Claim Rewards Flow

To claim the staking rewards with Staking API firstly we need to create a new Flow with a POST request to /api/v1/flows.

URL

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

Request

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

{
  "flow": {
    "network_code": "polygon",
    "chain_code": "testnet",
    "operation": "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_claim_rewards_tx : Use this action to claim staking rewards.
  - delegator_address : The address delegating MATIC.
  - validator_address : The Validator contract address to which MATIC is delegated.
  - gas_limit : Adjust the gas limit for the claim transaction.
  - gas_price : Adjust gas price for the claim transaction.
data : object Flow & transaction data.

{
  "id": "faa0231b-b993-4fc2-9360-0cda96ef415c",
  "operation": "claim_rewards",
  "state": "initialized",
  "actions": [
    {
      "name": "create_claim_rewards_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": {}
            }
          ],
          "array": false,
          "default_value": null
        },
        {
          "name": "gas_limit",
          "display": "Gas Limit",
          "description": "",
          "type": "string",
          "validations": [
            {
              "type": "numericality",
              "options": {
                "allow_blank": true,
                "only_integer": true,
                "greater_than": 0
              }
            }
          ],
          "array": false,
          "default_value": null
        },
        {
          "name": "gas_price",
          "display": "Gas Price",
          "description": "in GWEI",
          "type": "string",
          "validations": [
            {
              "type": "numericality",
              "options": {
                "allow_blank": true,
                "greater_than": 0
              }
            },
            {
              "type": "precision",
              "options": {
                "allow_blank": true,
                "max": 9
              }
            }
          ],
          "array": false,
          "default_value": null
        }
      ]
    }
  ],
  "data": {
    "delegator_address": null,
    "validator_address": null,
    "claim_rewards_transaction": null
  },
  "network_code": "polygon",
  "chain_code": "testnet",
  "created_at": "2023-03-02T19:33:40.360Z",
  "updated_at": "2023-03-02T19:33:40.360Z"
}

Submit Claim Rewards Data

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

URL

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

Request

name* : create_claim_rewards_tx
inputs* : object
- delegator_address* : string The address delegating MATIC.
- validator_address* : string The Validator contract address to which MATIC are delegated.
- gas_limit : string The gas limit for the transaction.
- gas_price : string The highest gas price you will pay for the transaction.

{
  "name": "create_claim_rewards_tx",
  "inputs": {
    "delegator_address": "0x542138451d0953Aa082dE659d2A1ca1e5EF452Bf",
    "validator_address": "0x15ED57Ca28cbebb58d9c6C62F570046BC089bC66"
  }
}

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_claim_rewards_tx : If you need to get a fresh version of the transaction payload (for example, if the nonce needs to be updated).
- sign_claim_rewards_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_claim_rewards_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 Flow & transaction data.

{
  "id": "07d6752c-c412-4cfa-a12c-65feab06acd6",
  "state": "claim_rewards_tx_signature",
  "actions": [
    {
      "name": "refresh_claim_rewards_tx",
      "inputs": []
    },
    {
      "name": "sign_claim_rewards_tx",
      "inputs": [
        {
          "name": "transaction_payload",
          "display": "Transaction Payload",
          "description": "",
          "type": "signed_transaction",
          "validations": [],
          "signers": [
            "0x542138451d0953Aa082dE659d2A1ca1e5EF452Bf"
          ],
          "transaction_payload": "0x02f86d05028459682f0084597a1b168304cf969415ed57ca28cbebb58d9c6c62f570046bc089bc6680b844c83ec04d0000000000000000000000000000000000000000000000000de0b6b3a76400000000000000000000000000000000000000000000000000000de0b6b3a7640000c0"
        },
        {
          "name": "signatures",
          "display": "Signatures",
          "description": "",
          "type": "array_of_signatures",
          "validations": [],
          "signers": [
            "0x542138451d0953Aa082dE659d2A1ca1e5EF452Bf"
          ],
          "transaction_payload": "0x02f86d05028459682f0084597a1b168304cf969415ed57ca28cbebb58d9c6c62f570046bc089bc6680b844c83ec04d0000000000000000000000000000000000000000000000000de0b6b3a76400000000000000000000000000000000000000000000000000000de0b6b3a7640000c0",
          "signing_payload": null
        }
      ]
    }
  ],
  "data": {
    "delegator_address": "0x542138451d0953Aa082dE659d2A1ca1e5EF452Bf",
    "validator_address": "0x15ED57Ca28cbebb58d9c6C62F570046BC089bC66",
    "amount": "1.0",
    "max_shares_to_burn": 1000000000000000000,
    "max_slippage_percentage": 0,
    "exchange_rate": "100000000000000000000000000000.0",
    "exchange_rate_precision": "100000000000000000000000000000.0",
    "unbond_transaction": {
      "raw": "0x02f86d05028459682f0084597a1b168304cf969415ed57ca28cbebb58d9c6c62f570046bc089bc6680b844c83ec04d0000000000000000000000000000000000000000000000000de0b6b3a76400000000000000000000000000000000000000000000000000000de0b6b3a7640000c0",
      "signing_payload": null,
      "signed": null,
      "hash": null,
      "status": null,
      "error": null,
      "signatures": null,
      "gas_limit": null,
      "gas_price": null
    },
    "claim_transaction": null,
    "estimated_unbonded_at": null,
    "unbond_checkpoint": null,
    "unbond_nonce": null
  },
  "network_code": "polygon",
  "chain_code": "testnet",
  "created_at": "2022-10-06T23:40:33.826Z",
  "updated_at": "2022-10-07T17:22:05.511Z"
}

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, you will PUT /api/v1/flows/[:flow_id]/next and the Staking API will broadcast the transaction to the Polygon network.

URL

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

Request

name* : sign_claim_rewards_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.

{
  "name": "sign_claim_rewards_tx",
  "inputs": {
    "transaction_payload": "0x02f8af05808459682f00845994f6fa82b58394499d11e0b6eac7c0593d8fb292dcbbf815fb29ae80b844095ea7b300000000000000000000000000200ea4ee292e253e6ca07dba5edc07c8aa37a3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffc001a08019145182b704f15aca2a95242e25abfe9382dd74d0c15e88087978beb476b1a05b4c37b70e316c91e6a19738208e7eae6b79dd2c8ef62aa229f76548490c26b7"
  }
}

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.
- claim_rewards_tx_broadcasting : the transaction has been broadcast but not confirmed.
- done : the transaction has been confirmed and the rewards are claimed.
actions : array It includes the name & inputs of all next possible actions.
data : object Flow & transaction data.

{
  "id": "e6dc662e-f77c-4235-9b28-7141d90c8ab8",
  "state": "claim_rewards_tx_broadcasting",
  "actions": [
    {
      "name": "wait",
      "estimated_state_change_at": "2022-10-07T17:16:44.809Z",
      "inputs": []
    }
  ],
  "data": {
    "delegator_address": "0x542138451d0953Aa082dE659d2A1ca1e5EF452Bf",
    "validator_address": "0x15ED57Ca28cbebb58d9c6C62F570046BC089bC66",
    "amount": "1.0",
    "minimum_shares_to_mint": 0,
    "max_slippage_percentage": null,
    "exchange_rate": null,
    "exchange_rate_precision": null,
    "allowance_transaction": {
      "raw": "0x02f86c05808459682f00845994f6fa82b58394499d11e0b6eac7c0593d8fb292dcbbf815fb29ae80b844095ea7b300000000000000000000000000200ea4ee292e253e6ca07dba5edc07c8aa37a3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffc0",
      "signing_payload": null,
      "signed": "0x02f8af05808459682f00845994f6fa82b58394499d11e0b6eac7c0593d8fb292dcbbf815fb29ae80b844095ea7b300000000000000000000000000200ea4ee292e253e6ca07dba5edc07c8aa37a3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffc001a08019145182b704f15aca2a95242e25abfe9382dd74d0c15e88087978beb476b1a05b4c37b70e316c91e6a19738208e7eae6b79dd2c8ef62aa229f76548490c26b7",
      "hash": "0xb71295568a41375014cb4de57ffbdb489f9d81283b3d6647029424d72c176f6d",
      "status": null,
      "error": null,
      "signatures": [],
      "gas_limit": null,
      "gas_price": null
    },
    "delegate_transaction": null
  },
  "network_code": "polygon",
  "chain_code": "testnet",
  "created_at": "2022-10-06T22:57:14.491Z",
  "updated_at": "2022-10-07T17:15:43.981Z"
}

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://matic-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.
- claim_rewards_tx_broadcasting — The transaction has been broadcast but not confirmed.
- done : The transaction has been confirmed.
actions : array It includes the name & inputs of all next possible actions.
data : object Flow & transaction data.

{
  "id": "536921d0-d0f3-4887-8177-69c855cbcce3",
  "operation": "staking",
  "state": "completed",
  "actions": [],
  "data": {
    "delegator_address": "0x6BeA1177Ff310983f84D4Fc77b7467a3bD5626ed",
    "validator_address": "0x15ED57Ca28cbebb58d9c6C62F570046BC089bC66",
    "amount": "1.0",
    "minimum_shares_to_mint": 0,
    "max_slippage_percentage": null,
    "exchange_rate": null,
    "exchange_rate_precision": null,
    "allowance_transaction": {
      "raw": "0x02f86d05808459682f00850eaa6fba0e82b58394499d11e0b6eac7c0593d8fb292dcbbf815fb29ae80b844095ea7b300000000000000000000000000200ea4ee292e253e6ca07dba5edc07c8aa37a3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffc0",
      "signing_payload": "0xd0c61a6d5d143d80f9f1455ec289275a096c65d4bfb89afb981857835c0106a6",
      "signed": "0x02f8b005808459682f00850eaa6fba0e82b58394499d11e0b6eac7c0593d8fb292dcbbf815fb29ae80b844095ea7b300000000000000000000000000200ea4ee292e253e6ca07dba5edc07c8aa37a3ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffc001a0a9cac4be7a0c56d6ed520814958b94d4385b1ac7d791485f85c6c58fa53e0d8aa002f14d836c1b5090b12ef16566056abd57e6fce013a759e444d925b8951633ea",
      "hash": "0x754e90f50c9b656e469baea0b18bb8221b58170b0fb57556b62d51c60d494af9",
      "status": null,
      "error": null,
      "signatures": [],
      "block_time": null,
      "gas_limit": null,
      "gas_price": null
    },
    "delegate_transaction": {
      "raw": "0x02f86e05018459682f00850a82b48cc683039b269415ed57ca28cbebb58d9c6c62f570046bc089bc6680b8446ab150710000000000000000000000000000000000000000000000000de0b6b3a76400000000000000000000000000000000000000000000000000000000000000000000c0",
      "signing_payload": "0x1032c3301634d32b8da886c67a72346ecb7f9b818e43c5675797233d2e0ecdac",
      "signed": "0x02f8b105018459682f00850a82b48cc683039b269415ed57ca28cbebb58d9c6c62f570046bc089bc6680b8446ab150710000000000000000000000000000000000000000000000000de0b6b3a76400000000000000000000000000000000000000000000000000000000000000000000c001a0d296fcf71df637b5642425980baa23ad635e18d8a321791a015a4458c53e3684a01eb9e8493d106997e66d065aa7a914b297bde333d7376c9f0869ce3d5bdc7388",
      "hash": "0x6f3321969a9815c7a1274514a03fec5314ac60d1d66674455f8e1e1941f870d4",
      "status": "confirmed",
      "error": null,
      "signatures": [],
      "block_time": "2023-03-02T18:53:48.000Z",
      "gas_limit": null,
      "gas_price": null
    }
  },
  "network_code": "polygon",
  "chain_code": "testnet",
  "created_at": "2023-03-02T18:23:42.248Z",
  "updated_at": "2023-03-02T18:53:50.297Z"
}