Documentation
P2P.org
Start typing to search…

Getting Started

📘

The Pooled Staking API is currently only available with exclusive access.

Public availability will be announced soon. To request access or discuss integration, please contact us.

Staking via the Pooled Staking API enables enterprise partners to offer secure, seamless ETH staking to their users, with no 32 ETH minimum.

The process consists of several straightforward steps:

  1. Discover available vaults
  2. Build a deposit transaction
  3. Sign and broadcast the transaction
  4. Track staking status and rewards
  5. Monitor historical balance and APY

Get an authentication token to start using Pooled Staking API.

Request examples are provided using cURL.

Lifecycle diagram:

sequenceDiagram
    participant USER as User (wallet/app)
    participant PARTNER as Partner Backend
    participant API as Pooled Staking API
    participant ETH as Ethereum Network

    %% --- DEPOSIT FLOW ---
    USER->>PARTNER: Stake ETH (<32 ETH)
    PARTNER->>API: POST /staking/deposit
    API-->>PARTNER: Unsigned deposit transaction
    PARTNER->>USER: User signs transaction
    USER-->>PARTNER: Signed deposit transaction
    PARTNER->>API: POST /transaction/send
    API-->>ETH: Broadcast to Ethereum

    %% --- WITHDRAWAL FLOW ---
    USER->>PARTNER: Unstake (withdraw) ETH
    PARTNER->>API: POST /staking/withdraw
    API-->>PARTNER: Unsigned withdrawal transaction
    PARTNER->>USER: User signs transaction
    USER-->>PARTNER: Signed withdrawal transaction
    PARTNER->>API: POST /transaction/send
    API-->>ETH: Broadcast to Ethereum

    %% --- OPTIONAL: STATUS/CLAIM ---
    Note over USER,PARTNER: ETH claimable after 1–4 days.
    PARTNER->>API: POST /staking/claim (when claimable)
    API-->>PARTNER: Unsigned claim transaction
    PARTNER->>USER: User signs transaction
    USER-->>PARTNER: Signed claim transaction
    PARTNER->>API: POST /transaction/send
    API-->>ETH: Broadcast to Ethereum
    ETH-->>USER: ETH returned to user wallet

1. Discover Available Vaults

Before staking, retrieve the list of vaults available to your integration on the target network.

Send a GET request to /api/v1/eth-pool/[network]/staking/vaults

Example request (for hoodi network):

curl --request GET \
     --url https://api-test.p2p.org/api/v1/eth-pool/hoodi/staking/vaults \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <token>'

Example response:

{
  "result": [
    {
      "address": "0xAaa1111111111111111111111111111111111111",
      "isPrivate": false
    },
    {
      "address": "0xba447498dc4c169f2b4f427b2c4d532320457e89",
      "isPrivate": true
    }
  ],
  "error": null
}
  • address — Ethereum address of the vault.
  • isPrivate — Indicates if this vault is exclusive to your integration (true) or shared/public (false).

Always select the correct vaultAddress for all staking operations.

2. Build Deposit Transaction

Initiate staking by creating an unsigned deposit transaction for the selected vault.

Send a POST request to /api/v1/eth-pool/[network]/staking/deposit

Example request (for hoodi network):

curl --request POST \
     --url https://api-test.p2p.org/api/v1/eth-pool/hoodi/staking/deposit \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <token>' \
     --data '{
    "stakerAddress": "0x092Af80778ff3c3D27Fd2744C39f6e9326d9AaEe",
    "vaultAddress": "0xba447498dc4c169f2b4f427b2c4d532320457e89",
    "amount": 0.01
}'
  • stakerAddress — User’s Ethereum address (sender and beneficiary).
  • vaultAddress — Vault address where the deposit will be made.
  • amount — Amount of ETH to stake (decimal, e.g., 0.01).

Example response:

