> ## Documentation Index
> Fetch the complete documentation index at: https://docs.p2p.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Polkadot

> Unified API + Polkadot Integration Workflow

In the following guide, the integration process for the `polkadot` chain is covered. The Polkadot integration aligns with the general [Unified API process](/docs/unified-api-getting-started) but with network-specific parameters.

[Get an authentication token](/docs/authentication) to start using the Unified API.

Request examples are provided using [cURL](https://curl.se/).

> To check the integration guides for other chains, refer to the [Networks Supported](/docs/unified-api-networks) section.

<Note>
  **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.
</Note>

## Staking flow

### 1. Create bonding request

Send a POST request to [/api/v1/unified/staking/stake](/reference/unified-create-stake-transaction).

Example request (for `westend` network):

<CodeGroup>
  ```bash bash theme={null}
  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"
  }'
  ```
</CodeGroup>

* `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.
* `extraData` — additional parameters:
  * `stashAccountAddress` — not needed for this step. required only for step (2) nomination request.

Example response:

<CodeGroup>
  ```json JSON theme={null}
  {
      "error": null,
      "result": {
          "amount": 1,
          "createdAt": "2025-03-07T07:10:20.966Z",
          "extraData": {
              "unsignedTransaction": "0xa8040600070010a5d4e8037427a7dee592c47c6875266357ee7afd763ddfdf6bd1634e410b7335fc38331e",
              "stashAccountAddress": "5Eh1C69jwNgBPtp2oKxJ7Zy5dS6LJn3XZ6CJHPwcAB2iFpZQ",
              "rewardDestinationType": "account",
              "rewardDestination": "5Eh1C69jwNgBPtp2oKxJ7Zy5dS6LJn3XZ6CJHPwcAB2iFpZQ"
          }
      }
  }
  ```
</CodeGroup>

* `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 <Tooltip tip="On Polkadot and Avail, this is an account that holds funds bonded for staking, but delegates all staking functions to a staking proxy account. You may actively participate in staking with a stash private key kept in a cold wallet like Ledger, meaning it stays offline all the time. Having a staking proxy will allow you to sign all staking-related transactions with the proxy instead of using your Ledger device. This will allow you to avoid carrying around your Ledger device just to sign staking-related transactions, and to keep the transaction history of your stash clean.">stash account</Tooltip> address which keeps tokens for bonding.

  * `rewardDestinationType` — type of receiving the rewards:

    * `staked` — rewards will be sent to the <Tooltip tip="On Polkadot and Avail, this is an account that holds funds bonded for staking, but delegates all staking functions to a staking proxy account. You may actively participate in staking with a stash private key kept in a cold wallet like Ledger, meaning it stays offline all the time. Having a staking proxy will allow you to sign all staking-related transactions with the proxy instead of using your Ledger device. This will allow you to avoid carrying around your Ledger device just to sign staking-related transactions, and to keep the transaction history of your stash clean.">stash account</Tooltip> and added to the current bond (compounding rewards).
    * `stash` — rewards will be sent to the <Tooltip tip="On Polkadot and Avail, this is an account that holds funds bonded for staking, but delegates all staking functions to a staking proxy account. You may actively participate in staking with a stash private key kept in a cold wallet like Ledger, meaning it stays offline all the time. Having a staking proxy will allow you to sign all staking-related transactions with the proxy instead of using your Ledger device. This will allow you to avoid carrying around your Ledger device just to sign staking-related transactions, and to keep the transaction history of your stash clean.">stash account</Tooltip> as a transferrable balance (not compounding rewards).
    * `controller` — rewards will be sent to the controller account.
    * `account` — default; 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](/docs/unified-api-signing-transaction) 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](/reference/unified-transaction-send).

Example request:

<CodeGroup>
  ```bash bash theme={null}
  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"
  }'
  ```
</CodeGroup>

* `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:

<CodeGroup>
  ```json JSON theme={null}
  {
      "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"
          }
      }
  }
  ```
</CodeGroup>

* `status` — transaction status: `pending`, `success` or `failed`.

* `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 <Tooltip tip="On Polkadot and Avail, a SCALE encoded array consisting of a version number, signature, and varying data types indicating the resulting runtime function to be called, including the parameters required for that function to be executed. These state changes are invoked from the outside world, i.e., they are not part of the system itself. Extrinsics can take two forms, “inherents” and “transactions”.">extrinsic</Tooltip> identifier.

  * `transactionHash` — signed transaction in the hexadecimal format.

  * `signerAccount` — account that signed the transaction.

  * `data` is the list of data fields to be used to construct the bonding transaction.

    * `args.value` — amount of tokens to bond.

    * `args.payee` — 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 transferable balance (not compounding rewards).
      * `controller` — rewards will be sent to the controller account.
      * `account` — default; rewards will be sent to any account specified as a transferrable balance.
        * `args.payee.Account` — account address initiated the bonding transaction.

    * `method` — operation type.

    * `section` — endpoint section type. `createdAt` — timestamp of the transaction in the ISO 8601 format.

