Copy page

Guides

Staking

Requires pools:read for the reads and transactions:write for the transaction flow - granted by name, or through the all:read / all:write wildcards.

Finding a pool

Code
curl https://stg-s2s.restake.gg/api/v1/s2s/staking-pools/simple-strategy/table \
  -H "authorization: Bearer $ACCESS_TOKEN"

Returns the curated selection split into low / mid / high by risk score, ordered by rank within each bucket. Each pool carries its slug - the handle every other call takes - along with apy, avg30dApy, tvlUsd, feePercent, riskScore, and the tokens involved:

Code
{
  "data": {
    "table": {
      "low": [
        {
          "slug": "aave-usdc-base",
          "name": "Aave USDC",
          "project": "Aave",
          "chain": "BASE",
          "poolType": "A_TOKEN",
          "contractAddress": "0x…",
          "riskScore": 12,
          "riskCategory": "low",
          "apy": 5.41,
          "avg30dApy": 5.12,
          "tvlUsd": 84213944.19,
          "feePercent": 0,
          "stakingEnabled": true,
          "website": "https://aave.com",
          "baseToken": { "symbol": "USDC", "chain": "BASE", "contractAddress": "0x…", "decimals": 6 },
          "quoteToken": null,
          "wrapToken": { "symbol": "aBasUSDC", "chain": "BASE", "contractAddress": "0x…", "decimals": 6 },
          "utilization": {
            "level": "normal",
            "rate": 82.4,
            "availableLiquidity": 14820331.5,
            "baseTokenSymbol": "USDC",
            "observedAt": "2026-08-11T09:00:01.000Z"
          },
          "updatedAt": "2026-08-11T09:00:00.000Z"
        }
      ],
      "mid": [],
      "high": []
    }
  }
}

stakingEnabled: false means the pool is listed for data only: building a stake or an unstake against it is a 400 - check it before building a transaction. updatedAt is when the stats were last recomputed, which is what to key your own caching on.

Exit liquidity (utilization)

A lending pool pays depositors back out of what is not lent out. At 100% utilization every unit supplied is borrowed, so an unstake reverts until borrowers repay or new supply arrives - while the APY is at its highest. utilization tells you how close a pool is:

Field	Meaning
rate	Percent of depositor assets that cannot be withdrawn right now, 2 dp
availableLiquidity	What can be withdrawn right now, in base-token units
level	normal, high (from 90%) or critical (from 98%). A pool leaves a level only 3 points below its threshold, so it does not flap
observedAt	When it was read. Readings are hourly

For a vault the rate is exit utilization: the share of its assets it cannot pay out now, whatever the vault's own reporting calls utilization. utilization is null for pools we do not monitor (DEX pools, and vaults we have not mapped yet) and for pools not read yet. Consider holding new stakes into a critical pool, and warn users before an unstake from one. A change of level is also pushed to you as the staking_pool_utilization_changed callback.

Which pools you see

Every pool we list is available to you by default, new ones included - there is nothing to opt into. Your team can switch individual pools off in the partner panel, and a pool switched off leaves this list and stops accepting transactions: a chart, stake or unstake addressed at its slug answers 403.

That is your own configuration, not a permission we set, so the fix is a toggle in the panel rather than a support ticket. A change takes effect within a minute across every instance.

History for one pool:

Code
curl "https://stg-s2s.restake.gg/api/v1/s2s/staking-pools/chart/tvl-apy/aave-usdc-base?dateFrom=2026-07-01" \
  -H "authorization: Bearer $ACCESS_TOKEN"

Ascending by date, defaulting to the last 7 days when dateFrom is omitted. Points with a zero APY are left out.

The transaction flow

Staking is two steps, because the API never holds a user's key:

1. POST …/construct/stake/transaction/batch returns an unsigned EIP-7702 batch user operation plus an intentId.
2. The user's wallet signs bundle.userOpHash and, when bundle.authorization is not null, the EIP-7702 authorization tuple.
3. POST …/transaction/batch/send returns the signatures with the intentId, and the API submits the operation.

The user operation itself never travels back to you. It stays server-side under the intentId, which is what stops a signed call from being replayed against a different chain, amount or target than the one that was quoted.

1. Build

Code
curl -X POST https://stg-s2s.restake.gg/api/v1/s2s/staking-pools/construct/stake/transaction/batch \
  -H "authorization: Bearer $ACCESS_TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "userId": "8f2b1c4e-…",
    "slug": "aave-usdc-base",
    "amount": 250.5
  }'

Code
{
  "data": {
    "intentId": "b7c1…",
    "amount": 250.5,
    "bundle": {
      "chainId": 8453,
      "entryPoint": "0x…",
      "delegate": "0x…",
      "calls": [{ "target": "0x…", "value": "0", "data": "0x…" }],
      "userOp": {
        "sender": "0x…",
        "nonce": "0x…",
        "callData": "0x…",
        "callGasLimit": "0x…",
        "verificationGasLimit": "0x…",
        "preVerificationGas": "0x…",
        "maxFeePerGas": "0x…",
        "maxPriorityFeePerGas": "0x…",
        "signature": "0x"
      },
      "userOpHash": "0x…",
      "authorization": { "chainId": 8453, "address": "0x…", "nonce": 0 }
    }
  }
}

userId names the user the transaction acts for - a partner token identifies your organisation, not a person, so the subject has to be explicit. It must be one of your users; anything else is a 404.

