Documentation

Getting Started

Suggest Edits

There are two ways to start staking on the Polkadot network using the Staking API with a public node:

  • Stake directly.
  • Stake via a nomination pool.

Get an authentication token to start using Staking API. While staking, it is essential to keep a minimum deposit of 1 DOT on the account.

A request example is provided using cURL.

Staking directly

1. Create Bond Request

  1. Send a POST request to /api/v1/polkadot/{network}/staking/bond. Note that there is a dynamic minimum threshold to stake.

    Example request (for westend network):

    curl --request POST \
     --url https://api.p2p.org/api/v1/polkadot/westend/staking/bond \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <token>' \
     --header 'content-type: application/json' \
     --data '
{
  "stashAccountAddress": "5H6ryBWChC5w7eaQ4GZjo329sEnhvjetSr6MBEt42mZ5tPw5",
  "rewardDestinationType": "account",
  "rewardDestination": "5H6ryBWChC5w7eaQ4GZjo329sEnhvjetSr6MBEt42mZ5tPw5",
  "amount": 3
}'

    • stashAccountAddress — main stash account address which keeps tokens for bonding.

    • rewardDestinationType — rewards destination type:

      • staked — rewards will be sent to your stash account and added to your current bond (compounding rewards).
      • stash — rewards will be sent to your stash account as a transferrable balance (not compounding rewards).

    • account — rewards will be sent to any account you specify as a transferrable balance.

    • rewardDestination — rewards destination account address.

    • amount — amount of tokens to bond. DOT is used for the main network, KSM for Kusama, and WND for Westend.

    Example response:

    {
  "result": {
    "unsignedTransaction": "0xac0406000b00487835a302032c6eca5cdaa3e87d7f8e06d10015bf0508b52d301c8991af113d5cf49a53553f",
    "stashAccountAddress": "5H6ryBWChC5w7eaQ4GZjo329sEnhvjetSr6MBEt42mZ5tPw5",
    "rewardDestinationType": "account",
    "rewardDestination": "5H6ryBWChC5w7eaQ4GZjo329sEnhvjetSr6MBEt42mZ5tPw5",
    "amount": 3,
    "createdAt": "2023-08-15T15:07:54.795Z"
  }
}

    • unsignedTransaction — unsigned transaction in hex format. Sign the transaction and submit it to the blockchain to perform the called action.

    • stashAccountAddress — main stash account address which keeps tokens for bonding.

    • rewardDestinationType — rewards destination type:

      • staked — rewards will be sent to your stash account and added to your current bond (compounding rewards).
      • stash — rewards will be sent to your stash account as a transferrable balance (not compounding rewards).
      • account — rewards will be sent to any account you specify as a transferrable balance.

    • rewardDestination — rewards destination account address.

    • amount — amount of tokens to bond. DOT is used for the main network, KSM for Kusama, and WND for Westend.

    • createdAt — timestamp of the transaction in the ISO 8601 format.

  2. Sign and broadcast the unsignedTransaction to the Polkadot network.

