Getting Started

There are two ways to start staking on the Avail 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.

Request examples are provided using cURL.

Staking directly

1. Create Bond and Nomination Request

  1. Send a POST request to /api/v1/avail/{network}/staking/direct/stake to stake the requested amount and nominate a validator in the Avail network. Note that there is a dynamic minimum threshold to stake.

    Example request (for mainnet network):

    curl --request POST \
         --url https://api.p2p.org/api/v1/avail/mainnet/staking/direct/stake \
         --header 'accept: application/json' \
         --header 'authorization: Bearer <token>' \
         --header 'content-type: application/json' \
         --data '
    {
      "stashAccountAddress": "5H6ryBWChC5w7eaQ4GZjo329sEnhvjetSr6MBEt42mZ5tPw5",
      "rewardDestinationType": "account",
      "rewardDestination": "5H6ryBWChC5w7eaQ4GZjo329sEnhvjetSr6MBEt42mZ5tPw5",
      "amount": 1000
    }'
    
    • 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).
      • controller — rewards will be sent to the controller account.
      • 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. AVAIL is used for the mainnet network.

    Example response:

    {
      "result": {
        "unsignedTransaction": "0xac0406000b00487835a302032c6eca5cdaa3e87d7f8e06d10015bf0508b52d301c8991af113d5cf49a53553f",
        "stashAccountAddress": "5H6ryBWChC5w7eaQ4GZjo329sEnhvjetSr6MBEt42mZ5tPw5",
        "rewardDestinationType": "account",
        "rewardDestination": "5H6ryBWChC5w7eaQ4GZjo329sEnhvjetSr6MBEt42mZ5tPw5",
        "amount": 1000,
        "targets": [
          "5FUJHYEzKpVJfNbtXmR9HFqmcSEz6ak7ZUhBECz7GpsFkSYR",
          "5Ek5JCnrRsyUGYNRaEvkufG1i1EUxEE9cytuWBBjA9oNZVsf",
          "5GTD7ZeD823BjpmZBCSzBQp7cvHR1Gunq7oDkurZr9zUev2n",
          "5CcHdjf6sPcEkTmXFzF2CfH7MFrVHyY5PZtSm1eZsxgsj1KC"
        ],    
        "createdAt": "2023-08-15T15:07:54.795Z"
      }
    }
    
    • unsignedTransactionunsigned 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 transferable balance (not compounding rewards).
      • controller — rewards will be sent to the controller account.
      • account — rewards will be sent to any account you specify as a transferable balance.
    • rewardDestination — rewards destination account address.

    • amount — amount of tokens to bond. AVAIL is used for the mainnet network.

    • targets — selected validators in the targets.

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

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

2. 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/avail/{network}/account/add.

    Example request (for mainnet network):

    curl --request POST \
         --url https://api.p2p.org/api/v1/avail/mainnet/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 Avail network.

Staking via a nomination pool

1. Create Bond Request

  1. Create a bond request by sending a POST request to /api/v1/avail/{network}/staking/pool/bond. The P2P.org pool ID on the Avail mainnet is 23.

    Example request (for mainnet network):

    curl --request POST \
      --url https://api.p2p.org/api/v1/avail/mainnet/staking/pool/bond \
      --header 'accept: application/json' \
      --header 'authorization: Bearer <token>' \
      --header 'content-type: application/json' \
      --data '
    {
    "stashAccountAddress": "5H6ryBWChC5w7eaQ4GZjo329sEnhvjetSr6MBEt42mZ5tPw5",
    "poolId": 23,
    "amount": 100
    }'
    
    • stashAccountAddress — main stash account address which keeps tokens for bonding.

    • poolId — ID of the nomination pool.

    • amount — amount of tokens to bond. AVAIL is used for the mainnet network.

    Example response:

    {
    "result": {
     "unsignedTransaction": "0xac0406000b00487835a302032c6eca5cdaa3e87d7f8e06d10015bf0508b52d301c8991af113d5cf49a53553f",
     "amount": 100,
     "createdAt": "2023-08-15T15:07:54.795Z"
    }
    }
    
    • unsignedTransactionunsigned transaction in hex format. Sign the transaction and submit it to the blockchain to perform the called action.

    • amount — amount of tokens to bond. AVAIL is used for the mainnet network.

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

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

2. Create Set Permission Request

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

    Example request (for mainnet network):

    curl --request POST \
      --url https://api.p2p.org/api/v1/avail/mainnet/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": {}
    }
    
  • unsignedTransactionunsigned 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 Avail 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 a claim payout request:

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

    Example request (for mainnet network):

    curl --request POST \
         --url https://api.p2p.org/api/v1/avail/mainnet/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 Avail network.

What's Next?