Typical user journeys when interacting with the Polygon Staking API
How to Bootstrap
Use the Post Bootstrapping Intent endpoint to prepare a user’s wallet for Polygon’s delegation program.
This endpoint returns an unsigned transaction configuring the user’s wallet for delegation, necessitating a single signing and sending, specifically when the user is delegating for the first time. Failing to complete this step results in the failure of subsequent delegation transactions.
How to Delegate
The Post Stake Intent endpoint generates an unsigned transaction transferring designated Matic tokens from your wallet to Polygon's staking program.
How to Withdraw Rewards
After receiving sufficient rewards (over 1 Matic), you can opt to withdraw them using the Post Rewards Withdrawal Intent endpoint. This operation solely withdraws rewards, leaving your stake untouched for future rewards. The entire reward is sent to the Polygon contract; no specific amount is passed.
How to Restake Rewards
After receiving sufficient rewards (over 1 Matic), you can choose to restake using the Post Rewards Restake Intent endpoint
This withdraws received rewards and delegates them to the same validator. Our platform streamlines these two operations into a single transaction. Like withdrawal, the entire reward is restaked; no specific amount is passed.
How to Unbond and Unstake
➡️ Step 1
Create a new unbond intent with POST Deactivation Intent. This endpoint returns an unsigned transaction that needs to be signed and sent.
After unbonding, Polygon does not release the validator’s funds immediately. If it did, validators could cheat the system by withdrawing their stake right after unbonding to avoid being slashed. This is why there’s a withdrawal period of 80 checkpoints. Depending on Polygon's workload, a checkpoint typically takes between 15 minutes and 2 hours.
Delegator funds are treated the same way as validators’ funds. If a validator is slashed, all of its delegators will be slashed proportionally. Similarly, if a delegator wants to withdraw their delegated stake from a validator, they must also wait for 80 checkpoints.
➡️ Step 2
Wait for around 80 checkpoints, which typically takes 2-3 days. During this time, you can call the GET Lists Deactivation Intents endpoint as many times as you want to find out the following details:
- How many ongoing unbonding requests are there?
- IDs of these requests (nonces).
- How many checkpoints each unbonding request still has to wait for?
➡️ Step 3
Once the withdrawal period is over, call the POST Withdrawal Intent endpoint and receive an unsigned transaction. After signing and sending it, the staked MATIC tokens are transferred back to you.
Unbond transactions must match corresponding unstake transactions on a one-to-one basis. There cannot be a successful unstake without a successful unbond preceding it.
Example Code
👋 Need Help?
Contact us through email or our support page for any issues, bugs, or assistance you may need.