2. Create Nomination Request

  1. Send a POST request to /api/v1/polkadot/{network}/staking/nominate to select validators within the Polkadot network.

    Example request (for westend network):

    curl --request POST \
     --url https://api.p2p.org/api/v1/polkadot/westend/staking/nominate \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <token>' \
     --header 'content-type: application/json' \
     --data '
{
  "stashAccountAddress": "5H6ryBWChC5w7eaQ4GZjo329sEnhvjetSr6MBEt42mZ5tPw5"
}'
    • stashAccountAddress — main stash account address which keeps tokens for bonding.

    Example response:

    {
  "result": {
    "unsignedTransaction": "0x2102040605100096b33e0a9647f13198ad16a2812c549a363646a3a7ddbdcc5590f5839c408c6200767f36484b1e2acf5c265c7a64bfb46e95259c66a8189bbcd216195def43685200c21ad1e5198cc0dc3b0f9f43a50f292678f63235ea321e59385d7ee45a7208360018164fa6f9ce28792fb781185e8de4e6eaae34c0f545e5864952fe23c183df0c",
    "stashAccountAddress": "5H6ryBWChC5w7eaQ4GZjo329sEnhvjetSr6MBEt42mZ5tPw5",
    "targets": [
      "5FUJHYEzKpVJfNbtXmR9HFqmcSEz6ak7ZUhBECz7GpsFkSYR",
      "5Ek5JCnrRsyUGYNRaEvkufG1i1EUxEE9cytuWBBjA9oNZVsf",
      "5GTD7ZeD823BjpmZBCSzBQp7cvHR1Gunq7oDkurZr9zUev2n",
      "5CcHdjf6sPcEkTmXFzF2CfH7MFrVHyY5PZtSm1eZsxgsj1KC"
    ],
    "createdAt": "2023-09-18T14:49:23.998Z"
  }
}
    • unsignedTransaction — unsigned transaction in hex format. Sign the transaction and submit it to the blockchain to perform the called action.
    • stashAccountAddress — main stash account address which keeps tokens for bonding.
    • targets — selected validators in the targets.
    • createdAt — timestamp of the transaction in the ISO 8601 format.

  2. Sign and broadcast the unsignedTransaction to the Polkadot network.

3. Add Proxy Account — optional step

You can add a staking proxy to utilize the main stash account less frequently. It allows delegating your staking rights to another account, which can then sign transactions on your behalf. The original account retains all of its rights, and the proxy account can be removed at any time.

  1. Send a POST request to /api/v1/polkadot/{network}/account/add.

    Example request (for westend network):

    curl --request POST \
     --url https://api.p2p.org/api/v1/polkadot/westend/account/add \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <token>' \
     --header 'content-type: application/json' \
     --data '
{
  "stashAccountAddress": "5H6ryBWChC5w7eaQ4GZjo329sEnhvjetSr6MBEt42mZ5tPw5",
  "proxyAccountAddress": "5Ggpg3JepXM3ZrktNpoc5QA1sKaFVpUPWMRr7jppiMxTuU75"
}'
    • stashAccountAddress — main stash account address which keeps tokens for bonding; a proxied address that transfers rights to a proxy account.
    • proxyAccountAddress — address that receives rights from the proxied account.

    Example response:

    {
  "result": {
    "unsignedTransaction": "0xa404160100cc7cb7325ad1208212e2d8ee41a7572e816d53ac1bcac1be5df433486819213c0200000000",
    "createdAt": "2023-09-18T14:49:23.998Z"
  }
}
    • unsignedTransaction — unsigned transaction in hex format. Sign the transaction and submit it to the blockchain to perform the called action.
    • createdAt — timestamp of the transaction in the ISO 8601 format.

  2. Sign and broadcast the unsignedTransaction to the Polkadot network.

Staking via a nomination pool

1. Create Bond Request

  1. Create a bond request by sending a POST request to /api/v1/polkadot/{network}/staking/pool/bond. The P2P.org pool ID on Polkadot mainnet is 238.

    Example request (for westend network):

    curl --request POST \
  --url https://api.p2p.org/api/v1/polkadot/westend/staking/pool/bond \
  --header 'accept: application/json' \
  --header 'authorization: Bearer <token>' \
  --header 'content-type: application/json' \
  --data '
{
"stashAccountAddress": "5H6ryBWChC5w7eaQ4GZjo329sEnhvjetSr6MBEt42mZ5tPw5",
"poolId": 238,
"amount": 3
}'

    • stashAccountAddress — main stash account address which keeps tokens for bonding.

    • poolId — ID of the nomination pool.

    • amount — amount of tokens to bond. DOT is used for the main network, KSM for Kusama, and WND for Westend.

    Example response:

    {
"result": {
 "unsignedTransaction": "0xac0406000b00487835a302032c6eca5cdaa3e87d7f8e06d10015bf0508b52d301c8991af113d5cf49a53553f",
 "amount": 3,
 "createdAt": "2023-08-15T15:07:54.795Z"
}
}

    • unsignedTransaction — unsigned transaction in hex format. Sign the transaction and submit it to the blockchain to perform the called action.

    • amount — amount of tokens to bond. DOT is used for the main network, KSM for Kusama, and WND for Westend.

    • createdAt — timestamp of the transaction in the ISO 8601 format.

  2. Sign and broadcast the unsignedTransaction to the Polkadot network.

