> ## 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 TON programmatically with the P2P.org Staking API.

There are two ways to start staking on the TON network using the Staking API:

* Stake individually with a validator via a single nominator pool
* Stake along with multiple nominators via [Ton Whales pools](https://tonwhales.com/staking)

<Warning>
  **Action Required: Single Nominator Pools**

  This is an alternative type of the TON smart contract designed for validators that have enough self stake to validate by themselves without relying on third-party nominators stakes.

  The single nominator staking flow requires manual activation. Before you begin, please contact the [P2P team](/docs/contacts) to whitelist your wallet address.

  *Note: Attempting to stake without pre-registration will result in validation error.*
</Warning>

For both flows, to start using the Staking API:

1. Create a staking request.
2. Sign and broadcast the staking transaction to the 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 Blockchain
    Client->>P2P API: Create stake transaction
    P2P API-->>Client: Unsigned transaction
    Client->>Client: Sign transaction locally
    Client->>Blockchain: Broadcast signed transaction
    Blockchain-->>Client: Transaction hash
```

<Steps>
  <Step title="Create staking request">
    Depending on the type of your staking pool, send a POST request either to [/api/v1/ton/\{network}/staking/single-nominator/stake](/reference/ton-staking-single-nominator-stake) or to [/api​/v1​/ton​/\{network}​/staking​/ton-whales​/stake](/reference/ton-staking-ton-whales-stake).

    Example request (in the `testnet` network for a single nominator pool):

    <CodeGroup>
      ```bash curl theme={null}
      curl --request POST \
           --url https://api-test.p2p.org/api/v1/ton/testnet/staking/single-nominator/stake \
           --header 'accept: application/json' \\
       		 --header 'authorization: Bearer <token>' \\
       		 --header 'content-type: application/json' \\
       		 --data '
      {
        "publicKey": "7031f1dcbe0f670daf4094d04ff9a7947bc4ac9174a7d470255d1a664e20b7c6",
        "amount": 20000000000,
        "walletVersion": "V4"
      }'
      ```

      ```typescript TypeScript theme={null}
      const response = await fetch(
        "https://api-test.p2p.org/api/v1/ton/testnet/staking/single-nominator/stake",
        {
          method: "POST",
          headers: {
            "accept": "application/json",
            "authorization": "Bearer <token>",
            "content-type": "application/json",
          },
          body: JSON.stringify({
            publicKey: "7031f1dcbe0f670daf4094d04ff9a7947bc4ac9174a7d470255d1a664e20b7c6",
            amount: 20000000000,
            walletVersion: "V4",
          }),
        }
      );
      const data = await response.json();
      console.log(data);
      ```

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

      response = requests.post(
          "https://api-test.p2p.org/api/v1/ton/testnet/staking/single-nominator/stake",
          headers={
              "accept": "application/json",
              "authorization": "Bearer <token>",
              "content-type": "application/json",
          },
          json={
              "publicKey": "7031f1dcbe0f670daf4094d04ff9a7947bc4ac9174a7d470255d1a664e20b7c6",
              "amount": 20000000000,
              "walletVersion": "V4",
          },
      )
      print(response.json())
      ```

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

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

      func main() {
      	payload := map[string]interface{}{
      		"publicKey":     "7031f1dcbe0f670daf4094d04ff9a7947bc4ac9174a7d470255d1a664e20b7c6",
      		"amount":        20000000000,
      		"walletVersion": "V4",
      	}
      	body, _ := json.Marshal(payload)
      	req, _ := http.NewRequest("POST", "https://api-test.p2p.org/api/v1/ton/testnet/staking/single-nominator/stake", 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>

    * `publicKey` — public key of the nominator for the TON network.

    * `amount` — amount of tokens to stake in nanoGRAMs (1 GRAM = 10⁹ nanoGRAMs). Note that the minimum staking amount is not limited, but there is a maximum cap of 2 000 000 GRAM for each pool.

    * `walletVersion` — [version of the smart contract](https://docs.ton.org/participate/wallets/contracts) used by the wallet in the TON blockchain:

      * `V3R1` and `V3R2` — wallet V3.
      * `V4` — wallet V4; used by default.
      * `V5R1` — wallet V5.

    Example response:

    <CodeGroup>
      ```json theme={null}
      {
          "error": null,
          "result": {
            "unsignedTransaction": "b5ee9c7241010101003800006b000010000000000000000001000000039fedeab7a2b56b38f19f60b5b9f70b2f1ba2d89b9c5a756036c7cfad73571fb281887735940193456f7e",
            "walletVersion": "V4",
            "stakerAddress": "0QDZncytCDTPJylG1POFhqzeCLDFZNKhJ2v73lcsBNjQHMZx",
            "publicKey": "7031f1dcbe0f670daf4094d04ff9a7947bc4ac9174a7d470255d1a664e20b7c6",
            "amount": 2
          }
        }
      ```
    </CodeGroup>

    * `unsignedTransaction` — <Tooltip tip="A transaction that must be signed and broadcasted to the blockchain network.">unsigned transaction</Tooltip> in the hexadecimal format. Sign the transaction and submit it to the blockchain to create a staking request.

    * `poolAddress` — nominator pool address (for Ton Whales pools).

    * `walletVersion` — [version of the smart contract](https://docs.ton.org/participate/wallets/contracts) used by the wallet in the TON blockchain.

    * `stakerAddress` — main account address of the <Tooltip tip="On TON, the bounceable address format protects users from erroneous transfers. If some issue happens during the transaction, the message will be “bounced” back to the sender and constitute the remainder of the original value of the transaction with the deduction of all transfer and gas fees. This ensures the sender doesn't lose their funds that were sent by accident to an address that cannot accept the transaction. This format is also the simplest and most readable, and it is used by regular users for standard transactions on the network.">bounceable</Tooltip> type which keeps tokens.

    * `publicKey` — public key of the nominator for the TON network.

    * `amount` — amount of tokens to stake in TON.
  </Step>

  <Step title="Sign and broadcast transaction">
    [Sign and broadcast](/docs/signing-transaction-ton) the `unsignedTransaction` to the TON network.

    To check the transaction status, send a GET request to [/api/v1/ton/\{network}/transactions/status/\{address}/\{transactionHash}](/reference/ton-staking-transaction-status).

    Example request (in the `testnet` network for a single nominator pool):

    <CodeGroup>
      ```bash curl theme={null}
      curl --request GET \
           --url https://api-test.p2p.org/api/v1/ton/testnet/transactions/status/{transactionHash} \
           --header 'accept: application/json'
      ```

      ```typescript TypeScript theme={null}
      const response = await fetch(
        "https://api-test.p2p.org/api/v1/ton/testnet/transactions/status/{transactionHash}",
        {
          method: "GET",
          headers: {
            "accept": "application/json",
          },
        }
      );
      const data = await response.json();
      console.log(data);
      ```

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

      response = requests.get(
          "https://api-test.p2p.org/api/v1/ton/testnet/transactions/status/{transactionHash}",
          headers={
              "accept": "application/json",
          },
      )
      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/ton/testnet/transactions/status/{transactionHash}", nil)
      	req.Header.Set("accept", "application/json")
      	resp, _ := http.DefaultClient.Do(req)
      	defer resp.Body.Close()
      	respBody, _ := io.ReadAll(resp.Body)
      	fmt.Println(string(respBody))
      }
      ```
    </CodeGroup>

    * `address` — staker account address.
    * `transactionHash` — hash of the transaction.

    Example response:

    <CodeGroup>
      ```json theme={null}
      {
            "error": null,
            "result": {
              "address": "0QC1f6DghlW6w31D7GWiYt0dZvX1SR3sGAsto_AhdQRFBobh",
              "lt": "27726830000001",
              "prevTransactionHash": "6210303f3cfb630c349b3859d9e367a65a6772938c681774e2a315aa95c80224",
              "prevTransactionLt": "1234567890abcdef",
              "now": 1730905768,
              "outMessagesCount": 1,
              "oldStatus": "active",
              "endStatus": "active",
              "transactionHash": "2829e4bb8a7b8084040c731a07523d680ce30fecef12f8eec1e409f3c6077a5e"
          },
        }
      ```
    </CodeGroup>

    * `address` — staker account address.
    * `lt` — logical time of the last transaction created by this staker account.
    * `prevTransactionHash` — hash of the previous transaction.
    * `prevTransactionLt` — logical time of the previous transaction.
    * `now` — current time on the TON blockchain node.
    * `outMessagesCount` — count of output messages sent by the smart contract in the result of this transaction.
    * `oldStatus` — staker account status before transaction execution.
    * `endStatus` — staker account status after transaction execution.
    * `transactionHash` — hash of the transaction.
  </Step>
</Steps>


## Related topics

- [Staking API reference](/reference/ton-staking-single-nominator-stake.md)
- [Withdrawal](/docs/withdrawal-ton.md)