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.
  • 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"
}