> ## 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.

# Getting Started

> Stake on TRON programmatically with the P2P.org Staking API.

Staking on the TRON network using the Staking API consists of the following main steps:

1. Create a delegate request: freeze tokens to gain voting power.
2. Create a voting request to vote for the Super Representatives.

After each step, sign and broadcast the transaction to the TRON network.

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

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

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant P2P API
    participant TRON
    Client->>P2P API: Create freeze (delegate) transaction
    P2P API-->>Client: Unsigned freeze transaction
    Client->>Client: Sign transaction locally
    Client->>TRON: Broadcast freeze transaction
    TRON-->>Client: Freeze confirmed
    Client->>P2P API: Create vote transaction
    P2P API-->>Client: Unsigned vote transaction
    Client->>Client: Sign transaction locally
    Client->>TRON: Broadcast vote transaction
    TRON-->>Client: Vote confirmed
```

<Steps>
  <Step title="Create delegate request">
    To freeze tokens, send a POST request to [/api/v1/tron/\{network}/staking/delegate](/reference/tron-staking-delegate).

    Example request (for `testnet-nile` network):

    <CodeGroup>
      ```bash curl theme={null}
      curl --request POST \
        --url 'https://api-test.p2p.org/api/v1/tron/testnet-nile/staking/delegate' \
        --header 'accept: application/json' \
        --header 'Authorization: Bearer <token>' \
        --header 'Content-Type: application/json' \
        --data '{
          "delegatorAddress": "TVscj8F6wPZ92d1smGYjH9heZR1MaEcE9u",
          "amount": 1000000,
          "resource": "BANDWIDTH"
      }'
      ```

      ```typescript TypeScript theme={null}
      const response = await fetch(
        "https://api-test.p2p.org/api/v1/tron/testnet-nile/staking/delegate",
        {
          method: "POST",
          headers: {
            "accept": "application/json",
            "Authorization": "Bearer <token>",
            "Content-Type": "application/json",
          },
          body: JSON.stringify({
            delegatorAddress: "TVscj8F6wPZ92d1smGYjH9heZR1MaEcE9u",
            amount: 1000000,
            resource: "BANDWIDTH",
          }),
        }
      );
      const data = await response.json();
      console.log(data);
      ```

      ```python Python theme={null}
      import requests

      response = requests.post(
          "https://api-test.p2p.org/api/v1/tron/testnet-nile/staking/delegate",
          headers={
              "accept": "application/json",
              "Authorization": "Bearer <token>",
              "Content-Type": "application/json",
          },
          json={
              "delegatorAddress": "TVscj8F6wPZ92d1smGYjH9heZR1MaEcE9u",
              "amount": 1000000,
              "resource": "BANDWIDTH",
          },
      )
      print(response.json())
      ```

      ```go Go theme={null}
      package main

      import (
      	"bytes"
      	"encoding/json"
      	"fmt"
      	"io"
      	"net/http"
      )

      func main() {
      	payload := map[string]interface{}{
      		"delegatorAddress": "TVscj8F6wPZ92d1smGYjH9heZR1MaEcE9u",
      		"amount":           1000000,
      		"resource":         "BANDWIDTH",
      	}
      	body, _ := json.Marshal(payload)
      	req, _ := http.NewRequest("POST", "https://api-test.p2p.org/api/v1/tron/testnet-nile/staking/delegate", bytes.NewBuffer(body))
      	req.Header.Set("accept", "application/json")
      	req.Header.Set("Authorization", "Bearer <token>")
      	req.Header.Set("Content-Type", "application/json")
      	resp, _ := http.DefaultClient.Do(req)
      	defer resp.Body.Close()
      	respBody, _ := io.ReadAll(resp.Body)
      	fmt.Println(string(respBody))
      }
      ```
    </CodeGroup>

    * `delegatorAddress` — delegator account address.

    * `amount` — amount of tokens to freeze in SUN (1 TRX = 10⁶ SUN). Note that only TRX (SUN) can be delegated, since USDT (TRC-20) is not natively stakeable.

    * `resource` — type of resources to be used for processing the TRON transaction:

      * `BANDWIDTH` — for regular transactions on the TRON chain.
      * `ENERGY` — for using smart contracts or running DApps.

    Example response:

    <CodeGroup>
      ```json theme={null}
      {
          "error": null,
          "result": {
            "delegatorAddress": "TVscj8F6wPZ92d1smGYjH9heZR1MaEcE9u",
            "amount": 10000000,
            "resource": "BANDWIDTH",
            "unsignedTransaction": {
              "visible": false,
              "txID": "98c15dc006cbe2f978ea2f25940703bbafecd89161f92f54eaeb82691faf34ec",
              "raw_data_hex": "0a02ba6b2208475fc5c8083be91340989888aef3325a55083612510a34747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e467265657a6542616c616e63655632436f6e747261637412190a1541700ca9ad5f162f9de000558ff04eef8f99dce7e8100170b8c384aef332",
              "raw_data": {
                "contract": [
                  {
                    "parameter": {
                      "value": {
                        "owner_address": "41700ca9ad5f162f9de000558ff04eef8f99dce7e8",
                        "frozen_balance": 1000000
                      },
                      "type_url": "type.googleapis.com/protocol.FreezeBalanceV2Contract"
                    },
                    "type": "FreezeBalanceV2Contract"
                  }
                ],
                "ref_block_bytes": "ba6b",
                "ref_block_hash": "475fc5c8083be913",
                "expiration": 1748953599000,
                "timestamp": 1748953539000
              }
            },
            "unsignedTransactionSerialized": "eyJ0eElEIjoidHJ4SWQifQ==",
            "createdAt": "2025-06-03T12:25:40.347Z",
            "voteAccount": "TH7Fe1W8CcLeqN4LGfqX1R9EpsnrJBQJji"
          }
        }
      ```
    </CodeGroup>

    * `delegatorAddress` — delegator account address.

    * `amount` — amount of tokens to freeze in SUN (1 TRX = 10⁶ SUN).

    * `resource` — type of resources used for processing the freeze transaction: `BANDWIDTH` or `ENERGY`.

    * `unsignedTransaction` — original unsigned transaction object returned by tronWeb.

      * `visible` — internal SDK parameter; always set to `false`.

      * `txID` — hash of the transaction.

      * `raw_data_hex` — raw payload of the unsigned transaction in the hexadecimal format.

      * `raw_data` — full decoded transaction structure with all the fields and metadata:

        * `contract` — list of TRON contracts:

          * `parameter.type_url` — TRON protocol contract, e.g., `type.googleapis.com/protocol.FreezeBalanceV2Contract`.
          * `parameter.value.owner_address `— TRON account address in the hexadecimal format.
          * `parameter.value.frozen_balance` — amount of tokens used for voting in SUN (1 TRX = 10⁶ SUN).

        * `ref_block_bytes`, `ref_block_hash` — hash and references of the block in which the transaction has been included.

        * `expiration` — timestamp of the transaction expiration in ms since last epoch.

        * `timestamp` — timestamp of the transaction in ms since last epoch.

    * `unsignedTransactionSerialized` — unsigned serialized transaction in Base64 encrypted format ready for signing.

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

    * `voteAccount` — address of the Super Representative for voting.
  </Step>

  <Step title="Sign and send transaction">
    Use `unsignedTransactionSerialized` to [sign and send](/docs/signing-transaction-tron) the signed transaction to the TRON network.
  </Step>

  <Step title="Create voting request">
    To vote for the P2P Super Representative using your frozen TRX, send a POST request to [/api/v1/tron/\{network}/staking/vote](/reference/tron-staking-vote).

    Example request (for `testnet-nile` network):

    <CodeGroup>
      ```bash curl theme={null}
      curl --request POST \
        --url 'https://api-test.p2p.org/api/v1/tron/testnet-nile/staking/vote' \
        --header 'accept: application/json' \
        --header 'Authorization: Bearer <token>' \
        --header 'Content-Type: application/json' \
        --data '{
          "delegatorAddress": "TVscj8F6wPZ92d1smGYjH9heZR1MaEcE9u",
          "voteCount": 3
      }'
      ```

      ```typescript TypeScript theme={null}
      const response = await fetch(
        "https://api-test.p2p.org/api/v1/tron/testnet-nile/staking/vote",
        {
          method: "POST",
          headers: {
            "accept": "application/json",
            "Authorization": "Bearer <token>",
            "Content-Type": "application/json",
          },
          body: JSON.stringify({
            delegatorAddress: "TVscj8F6wPZ92d1smGYjH9heZR1MaEcE9u",
            voteCount: 3,
          }),
        }
      );
      const data = await response.json();
      console.log(data);
      ```

      ```python Python theme={null}
      import requests

      response = requests.post(
          "https://api-test.p2p.org/api/v1/tron/testnet-nile/staking/vote",
          headers={
              "accept": "application/json",
              "Authorization": "Bearer <token>",
              "Content-Type": "application/json",
          },
          json={
              "delegatorAddress": "TVscj8F6wPZ92d1smGYjH9heZR1MaEcE9u",
              "voteCount": 3,
          },
      )
      print(response.json())
      ```

      ```go Go theme={null}
      package main

      import (
      	"bytes"
      	"encoding/json"
      	"fmt"
      	"io"
      	"net/http"
      )

      func main() {
      	payload := map[string]interface{}{
      		"delegatorAddress": "TVscj8F6wPZ92d1smGYjH9heZR1MaEcE9u",
      		"voteCount":        3,
      	}
      	body, _ := json.Marshal(payload)
      	req, _ := http.NewRequest("POST", "https://api-test.p2p.org/api/v1/tron/testnet-nile/staking/vote", bytes.NewBuffer(body))
      	req.Header.Set("accept", "application/json")
      	req.Header.Set("Authorization", "Bearer <token>")
      	req.Header.Set("Content-Type", "application/json")
      	resp, _ := http.DefaultClient.Do(req)
      	defer resp.Body.Close()
      	respBody, _ := io.ReadAll(resp.Body)
      	fmt.Println(string(respBody))
      }
      ```
    </CodeGroup>

    * `delegatorAddress` — delegator account address used for freezing tokens.
    * `voteCount` — number of votes to delegate to the default vote account; equal to the amount of frozen tokens. To delegate all available votes, specify 0.

    Example response:

    <CodeGroup>
      ```json theme={null}
      {
          "error": null,
          "result": {
            "delegatorAddress": "TVscj8F6wPZ92d1smGYjH9heZR1MaEcE9u",
            "voteAccount": "TH7Fe1W8CcLeqN4LGfqX1R9EpsnrJBQJji",
            "voteCount": 3,
            "unsignedTransaction": {
              "visible": false,
              "txID": "a9283ebb983e932d40bc1fad0a34457acd9922875a27705d76afb2fc62ceb668",
              "raw_data_hex": "0a020e0c22087db974037137d39c4090bde5ccf3325a6a080412660a30747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e566f74655769746e657373436f6e747261637412320a1541da53d324a354aa5924c7117caff3ead97910a5e112190a1541351b95e29c2514b7b8183cbc81a8e08c68e8833b100370b0e8e1ccf332",
              "raw_data": {
                "contract": [
                  {
                    "parameter": {
                      "value": {
                        "owner_address": "41da53d324a354aa5924c7117caff3ead97910a5e1",
                        "votes": [
                          {
                            "vote_address": "41351b95e29c2514b7b8183cbc81a8e08c68e8833b",
                            "vote_count": 3
                          }
                        ]
                      },
                      "type_url": "type.googleapis.com/protocol.VoteWitnessContract"
                    },
                    "type": "VoteWitnessContract"
                  }
                ],
                "ref_block_bytes": "0e0c",
                "ref_block_hash": "7db974037137d39c",
                "expiration": 1749018042000,
                "timestamp": 1749017982000
              }
            }
          },
          "unsignedTransactionSerialized": "eyJ0eElEIjoidHJ4SWQifQ==",
          "createdAt": "2025-06-04T06:19:42.228Z"
        }
      ```
    </CodeGroup>

    * `delegatorAddress` — delegator account address used for freezing tokens.

    * `voteAccount` — vote account address of the Super Representative to receive the delegation.

    * `voteCount` — number of votes delegated to the vote account.

    * `unsignedTransaction` — original unsigned transaction object returned by tronWeb.

      * `visible` — internal SDK parameter; always set to `false`.

      * `txID` — hash of the voting transaction.

      * `raw_data_hex` — raw payload of the unsigned transaction in the hexadecimal format.

      * `raw_data` — full decoded transaction structure with all the fields and metadata:

        * `contract` — list of TRON contracts:

          * `parameter.type_url` — TRON network operation type, e.g., `type.googleapis.com/protocol.VoteWitnessContract`.
          * `parameter.value.owner_address `— account address performing the vote in the hexadecimal format.
          * `parameter.value.votes` — address of the Super Representative and the number of votes.

        * `ref_block_bytes`, `ref_block_hash` — hash and references of the block in which the transaction has been included.

        * `expiration` — timestamp of the transaction expiration in ms since last epoch.

        * `timestamp` — timestamp of the transaction in ms since last epoch.

    * `unsignedTransactionSerialized` — unsigned serialized transaction in Base64 encrypted format ready for signing.

    * `createdAt` — timestamp of the transaction in the ISO 8601 format.
  </Step>

  <Step title="Sign and send transaction">
    Use `unsignedTransactionSerialized` to [sign and send](/docs/signing-transaction-tron) the signed transaction to the TRON network.
  </Step>
</Steps>

## Additional operations

### Get transaction status

To check the transaction status by its hash, send a GET request to [/api/v1/tron/\{network}/transaction/\{transactionHash}/status](/reference/tron-transaction-status).

Example request (for `testnet-nile` network):

<CodeGroup>
  ```bash curl theme={null}
  curl --request GET \
    --url 'https://api-test.p2p.org/api/v1/tron/testnet-nile/transaction/852180cff2cc870d0ff904cbf231d194e6a9d4276f309b016831bd0b1b2212d5/status' \
    --header 'accept: application/json' \
    --header 'Authorization: Bearer <token>'
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(
    "https://api-test.p2p.org/api/v1/tron/testnet-nile/transaction/852180cff2cc870d0ff904cbf231d194e6a9d4276f309b016831bd0b1b2212d5/status",
    {
      method: "GET",
      headers: {
        "accept": "application/json",
        "Authorization": "Bearer <token>",
      },
    }
  );
  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api-test.p2p.org/api/v1/tron/testnet-nile/transaction/852180cff2cc870d0ff904cbf231d194e6a9d4276f309b016831bd0b1b2212d5/status",
      headers={
          "accept": "application/json",
          "Authorization": "Bearer <token>",
      },
  )
  print(response.json())
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"io"
  	"net/http"
  )

  func main() {
  	req, _ := http.NewRequest("GET", "https://api-test.p2p.org/api/v1/tron/testnet-nile/transaction/852180cff2cc870d0ff904cbf231d194e6a9d4276f309b016831bd0b1b2212d5/status", nil)
  	req.Header.Set("accept", "application/json")
  	req.Header.Set("Authorization", "Bearer <token>")
  	resp, _ := http.DefaultClient.Do(req)
  	defer resp.Body.Close()
  	respBody, _ := io.ReadAll(resp.Body)
  	fmt.Println(string(respBody))
  }
  ```
</CodeGroup>

* `transactionHash` — hash of the transaction.

Example response:

<CodeGroup>
  ```json theme={null}
  {
      "error": null,
      "result": {
        "transactionHash": "852180cff2cc870d0ff904cbf231d194e6a9d4276f309b016831bd0b1b2212d5",
        "status": "CONFIRMED",
        "confirmed": true,
        "block": 72835612,
        "energyUsed": 15800,
        "createdAt": "2025-06-05T12:09:11.892Z"
      }
    }
  ```
</CodeGroup>

* `transactionHash` — hash of the TRON transaction.
* `status` — transaction status: `PENDING`, `CONFIRMED` or `FAILED`.
* `confirmed` — boolean flag indicating whether the transaction has been included in a block.
* `block` — unique identifier of the block in which the transaction has been included; `null` if the transaction has not been confirmed yet.
* `energyUsed` — amount of energy points consumed by the transaction.
* `createdAt` — timestamp of the transaction in the ISO 8601 format.

### Get account summary

To track delegator account balances, frozen TRX, and voting details, send a GET request to [/api/v1/tron/\{network}/account/\{address}](/reference/tron-account-get).

Example request (for `testnet-nile` network):

<CodeGroup>
  ```bash curl theme={null}
  curl --request GET \
    --url 'https://api-test.p2p.org/api/v1/tron/testnet-nile/account/TNDzfERDpxLDS2w1q6yaFC7pzqaSQ3Bg3r' \
    --header 'accept: application/json' \
    --header 'Authorization: Bearer <token>'
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(
    "https://api-test.p2p.org/api/v1/tron/testnet-nile/account/TNDzfERDpxLDS2w1q6yaFC7pzqaSQ3Bg3r",
    {
      method: "GET",
      headers: {
        "accept": "application/json",
        "Authorization": "Bearer <token>",
      },
    }
  );
  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api-test.p2p.org/api/v1/tron/testnet-nile/account/TNDzfERDpxLDS2w1q6yaFC7pzqaSQ3Bg3r",
      headers={
          "accept": "application/json",
          "Authorization": "Bearer <token>",
      },
  )
  print(response.json())
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"io"
  	"net/http"
  )

  func main() {
  	req, _ := http.NewRequest("GET", "https://api-test.p2p.org/api/v1/tron/testnet-nile/account/TNDzfERDpxLDS2w1q6yaFC7pzqaSQ3Bg3r", nil)
  	req.Header.Set("accept", "application/json")
  	req.Header.Set("Authorization", "Bearer <token>")
  	resp, _ := http.DefaultClient.Do(req)
  	defer resp.Body.Close()
  	respBody, _ := io.ReadAll(resp.Body)
  	fmt.Println(string(respBody))
  }
  ```
</CodeGroup>

* `address` — TRON account address.

Example response:

<CodeGroup>
  ```json theme={null}
  {
      "result": {
        "address": "TQ5N6Znhy92Yq2a4YDosMkbqygXgU5Ykh",
        "balance": 250000000,
        "availableVotes": 500,
        "usedVotes": 1500,
        "totalVotes": 2000,
        "votes": {
          "TLGQ9jXwWXsy8sxkXoXKVLfV7Qe64Q8Yh1": 1000,
          "TKTcsyw81V4WsqfK8AYx7zoXvD3QycjCkg": 500
        },
        "voteList": [
          {
            "voteAddress": "TLGQ9jXwWXsy8sxkXoXKVLfV7Qe64Q8Yh1",
            "voteCount": 1000
          },
          {
            "voteAddress": "TKTcsyw81V4WsqfK8AYx7zoXvD3QycjCkg",
            "voteCount": 500
          }
        ],
        "hasEnergyStake": true,
        "hasBandwidthStake": false,
        "createdAt": "2025-06-26T19:28:54.816Z",
        "netUsage": 432,
        "accountCreatedAt": "2023-09-15T07:20:35.000Z",
        "lastOperationAt": "2025-06-08T09:17:42.000Z"
      },
      "error": {}
    }
  ```
</CodeGroup>

* `address` — address of the TRON account in the base58 format.

* `balance` — total amount of tokens in SUN staked by the account (1 TRX = 10⁶ SUN).

* `availableVotes` — number of votes available to assign to the Super Representatives.

* `usedVotes` — number of votes already used by this address.

* `totalVotes` — total number of votes granted to this account based on the total amount of frozen TRX.

* `votes` — list of key-value pairs: vote address and the vote count.

* `voteList` — list of vote entries for this account:

  * `voteAddress` — vote account address of the Super Representative received the delegation.
  * `voteCount` — number of votes delegated to this vote address.

* `hasEnergyStake` — boolean flag indicating if the account has frozen TRX for the `ENERGY` type of resources.

* `hasBandwidthStake` — boolean flag indicating if the account has frozen TRX for the BANDWIDTH type of resources.

* `createdAt` — timestamp of the report generation in the ISO 8601 format.

* `netUsage` — total amount of bandwidth points consumed by the account.

* `accountCreatedAt` — timestamp of the account creation in the ISO 8601 format.

* `lastOperationAt` — timestamp of the last operation performed by the account in the ISO 8601 format.


## Related topics

- [Sign and Send Transaction](/docs/signing-transaction-tron.md)
- [Withdrawal](/docs/withdrawal-tron.md)
- [Staking API reference](/reference/tron-staking-delegate.md)