Getting Started

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

Create a stake transaction.
Sign and send the transaction to the network.

Get an authentication token to start using Staking API.

A request example is provided using cURL.

1. Create Stake Transaction

Send a POST request to /api/v1/story/[network]/staking/stake.

Example request (for aeneid network):

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
       }
     }'

amount — amount of tokens to stake in IP. 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 been already 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:

{
  "result": {
    "unsignedTransaction": "0xf86e808504a817c80082520894c32e3d7c7e6e53d16b9a48d0ae76c70e6adf09f080801ba0f31401df9e6f6d861fdf09d1e69b5f51855f4f63b0179033a6c3871c05ec93da03e0f7d7eab4a3179b29b416d6c75dbe53de763153b7ed9e2c49883c8fca1ef29c",
    "createdAt": "2025-07-22T12:34:56.789Z"
  }
}

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.

2. Sign and Send Transaction

Use unsignedTransaction to sign and send the signed transaction to the Story Protocol network.

1. Create Stake Transaction

2. Sign and Send Transaction

What's Next?