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

Staking with Story Protocol via the Staking API consists of several main steps:

1. Create a staking request.
2. Sign and send the 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->>P2P API: Broadcast signed transaction
    P2P API->>Blockchain: Submit transaction
    Blockchain-->>P2P API: Transaction hash
    P2P API-->>Client: Transaction status
```

<Steps>
  <Step title="Create staking request">
    Send a POST request to [/api/v1/story/\{network}/staking/stake](/reference/story-staking-stake).

    Example request (for `aeneid` network):

    <CodeGroup>
      ```bash curl theme={null}
      curl --request POST \
           --url https://api-test.p2p.org/api/v1/story/aeneid/staking/stake \
           --header 'accept: application/json' \
           --header 'authorization: Bearer <token>' \
           --header 'content-type: application/json' \
           --data '{
             "amount": 1024,
             "delegatorAddress": "0x3202B5B0602274197CcB22B8c02CEC9539990c7c",
             "stakingPeriod": 0,
             "tokenType": "UNLOCKED",
             "gas": {
               "maxFeePerGas": 100,
               "maxPriorityFeePerGas": 1,
               "gasLimit": 21000
             }
           }'
      ```

      ```typescript TypeScript theme={null}
      const response = await fetch(
        "https://api-test.p2p.org/api/v1/story/aeneid/staking/stake",
        {
          method: "POST",
          headers: {
            "accept": "application/json",
            "authorization": "Bearer <token>",
            "content-type": "application/json",
          },
          body: JSON.stringify({
            amount: 1024,
            delegatorAddress: "0x3202B5B0602274197CcB22B8c02CEC9539990c7c",
            stakingPeriod: 0,
            tokenType: "UNLOCKED",
            gas: {
              maxFeePerGas: 100,
              maxPriorityFeePerGas: 1,
              gasLimit: 21000,
            },
          }),
        }
      );
      const data = await response.json();
      console.log(data);
      ```

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

      response = requests.post(
          "https://api-test.p2p.org/api/v1/story/aeneid/staking/stake",
          headers={
              "accept": "application/json",
              "authorization": "Bearer <token>",
              "content-type": "application/json",
          },
          json={
              "amount": 1024,
              "delegatorAddress": "0x3202B5B0602274197CcB22B8c02CEC9539990c7c",
              "stakingPeriod": 0,
              "tokenType": "UNLOCKED",
              "gas": {
                  "maxFeePerGas": 100,
                  "maxPriorityFeePerGas": 1,
                  "gasLimit": 21000,
              },
          },
      )
      print(response.json())
      ```

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

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

      func main() {
      	payload := map[string]interface{}{
      		"amount":           1024,
      		"delegatorAddress": "0x3202B5B0602274197CcB22B8c02CEC9539990c7c",
      		"stakingPeriod":    0,
      		"tokenType":        "UNLOCKED",
      		"gas": map[string]interface{}{
      			"maxFeePerGas":         100,
      			"maxPriorityFeePerGas": 1,
      			"gasLimit":             21000,
      		},
      	}
      	body, _ := json.Marshal(payload)
      	req, _ := http.NewRequest("POST", "https://api-test.p2p.org/api/v1/story/aeneid/staking/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>

    * `amount` — amount of tokens to stake in IP. The minimum stake amount is 1024 IP.

    * `delegatorAddress` — delegator EVM Story account address.

    * `stakingPeriod`— staking period duration:

      * `FLEXIBLE` — no lock-up; funds can be withdrawn at any time.
      * `SHORT` — 90 days of the lock-up period.
      * `MEDIUM` — 360 days of the lock-up period.
      * `LONG` — 540 days of the lock-up period.

    * `tokenType`— token source type:

      * `UNLOCKED` — tokens will be locked during staking from the user’s free balance.
      * `LOCKED`— tokens have already been locked, e.g., via the protocol rules; no additional lock-up applied.

    * `gas` — optional gas settings to execute the transaction:

      * `maxFeePerGas` — maximum price per unit of gas this transaction will pay for the combined EIP-1559 block's base fee and this transaction's priority fee in Wei.
      * `maxPriorityFeePerGas` — price per unit of gas in Wei, which is added to the EIP-1559 block's base fee. This added fee is used to incentivize miners to prioritize this transaction.
      * `gasLimit` — maximum gas limit for the transaction.

    Example response:

    <CodeGroup>
      ```json theme={null}
      {
          "result": {
            "unsignedTransaction": "0xf86e808504a817c80082520894c32e3d7c7e6e53d16b9a48d0ae76c70e6adf09f080801ba0f31401df9e6f6d861fdf09d1e69b5f51855f4f63b0179033a6c3871c05ec93da03e0f7d7eab4a3179b29b416d6c75dbe53de763153b7ed9e2c49883c8fca1ef29c",
            "createdAt": "2025-07-22T12:34:56.789Z"
          }
        }
      ```
    </CodeGroup>

    * `unsignedTransaction` — unsigned serialized transaction in the hexadecimal format ready for signing. Sign the transaction and submit it to the blockchain to perform the called action. Note that it must be signed and submitted within a limited time window (e.g., 1 minute).
    * `createdAt` — timestamp of the transaction in the ISO 8601 format.
  </Step>

  <Step title="Sign and send transaction">
    Use `unsignedTransaction` to [sign and send](/docs/signing-transaction-story) the signed transaction to the Story Protocol network.
  </Step>
</Steps>


## Related topics

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