2. Create Set Permission Request

  1. Grant permission to the pool for managing rewards on your behalf by sending a POST request to api/v1/polkadot/{network}/staking/pool/set-claim-permission.

    Example request (for westend network):

    curl --request POST \
  --url https://api.p2p.org/api/v1/polkadot/westend/staking/pool/set-claim-permission \
  --header 'accept: application/json' \
  --header 'authorization: Bearer <token>' \
  --header 'content-type: application/json' \
  --data '
{
  "stashAccountAddress": "5H6ryBWChC5w7eaQ4GZjo329sEnhvjetSr6MBEt42mZ5tPw5",
  "permission": "PermissionlessAll"
}
'

    • stashAccountAddress — main stash account address which keeps tokens for bonding.

    • permission — state of the permission to grant:

      • Permissioned — only you can claim, bond or withdraw rewards. If this level of permission is set, an additional Claiming Payout request is needed.
      • PermissionlessCompound — compounding (claim and then bond) of your rewards on your behalf is permitted.
      • PermissionlessWithdraw — withdrawing (claim and then keep as a free balance) of your rewards on your behalf is permitted.
      • PermissionlessAll — claiming, bonding and withdrawing rewards on your behalf are permitted.

    Example response:

    {
  "result": {
    "unsignedTransaction": "0xa404160200165874de804160c3cd013d9b6f4bba864657c4c2168a542f78ff14a0253873190200000000",
    "createdAt": "2023-08-24T08:23:18.830Z"
  },
  "error": {}
}

  • unsignedTransaction — unsigned transaction in hex format. Sign the transaction and submit it to the blockchain to perform the called action.

  • createdAt — timestamp of the transaction in the ISO 8601 format.

  1. Sign and broadcast the unsignedTransaction to the Polkadot network.

3. Create Claim Payout Request

Unlike direct staking, after the rewards is distributed to the nomination pool by a validator, each pool member has to claim their part manually. Since that, to bond, compound or withdraw your rewards, you may need to perform an additional claiming payout request.

Whether it is required depends on the claim rewards permissions you set in the step 2:

  • For PermissionlessAll, the step is optional.
  • For Permissioned, the step is necessary, as you are the only who can claim the rewards.
  • For PermissionlessCompound and PermissionlessWithdraw, the step is required if you want to withdraw and compound your rewards accordingly.

To create claim payout request:

  1. Send a POST request to /api/v1/polkadot/{network}/staking/pool/claim-payout.

    Example request (for westend network):

    curl --request POST \
     --url https://api.p2p.org/api/v1/polkadot/westend/staking/pool/claim-payout \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <token>' \
     --header 'content-type: application/json' \
     --data '
{
  "stashAccountAddress": "5H6ryBWChC5w7eaQ4GZjo329sEnhvjetSr6MBEt42mZ5tPw5"
}'
    • stashAccountAddress — main stash account address which keeps tokens for bonding.

    Example response:

    {
  "result": {
    "unsignedTransaction": "0xa404160100cc7cb7325ad1208212e2d8ee41a7572e816d53ac1bcac1be5df433486819213c0200000000",
    "createdAt": "2023-08-24T08:23:18.830Z"
  }
}
    • unsignedTransaction — unsigned transaction in hex format. Sign the transaction and submit it to the blockchain to perform the called action.
    • createdAt — timestamp of the transaction in the ISO 8601 format.

  2. Sign and broadcast the unsignedTransaction to the Polkadot network.

What's Next?

Updated about 1 month ago