Polygon API User Journey
In this section you will find a typical user journey for Polygon Staking Integration API:
Endpoint: POST Create a New Bootstrapping Intent
The Bootstrapping endpoint is used to prepare a user’s wallet for participating in Polygon’s delegation program. It returns an unsigned transaction that sets up the user’s wallet for delegation and should only signed and sent once, the very first time the user is going to delegate. If this step is not completed, any subsequent delegation transactions will fail.
Endpoint: POST Create a New Stake Intent
The Stake Intent endpoint generates an unsigned transaction that transfers a designated amount of Matic tokens from a user’s wallet to Polygon’s staking program.
3. Withdrawing Rewards
After earning a sufficient amount of rewards (more than 1 Matic), a user may choose to withdraw their earnings. This operation only withdraws the rewards, not the stake. The stake remains in the system and will continue to earn rewards in the future. No specific amount is passed to the Polygon contract; it always sends the entire reward.
4. Restaking Rewards
Endpoint: POST Create a New Rewards Restake Intent
After earning a sufficient amount of rewards (more than 1 Matic), a user may choose to restake — withdraw their earnings and delegate them to the same validator. The platform allows users to combine these two operations into a single transaction. No specific amount is passed to the Polygon contract; it always restakes the entire reward.
5. Unbonding and Unstaking
- POST Create a New Deactivation Intent
- GET Get Deactivation Intents
- POST Create a New Withdrawal Intent
Step 1. The user first needs to create a new unbond intent with POST Create a New Deactivation Intent. This endpoint returns an unsigned transaction that needs to be signed and sent.
After unbonding, Polygon does not release 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. A checkpoint typically takes between 15 minutes and 2 hours, depending on Polygon’s workload.
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. The user waits for 80 checkpoints, which typically takes around 2-3 days. During this time, the user can call GET Get Deactivation Intents as many times as they want to find out the following details:
- how many ongoing unbonding requests there are
- IDs of these requests (nonces)
- how many checkpoints each unboding request still has to wait for
Step 3. Once the withdrawal period is over, user calls POST Create a New Withdrawal Intent and receives an unsigned transaction. After signing and sending it, the staked MATIC tokens are transferred back to the user.
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.