{
  "result": {
    "unsignedTransaction": {
      "to": "0xba447498dc4c169f2b4f427b2c4d532320457e89",
      "data": "0xf9609f08000000000000000000000000092af80778ff3c3d27fd2744c39f6e9326d9aaee0000000000000000000000000000000000000000000000000000000000000000",
      "value": "10000000000000000"
    },
    "createdAt": "2023-08-24T08:14:50.455Z"
  },
  "error": {}
}
  • unsignedTransaction — Standard Ethereum transaction object (ready to sign).

3. Sign and Send Transaction

Use unsignedTransaction to sign and send the signed transaction to the Ethereum network.

  • Signing: Must be performed on your backend or user device.
  • Broadcast: Use Pooled Staking API or your own node.

Send a POST request to /api/v1/eth-pool/[network]/transaction/send

Example request (for hoodi network):

curl --request POST \
     --url https://api-test.p2p.org/api/v1/eth-pool/hoodi/transaction/send \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <token>' \
	   --data '{
       "signedTransaction": "0xf86b82015285012a05f20083...1c0029"
     }'
  • signedTransaction — Hex-encoded, signed Ethereum transaction.

Example response:

{
  "result": {
    "transactionHash": "0x8d80b8ed85b578eeb873731101a926221701ee48218f6c9b83895f7ac1535641",
    "status": "PENDING"
  },
  "error": null
}
  • transactionHash — Ethereum transaction hash.
  • status — Current status: PENDING, CONFIRMED, FAILED.

Status tracking

To check the transaction status, send a GET request to /api/v1/eth-pool/{network}/transaction/status/{transactionHash}] endpoint.

Example request (for hoodi network):

curl --request GET \
     --url https://api.p2p.org/api/v1/eth-pool/hoodi/transaction/status/0x8d80b8ed85b578eeb873731101a926221701ee48218f6c9b83895f7ac1535641 \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <token>' \
     --header 'content-type: application/json'
  • transactionHash — hash of the transaction.

4. Track Staking Status and Rewards

Monitor user balances, staking status, and withdrawal eligibility.

Send a GET request to /api/v1/eth-pool/[network]/account/[stakerAddress]

Example request (for hoodi network):

curl --request GET \
     --url https://api-test.p2p.org/api/v1/eth-pool/hoodi/account/0x092Af80778ff3c3D27Fd2744C39f6e9326d9AaEe \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <token>'

Example response:

{
  "result": {
    "stakeStatus": "ACTIVE",         // or "PENDING", "IN_QUEUE", "CLAIMABLE"
    "pendingAmount": "1000000000000000000",
    "claimableAmount": "0",
    "estimatedClaimTime": null
  },
  "error": null
}
  • stakeStatus — Current state of the user's stake (ACTIVE, PENDING, IN_QUEUE, CLAIMABLE).
  • pendingAmount — Pending ETH (Wei).
  • claimableAmount — ETH available to claim (Wei).
  • estimatedClaimTime — Estimated timestamp (ISO 8601) for next claimable event, if applicable.

5. Monitor Historical Balance and APY

Retrieve daily balance and reward history, as well as current APY.

Send a GET request to /api/v1/eth-pool/[network]/account/[stakerAddress]/stats

Example request (for hoodi network):

curl --request GET \
     --url https://api-test.p2p.org/api/v1/eth-pool/hoodi/account/0x092Af80778ff3c3D27Fd2744C39f6e9326d9AaEe/stats \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <token>'

Example response:

{
  "result": {
    "apy": 0.041,
    "history": [
      {
        "date": "2025-07-01",
        "balance": "1200000000000000000",
        "rewards": "40000000000000000"
      }
    ]
  },
  "error": null
}
  • apy — Annual percentage yield (float).
  • history — Array of daily snapshots:
    • date — ISO 8601 date.
    • balance — User balance (Wei).
    • rewards — Rewards earned on that date (Wei).

What's Next?

Updated about 12 hours ago