Documentation
Documentation

Polkadot

Unified API + Polkadot Integration Workflow

Suggest Edits

In the following guide, the integration process for the polkadot chain is covered. The Polkadot integration aligns with the general Unified API process but with network-specific parameters.

Get an authentication token to start using the Unified API.

Request examples are provided using cURL.

To check the integration guides for other chains, refer to the Networks section.

📘

Key Polkadot-specific details

  • chain — always set to polkadot for Polkadot-related requests.
  • network — environment in which the transaction is processed (kusama ,westend or mainnet).
  • stakerAddress — account address initiating staking, unstaking or withdrawal transactions.
  • amount — amount of tokens for bond operations. DOT is used for the main network, KSM for Kusama, and WND for Westend.

Staking Flow

1. Create Bond Request

Send a POST request to /api/v1/unified/staking/stake.

Example request (for westend network):

curl --request POST \
     --url https://api-test.p2p.org/api/v1/unified/staking/stake \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <token>' \
     --data '{
    "chain": "polkadot",
    "network": "westend",
    "stakerAddress": "5Eh1C69jwNgBPtp2oKxJ7Zy5dS6LJn3XZ6CJHPwcAB2iFpZQ",
    "amount": "1"
}'
  • chain — blockchain network, always set to polkadot for Polkadot-related requests.
  • network — environment in which the transaction is processed (kusama , westend or mainnet).
  • stakerAddress — account address initiating the bonding transaction.
  • amount — amount of tokens to bond. DOT is used for the main network, KSM for Kusama, and WND for Westend.

Example response:

{
    "error": null,
    "result": {
        "amount": 1,
        "createdAt": "2025-03-07T07:10:20.966Z",
        "extraData": {
            "unsignedTransaction": "0xa8040600070010a5d4e8037427a7dee592c47c6875266357ee7afd763ddfdf6bd1634e410b7335fc38331e",
            "stashAccountAddress": "5Eh1C69jwNgBPtp2oKxJ7Zy5dS6LJn3XZ6CJHPwcAB2iFpZQ",
            "rewardDestinationType": "account",
            "rewardDestination": "5Eh1C69jwNgBPtp2oKxJ7Zy5dS6LJn3XZ6CJHPwcAB2iFpZQ"
        }
    }
}
  • 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.
  • extraData — additional transaction details:
    • unsignedTransactionData — unsigned transaction in Base64 encrypted 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 — type of receiving the rewards:
      • staked — rewards will be sent to the stash account and added to the current bond (compounding rewards).
      • stash — rewards will be sent to the stash account as a transferrable balance (not compounding rewards).
      • account — rewards will be sent to any account specified as a transferrable balance.
    • rewardDestination — rewards destination account address.

2. Sign and Send Transaction

Use unsignedTransactionData to sign the transaction using the Polkadot-specific signing logic.

To broadcast the signed transaction to the Polkadot network, send a POST request to /api/v1/unified/transaction/broadcast.

Example request:

curl --request POST \
     --url https://api-test.p2p.org/api/v1/unified/transaction/broadcast \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <token>' \
     --data '{
    "chain": "polkadot",
    "network": "westend",
    "stakerAddress": "5Eh1C69jwNgBPtp2oKxJ7Zy5dS6LJn3XZ6CJHPwcAB2iFpZQ",
    "signedTransaction":    "0x410284007427a7dee592c47c6875266357ee7afd763ddfdf6bd1634e410b7335fc38331e01f214ddb36378b5f5927b06028eccfe284d9cb736f8552e301cc09c2006998b098f84bf6386a201aa952fe298dd5f0c5fb6f03fc7b9f7efafd87b6ee321500b8e450340000600070010a5d4e8037427a7dee592c47c6875266357ee7afd763ddfdf6bd1634e410b7335fc38331e"
}'
  • chain — blockchain network.
  • network — environment in which the transaction is processed.
  • stakerAddress — account address initiating the bonding transaction.
  • signedTransaction — signed transaction in Base64 encrypted format, which contains all transaction details (e.g., accounts, instructions, and signatures) required to broadcast the transaction to the network.

Example response:

{
    "error": null,
    "result": {
        "status": "success",
        "extraData": {
            "network": "westend",
            "signedTransaction": "0x450284007427a7dee592c47c6875266357ee7afd763ddfdf6bd1634e410b7335fc38331e011c38a0ce7dad52c9500843dddb52645bc790891c61963a454dcb79cbc3e0545fcc64d1fcbebea0769392248dc3d34e60568452ebbe44bd0f876ecae73a8eae8915012000000600070010a5d4e8037427a7dee592c47c6875266357ee7afd763ddfdf6bd1634e410b7335fc38331e",
            "blockHash": "0x5cffd50711d3de0a896687ce2939313dd00491edc820d3abeaefe6a997be3a4f",
            "blockId": 25052458,
            "extrinsicId": 2,
            "transactionHash": "0xb5546fbfb7221c358d8e593cc094430a884a9f41b765003674b59aaf16d0f5f2",
            "signerAccount": "5Eh1C69jwNgBPtp2oKxJ7Zy5dS6LJn3XZ6CJHPwcAB2iFpZQ",
            "data": {
                "args": {
                    "value": "1,000,000,000,000",
                    "payee": {
                        "Account": "5Eh1C69jwNgBPtp2oKxJ7Zy5dS6LJn3XZ6CJHPwcAB2iFpZQ"
                    }
                },
                "method": "bond",
                "section": "staking"
            },
            "createdAt": "2025-03-07T03:57:30.386Z"
        }
    }
}
  • status — transaction status.
  • extraData — additional transaction details:
    • network — environment in which the transaction is processed.
    • signedTransaction — signed transaction in Base64 encrypted format, which contains all transaction details (e.g., accounts, instructions, and signatures) required to broadcast the transaction to the network.
    • blockHash — block hash in which the transaction has been included.
    • blockId — unique block identifier.
    • extrinsicId — unique extrinsic identifier.
    • transactionHash — signed transaction in the hexadecimal format.
    • signerAccount — account that signed the transaction.
    • data —
    • createdAt — timestamp of the transaction in the ISO 8601 format.