### 3. Create nomination request

<Warning>
  **Note: Accessing High-APR Nodes**

  To benefit from P2P.org’s high-APR validators on Polkadot (DOT), you must attach the **P2P.org proxy** to your account. These private validators require explicit approval and cannot be nominated via standard methods. Ensure the proxy is attached during your integration flow to unlock the enhanced staking rewards.

  Contact our [team](/docs/contacts) for dedicated assistance.
</Warning>

Send a POST request to [/api/v1/unified/staking/stake](/reference/unified-create-stake-transaction).

Example request (for `westend` network):

<CodeGroup>
  ```bash bash theme={null}
  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"
      }
  }'
  ```
</CodeGroup>

* `chain` — blockchain network.
* `network` — environment in which the transaction is processed.
* `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 parameters:
  * `stashAccountAddress` — main stash account address which keeps tokens for bonding.

Example response:

<CodeGroup>
  ```json JSON theme={null}
  {
      "error": null,
      "result": {
          "createdAt": "2025-03-07T03:59:22.666Z",
          "extraData": {
              "unsignedTransaction": "0x19010406050800be5ddb1579b72e84524fc29e78609e3caf42e85aa118ebfe0b0ad404b5bdd25f00fe65717dad0447d715f660a0a58411de509b42e6efb8375f562f58a554d5860e",
              "stashAccountAddress": "5Eh1C69jwNgBPtp2oKxJ7Zy5dS6LJn3XZ6CJHPwcAB2iFpZQ",
              "targets": [
                  "5GNJqTPyNqANBkUVMN1LPPrxXnFouWXoe2wNSmmEoLctxiZY",
                  "5HpG9w8EBLe5XCrbczpwq5TSXvedjrBGCwqxK1iQ7qUsSWFc"
              ]
          }
      }
  }
  ```
</CodeGroup>

* `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](https://polkadot.js.org/apps/#/staking/targets).

### 4. Sign and send transaction

Use `unsignedTransactionData` to [sign and send](/docs/unified-api-signing-transaction) the transaction following the Polkadot-specific signing logic.

## Unstaking flow

### 1. Create unbonding request

Send a POST request to [/api/v1/unified/staking/unstake](/reference/unified-create-unstake-transaction).

Example request (for `westend` network):

<CodeGroup>
  ```bash bash theme={null}
  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
      }
  }'
  ```
</CodeGroup>

* `chain` — blockchain network.
* `network` — environment in which the transaction is processed.
* `stakerAddress` — account address initiated the bonding transaction.
* `extra` — additional parameters:
  * `amount` — amount of tokens to unbond. DOT for mainnet, KSM for Kusama and WND for Westend.

Example response:

<CodeGroup>
  ```json JSON theme={null}
  {
      "error": null,
      "result": {
          "createdAt": "2025-03-07T04:02:18.033Z",
          "extraData": {
              "unsignedTransaction": "0x24040602070010a5d4e8",
              "stashAccountAddress": "5Eh1C69jwNgBPtp2oKxJ7Zy5dS6LJn3XZ6CJHPwcAB2iFpZQ",
              "amount": 1
          }
      }
  }
  ```
</CodeGroup>

* `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](/docs/unified-api-signing-transaction) the transaction following the Polkadot-specific signing logic.

### 3. Create withdrawal request

<Note>
  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.
</Note>

Send a POST request to [/api/v1/unified/staking/withdraw](/reference/unified-create-withdraw-transaction).

Example request (for `westend` network):

<CodeGroup>
  ```bash bash theme={null}
  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"
  }'
  ```
</CodeGroup>

* `chain` — blockchain network.
* `network` — environment in which the transaction is processed.
* `stakerAddress` — account address initiated the unbonding transaction.

Example response:

<CodeGroup>
  ```json JSON theme={null}
  {
      "error": null,
      "result": {
          "stakerAddress": "5Eh1C69jwNgBPtp2oKxJ7Zy5dS6LJn3XZ6CJHPwcAB2iFpZQ",
          "unsignedTransactionData": "0x1c04060300000000",
          "createdAt": "2025-03-07T04:30:47.854Z",
          "extraData": {}
      }
  }
  ```
</CodeGroup>

* `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](/docs/unified-api-signing-transaction) the transaction following the Polkadot-specific signing logic.


## Related topics

- [Unified API Reference](/reference/unified-create-stake-transaction.md)
- [Integration Workflow Example](/docs/unified-api-getting-started.md)
- [Networks Supported](/docs/unified-api-networks.md)