amount in the response is the amount the batch was built for.

Gas is always sponsored: the user's address never needs the chain's native token. The platform fee includes a gas-coverage component that pays for it, priced from the chain's current gas price.

Building for the largest amount (maxAmount)

A "max" button should not send the wallet balance: the platform fee comes on top of a USDC stake, and an unstake can be capped by what the pool can pay out. Send "maxAmount": true instead of amount, and the batch is built for the largest amount the wallet can afford right now, fee included. The response's amount says what that was.

Code
curl -X POST https://stg-s2s.restake.gg/api/v1/s2s/staking-pools/construct/stake/transaction/batch \
  -H "authorization: Bearer $ACCESS_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ "userId": "8f2b1c4e-…", "slug": "aave-usdc-base", "maxAmount": true }'

• Stake: the base-token balance less the platform fee, when the fee is paid in the same token. A tiny remainder stays in the wallet, so a gas price that rises before the batch lands cannot make it unaffordable.
• Unstake: every share the wallet holds that the pool can pay out now (ERC-4626 maxRedeem, or the Aave reserve's unborrowed liquidity). The fee comes out of the withdrawal. A DEX pool answers 400 (MAX_AMOUNT_NOT_SUPPORTED).
• amount is ignored when maxAmount is true.

2. Sign

The wallet produces one or two signatures:

• signature - EIP-191 over the 32 bytes of bundle.userOpHash, prefixed with 0xff00.
• authorization - the EIP-7702 tuple signed as { r, s, yParity }, using bundle.authorization (chainId, address, nonce). Only when bundle.authorization is not null.

bundle.authorization is null once the wallet already delegates to bundle.delegate - normally every batch after the user's first on that chain. Then sign only userOpHash and leave authorization out of the submit body. Sending one anyway, or leaving it out when the bundle has one, is a 400 (AUTHORIZATION_INVALID).

Signing with Privy and Signing with Wallet Core cover both signatures in code, along with the mistakes that get a submit rejected.

3. Submit

Code
curl -X POST https://stg-s2s.restake.gg/api/v1/s2s/staking-pools/transaction/batch/send \
  -H "authorization: Bearer $ACCESS_TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "userId": "8f2b1c4e-…",
    "intentId": "b7c1…",
    "signature": "0x…",
    "authorization": { "r": "0x…", "s": "0x…", "yParity": 0 }
  }'

Code
{ "data": { "userOpHash": "0x…" } }

An intent is single-use and short-lived. A replayed or late submit is a 400 - rebuild and re-sign rather than retrying the same intentId.

Estimating the fee (fee-estimate)

GET …/fee-estimate/:slug?action=stake|unstake&amount=… answers the platform fee and gas fee on an amount, and what is left of it once they are taken. It reads no wallet and builds nothing, so you can call it as the user types. It needs pools:read, and refuses a pool you switched off with 403, like a build.

Code
curl "https://stg-s2s.restake.gg/api/v1/s2s/staking-pools/fee-estimate/aave-usdc-base?action=stake&amount=100" \
  -H "authorization: Bearer $ACCESS_TOKEN"

Code
{
  "data": {
    "amount": 100,
    "amountToken": "USDC",
    "feePercent": 1,
    "systemFeeUsd": 1,
    "gasFeeUsd": 0.1,
    "totalFeeUsd": 1.1,
    "feeTokenSymbol": "USDC",
    "finalAmount": 98.9,
    "finalAmountToken": "USDC"
  }
}

• action is stake (amount in base-token units) or unstake (share units), matching the construct call it is for.
• feePercent is the tier the amount falls in - from the fee tiers you set for your users in the partner panel (Fees), or the platform's default tiers if you have not set any. A change there applies to every estimate and batch built after it.
• gasFeeUsd is the gas coverage at the chain's current gas price; it moves with the network.
• finalAmount is what is left once the fee is taken. On a stake it is amount less the fee, so for a wallet holding amount it is about what maxAmount will stake. On an unstake it is what the shares redeem for (finalAmountToken is the base token) less the fee. When the fee is paid in another token, nothing is taken from it.
• The figures are approximate. The construct call charges the exact fee, and refuses an amount the wallet cannot cover.

Unstaking, and the units trap

Unstaking is the same three steps against …/construct/unstake/transaction/batch, with one difference that is easy to get wrong:

Direction	amount is denominated in
Stake	the base token - baseToken.decimals
Unstake	the wrap token (shares) - wrapToken.decimals

A withdrawal redeems the share token the deposit minted, so it is denominated in that token, not in the asset the user originally deposited. The two can have different decimals, and their exchange rate drifts as the position accrues - which is exactly why the pool view carries decimals for both.

amount is a human-readable number (250.5), not base units; the API scales it by the decimals of the correct token.

An unstake batch also revokes any base-token allowance the wallet still grants the pool contract, so bundle.calls may carry an approve(pool, 0) right after the withdrawal - see Allowances are revoked on unstake.

Failure modes

Status	Cause
400	Unknown pool slug, the pool has stakingEnabled: false, the user has no linked wallet, neither amount nor maxAmount was sent, the wallet cannot afford amount plus fee (INSUFFICIENT_BALANCE), an unstake above what the pool can pay out now, or the intent is unknown, already used or expired
403	Your token lacks transactions:write (or pools:read on fee-estimate), or your team has switched this pool off in the panel
404	No such user, or the user belongs to another partner