3. Create Nomination Request

Send a POST request to /api/v1/unified/staking/stake.

Example request:

curl --request POST \
     --url https://api-test.p2p.org/api/v1/unified/staking/stake \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <token>' \
     --data '{
    "chain": "polkadot",
    "network": "westend",
    "stakerAddress": "5Eh1C69jwNgBPtp2oKxJ7Zy5dS6LJn3XZ6CJHPwcAB2iFpZQ",
    "amount": "1",
    "extra": {
      "stashAccountAddress": "5Eh1C69jwNgBPtp2oKxJ7Zy5dS6LJn3XZ6CJHPwcAB2iFpZQ"
    }
}'
  • chain — blockchain network, always set to polkadot for Polkadot-related requests.
  • network — environment in which the transaction is processed (kusama , westend or mainnet).
  • stakerAddress — account address initiated the bonding transaction.
  • amount — amount of tokens to bond. DOT is used for the main network, KSM for Kusama, and WND for Westend.
  • extraData — additional request parameters:
    • stashAccountAddress — main stash account address which keeps tokens for bonding.

Example response:

{
    "error": null,
    "result": {
        "createdAt": "2025-03-07T03:59:22.666Z",
        "extraData": {
            "unsignedTransaction": "0x19010406050800be5ddb1579b72e84524fc29e78609e3caf42e85aa118ebfe0b0ad404b5bdd25f00fe65717dad0447d715f660a0a58411de509b42e6efb8375f562f58a554d5860e",
            "stashAccountAddress": "5Eh1C69jwNgBPtp2oKxJ7Zy5dS6LJn3XZ6CJHPwcAB2iFpZQ",
            "targets": [
                "5GNJqTPyNqANBkUVMN1LPPrxXnFouWXoe2wNSmmEoLctxiZY",
                "5HpG9w8EBLe5XCrbczpwq5TSXvedjrBGCwqxK1iQ7qUsSWFc"
            ]
        }
    }
}
  • createdAt — timestamp of the transaction in the ISO 8601 format.
  • extraData — additional transaction details:
    • unsignedTransactionData — unsigned transaction in Base64 encrypted 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 — validators selected in the targets.

4. Sign and Send Transaction

Use unsignedTransactionData to sign and send the transaction following the Polkadot-specific signing logic.

Unstaking Flow

1. Create Unstaking Request

Send a POST request to /api/v1/unified/staking/unstake.

Example request:

curl --request POST \
     --url https://api-test.p2p.org/api/v1/unified/staking/unstake \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <token>' \
     --data '{
    "chain": "polkadot",
    "network": "westend",
    "stakerAddress": "5Eh1C69jwNgBPtp2oKxJ7Zy5dS6LJn3XZ6CJHPwcAB2iFpZQ"
    "extra": {
      "amount": 1
    }
}'
  • chain — blockchain network.
  • network — environment in which the transaction is processed.
  • stakerAddress — account address initiated the bonding transaction.
  • extra — additional request parameters:
    • amount — amount of tokens to unbond. DOT is used for the main network, KSM for Kusama, and WND for Westend.

Example response:

{
    "error": null,
    "result": {
        "createdAt": "2025-03-07T04:02:18.033Z",
        "extraData": {
            "unsignedTransaction": "0x24040602070010a5d4e8",
            "stashAccountAddress": "5Eh1C69jwNgBPtp2oKxJ7Zy5dS6LJn3XZ6CJHPwcAB2iFpZQ",
            "amount": 1
        }
    }
}
  • createdAt — timestamp of the transaction in the ISO 8601 format.
  • extraData — additional transaction details:
    • unsignedTransactionData — unsigned transaction in Base64 encrypted 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.
    • amount — amount of tokens to unbond. DOT is used for the main network, KSM for Kusama, and WND for Westend.

2. Sign and Send Transaction

Use unsignedTransactionData to sign and send the transaction following the Polkadot-specific signing logic.

3. Create Withdrawal Request

📘

Note that the withdrawal is available only after the unbonding period. It takes 7 days (28 eras) to unbond on Kusama, 28 days (28 eras) on Polkadot, and 12 hours (2 eras) on Westend.

Send a POST request to /api/v1/unified/staking/withdraw.

Example request:

curl --request POST \
     --url https://api-test.p2p.org/api/v1/unified/staking/withdraw \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <token>' \
     --data '{
    "chain": "polkadot",
    "network": "westend",
    "stakerAddress": "5Eh1C69jwNgBPtp2oKxJ7Zy5dS6LJn3XZ6CJHPwcAB2iFpZQ"
}'
  • chain — blockchain network.
  • network — environment in which the transaction is processed.
  • stakerAddress — account address initiated the unbonding transaction.

Example response:

{
    "error": null,
    "result": {
        "stakerAddress": "5Eh1C69jwNgBPtp2oKxJ7Zy5dS6LJn3XZ6CJHPwcAB2iFpZQ",
        "unsignedTransactionData": "0x1c04060300000000",
        "createdAt": "2025-03-07T04:30:47.854Z",
        "extraData": {}
    }
}
  • stakerAddress — account address initiating the withdrawal transaction.
  • unsignedTransactionData — unsigned transaction in Base64 encrypted 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.
  • extraData — additional transaction details.

4. Sign and Send Transaction

Use unsignedTransactionData to sign and send the transaction following the Polkadot-specific signing logic.

What's Next?

Updated 2 days ago