In the following guide, the integration process for the story chain is covered. The Story Protocol integration aligns with the general Unified API process but with network-specific parameters.

Get an authentication token to start using the Unified API.

Request examples are provided using cURL.

To check the integration guides for other chains, refer to the Networks Supported section.

📘
Key Story-specific details

chain — always set to story for Story-related requests.

network — environment in which the transaction is processed: mainnet or aeneid(testnet).

stakerAddress — Ethereum account address of the user initiating staking, unstaking or withdrawal operations, which keeps the Story blockchain tokens.

amount — amount of tokens in IP.

extra.stakingPeriod — staking period duration.

extra.tokenType— token source type.

Staking Flow

1. Create Staking Request

Send a POST request to /api/v1/unified/staking/stake.

Example request (for aeneid network):

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": "story",
  "network": "aeneid",
  "stakerAddress": "0x3202B5B0602274197CcB22B8c02CEC9539990c7c",
  "amount": 1024,
  "extra": {
    "stakingPeriod": "FLEXIBLE",
    "tokenType": "UNLOCKED"
  }
}'

chain — blockchain network, always set to story for Story-related requests.
network — environment in which the transaction is processed: mainnet or aeneid(testnet).
stakerAddress — staking account address receiving the staked tokens.
amount— amount of tokens to stake in IP. Minimum stake amount is 1024 IP.
extra — additional request parameters:
- extra.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.
- extra.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.

Example response:

{
  "error": null,
  "result": {
    "amount": "1024",
    "stakerAddress": "0x3202B5B0602274197CcB22B8c02CEC9539990c7c",
    "unsignedTransactionData": "0xf86f808504a817c80082520894...",
    "extraData": {
      "stakingPeriod": "FLEXIBLE",
      "tokenType": "UNLOCKED"
    }
  }
}

amount — amount of tokens to stake in IP.
stakerAddress — account address initiating the staking transaction.
unsignedTransactionData — serialized unsigned transaction in the hexadecimal format (RLP-encoded).
extraData — additional transaction details:
- stakingPeriod — staking period duration: FLEXIBLE, SHORT, MEDIUM or LONG.
- tokenType — token source type: UNLOCKED or LOCKED.

2. Sign and Send Transaction

Use unsignedTransactionData to sign the transaction Use following the Story-specific signing logic.

To broadcast the signed transaction to the Story network, send a POST request to /api/v1/unified/transaction/broadcast.

Example request:

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": "story",
  "network": "aeneid",
  "signedTransaction": "0xf86f82012a8504a817c80082520894...",
  "stakerAddress": "0x3202B5B0602274197CcB22B8c02CEC9539990c7c"
}'

chain — blockchain network.
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.
stakerAddress — account address initiating the staking transaction.

Example response:

{
    "error": null,
    "result": {
        "extraData": {}
    }
}

Unstaking Flow

1. Create Withdrawal Request

Send a POST request to /api/v1/unified/staking/withdraw.

Example request (for mainnet network):

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": "story",
  "network": "aeneid",
  "stakerAddress": "0x3202B5B0602274197CcB22B8c02CEC9539990c7c",
  "extra": {
    "stakingPeriod": "FLEXIBLE",
    "tokenType": "UNLOCKED"
  }
}'

chain — blockchain network.
network — environment in which the transaction is processed.
stakerAddress — staking account address initiated the staking transaction.
extra — additional request parameters:
- stakingPeriod — staking period duration: FLEXIBLE, SHORT, MEDIUM or LONG.
- tokenType — token source type: UNLOCKED or LOCKED.

Example response:

{
  "error": null,
  "result": {
    "stakerAddress": "0x3202B5B0602274197CcB22B8c02CEC9539990c7c",
    "unsignedTransactionData": "0xf8a9808504a817c800830186a094...",
    "extraData": {
      "stakingPeriod": "FLEXIBLE",
      "tokenType": "UNLOCKED"
    }
  }
}

stakerAddress — account address initiating the unstaking transaction.
unsignedTransactionData — unsigned transaction in Base64 or hex-encoded format. Sign the transaction and submit it to the blockchain to perform the called action.
extraData — additional transaction details:
- stakingPeriod — staking period duration: FLEXIBLE, SHORT, MEDIUM or LONG.
- tokenType — token source type: UNLOCKED or LOCKED.

2. Sign and Send Transaction

Use unsignedTransactionData to sign and send the transaction following the Story-specific signing logic.

Key Story-specific details

Staking Flow

1. Create Staking Request

2. Sign and Send Transaction

Unstaking Flow

1. Create Withdrawal Request

2. Sign and Send Transaction

What's Next?