Skip to main content

Polkadot-JS Guides For Nominators


Polkadot-JS is for developers and power users only. If you need help using the Polkadot-JS UI, you can contact the Polkadot Support Team. For more user-friendly tools see the wallets, apps and dashboard pages.

See this page to learn about staking.

Nominate Using Polkadot-JS

Bond your tokens

Support Article

Read the support article about How to Bond Tokens and Nominate.

On the Polkadot-JS UI navigate to the "Staking" tab (within the "Network" menu).

The "Staking Overview" subsection will show you all the active validators and their information - their identities, the amount of KSM that are staking for them, amount that is their own provided stake, how much they charge in commission, the era points they've earned in the current era, and the last block number that they produced. If you click on the chart button it will take you to the "Validator Stats" page for that validator that shows you more detailed and historical information about the validator's stake, rewards and slashes.

The "Account actions" subsection (link) allows you to stake and nominate.

The "Payouts" subsection (link) allows you to claim rewards from staking.

The "Targets" subsection (link) will help you estimate your earnings and this is where it's good to start picking favorites.

The "Waiting" subsection (link) lists all pending validators that are awaiting more nominations to enter the active validator set. Validators will stay in the waiting queue until they have enough KSM backing them (as allocated through the Phragmén election mechanism). It is possible validator can remain in the queue for a very long time if they never get enough backing.

The "Validator Stats" subsection (link) allows you to query a validator's stash address and see historical charts on era points, elected stake, rewards, and slashes.

Pick "Account actions" underneath "Network" > "Staking", then click the "+ Nominator" button.

You will see a modal window that looks like the below:

nominator-update-1

Select a "value bonded" that is less than the total amount of KSM you have, so you have some left over to pay transaction fees. Transaction fees are currently at least 0.01 KSM, but they are dynamic based on a variety of factors including the load of recent blocks.

Also be mindful of the reaping threshold - the amount that must remain in an account lest it be burned. That amount is 0.01 in Kusama, so it's recommended to keep at least 0.1 KSM in your account to be on the safe side.

Choose whatever payment destination that makes sense to you. If you're unsure, you can choose "Stash account (increase amount at stake)" to simply accrue the rewards into the amount you're staking and earn compound interest.

Payout account selection dropdown with the custom account option highlighted

Nominate a validator

Support Article

Read the support article about How to Select Validators.

You are now bonded. Being bonded means your tokens are locked and could be slashed if the validators you nominate misbehave. All bonded funds can now be distributed to up to 24 validators. Be careful about the validators you choose since you will be slashed if your validator commits an offence.

Click on "Nominate" on an account you've bonded and you will be presented with another popup asking you to select some validators.

Nominating validators

Select them, confirm the transaction, and you're done - you are now nominating. Your nominations will become active in the next era. Eras last six hours on Kusama - depending on when you do this, your nominations may become active almost immediately, or you may have to wait almost the entire six hours before your nominations are active. You can check how far along Kusama is in the current era on the Staking page.

Assuming at least one of your nominations ends up in the active validator set, you will start to get rewards allocated to you. In order to claim them (i.e., add them to your account), you must manually claim them. To initiate a claim, you can do it yourself or have the validator that you staked for initiate a claim. This is to help optimize the effectiveness and storage of payouts on Kusama. See the Claiming Rewards section of the Staking wiki page for more details.

Stop nominating

Support Article

Read the support article about How to Stop Nominating & Unbond Tokens. See also the support article about How to Rebond Tokens.

At some point, you might decide to stop nominating one or more validators. You can always change who you're nominating, but you cannot withdraw your tokens unless you unbond them.

Claiming Rewards with Polkadot-JS

Anyone can trigger a payout for any validator, as long as they are willing to pay the transaction fee. Someone must submit a transaction with a validator ID and an era index. Kusama will automatically calculate that validator's reward, find the top nominators for that era, and distribute the rewards pro rata.

note

The Staking system only applies the highest nominations to each validator to reduce the complexity of the staking set.

These details are handled for you automatically if you use the Polkadot-JS UI, which also allows you to submit batches of eras at once.

To claim rewards on Polkadot-JS UI, you will need to be in the "Payouts" tab underneath "Staking", which will list all the pending payouts for your stashes.

pending-payouts

To then claim your reward, select the "Payout all" button. This will prompt you to select your stash accounts for payout.

select-payouts

Once you are done with payout, another screen will appear asking for you to sign and submit the transaction.

transaction-payouts

Using Command-Line Interface (CLI)

Apart from using the Polkadot-JS UI to participate in the staking, you can do all these things in CLI instead. The CLI approach allows you to interact with the Kusama network without using Polkadot-JS.

Step 1: Install @polkadot/api-cli

We assume you have installed NodeJS with npm. Run the following command to install the @polkadot/api-cli globally:

npm install -g @polkadot/api-cli

Step 2: Bond Tokens

Controller accounts are deprecated

Controller accounts are deprecated. For more information, see this discussion.

Executing the following command:

polkadot-js-api --seed "MNEMONIC_PHRASE" tx.staking.bond CONTROLLER_ADDRESS NUMBER_OF_TOKENS REWARD_DESTINATION --ws WEBSOCKET_ENDPOINT

CONTROLLER_ADDRESS: An address you would like to bond to the stash account. (Controller accounts are now deprecated. Refer to this discussion for additional context)

NUMBER_OF_TOKENS: The number of KSM you would like to stake to the network. KSM has twelve decimal places and is always represented as an integer with zeroes at the end. So 1 KSM = 1_000_000_000_000 Plancks. For more information, see this page.

REWARD_DESTINATION:

  • Staked - Pay into the stash account, increasing the amount at stake accordingly.
  • Stash - Pay into the stash account, not increasing the amount at stake.
  • Account - Pay into a custom account, like so: Account DMTHrNcmA8QbqRS4rBq8LXn8ipyczFoNMb1X4cY2WD9tdBX.
  • Controller - Pay into the controller account.

Example for Kusama:

polkadot-js-api --seed "xxxx xxxxx xxxx xxxxx" tx.staking.bond DMTHrNcmA8QbqRS4rBq8LXn8ipyczFoNMb1X4cY2WD9tdBX 1000000000000 Staked --ws wss://kusama-rpc.polkadot.io

For wss endpoints see this page.

Result:

...
...
"status": {
"InBlock": "0x0ed1ec0ba69564e8f98958d69f826adef895b5617366a32a3aa384290e98514e"
}

You can check the transaction status by using the value of the InBlock in Subscan. Also, you can verify the bonding state under the Staking page on the Polkadot-JS UI.

Step 3: Nominate a validator

To nominate a validator, you can execute the following command:

polkadot-js-api --seed "MNEMONIC_PHRASE" tx.staking.nominate '["VALIDATOR_ADDRESS"]' --ws WS_ENDPOINT
polkadot-js-api --seed "xxxx xxxxx xxxx xxxxx" tx.staking.nominate '["CmD9vaMYoiKe7HiFnfkftwvhKbxN9bhyjcDrfFRGbifJEG8","E457XaKbj2yTB2URy8N4UuzmyuFRkcdxYs67UvSgVr7HyFb"]' --ws wss://kusama-rpc.polkadot.io

After a few seconds, you should see the hash of the transaction, and if you would like to verify the nomination status, you can check that on the Polkadot-JS UI as well.