API Reference
Staking API
Pre-launch
Section
API Reference
Documentation category
Type
Guide
Technical reference
Summary
Complete reference for SwssChain staking API endpoints: positions, rewards, tier rates, and network-wide SGP metrics with full response shapes.
SWSS Foundation Notice

This documentation is restricted to authorised members of the SWSS Developer Community. Access is granted exclusively through SWSS DevHub, after KYB and SWSS Foundation approval.

All SwssChain GitHub repositories are private. Significant updates are currently deploying across the full SWSS Ecosystem. SDK and API specifications are subject to change at any time in accordance with security requirements and SwssChain Foundation governance decisions.

Join SWSS DevHub →Have a question? Use the Need Help? button below.
SDK Update Notice

SWSS SDK v2.1 is deploying across the ecosystem. API signatures may change during this period. Ensure your integration uses the latest schema from SWSS DevHub.

Article Content

Staking API

Staking API endpoints provide read access to all staking data on SwssChain: active positions, earned rewards, current tier rates, and network-wide SGP metrics. Staking actions (entering or exiting a staking position) are performed exclusively through the SWSS App and are recorded on SwssChain. The API provides the data layer for dashboards, analytics, and portfolio applications built on top of the staking system.

Base URL: https://swssscan.swss.io/api/v1

GET /staking/address/{address}

Returns all active and historical staking positions for a wallet address.

curl https://swssscan.swss.io/api/v1/staking/address/0xwallet...   -H "X-API-Key: your_api_key"
{
  "address": "0xwallet...",
  "positions": [
    {
      "positionId": "pos_abc...",
      "tier": 5,
      "amount": "10000000000000000000000",
      "startBlock": 1200000,
      "unlockBlock": 1231536,
      "unlockTimestamp": "2027-05-15T10:00:00Z",
      "estimatedYield": "450000000000000000000",
      "governanceWeight": "50000000000000000000000",
      "status": "active"
    }
  ],
  "totalStaked": "10000000000000000000000",
  "totalPositions": 1
}

GET /staking/address/{address}/rewards

Returns earned and pending staking rewards for a wallet address.

curl https://swssscan.swss.io/api/v1/staking/address/0xwallet.../rewards   -H "X-API-Key: your_api_key"
{
  "address": "0xwallet...",
  "earnedToDate": "125000000000000000000",
  "pendingRewards": "45000000000000000000",
  "nextRewardBlock": 1234600,
  "rewardHistory": [ /* array of reward distribution events */ ]
}

GET /staking/tiers

Returns the current APY rates and parameters for all five staking tiers. Rates reflect the current base pool distribution rate and may be augmented by ERRP Track B as ecosystem revenues activate.

curl https://swssscan.swss.io/api/v1/staking/tiers   -H "X-API-Key: your_api_key"
{
  "tiers": [
    { "tier": 1, "duration": 0, "label": "Flexible", "baseApy": "3.5", "lockDays": 0 },
    { "tier": 2, "duration": 30, "label": "30 Days", "baseApy": "5.0", "lockDays": 30 },
    { "tier": 3, "duration": 90, "label": "90 Days", "baseApy": "7.5", "lockDays": 90 },
    { "tier": 4, "duration": 180, "label": "180 Days", "baseApy": "10.0", "lockDays": 180 },
    { "tier": 5, "duration": 365, "label": "365 Days", "baseApy": "14.0", "lockDays": 365 }
  ],
  "lastUpdatedBlock": 1234567
}

GET /staking/stats

Returns network-wide staking statistics and SGP compression metrics.

curl https://swssscan.swss.io/api/v1/staking/stats   -H "X-API-Key: your_api_key"
{
  "totalStaked": "850000000000000000000000000",
  "totalStakers": 12480,
  "stakersByTier": { "1": 4200, "2": 2800, "3": 2400, "4": 1800, "5": 1280 },
  "totalRewardsDistributed": "42000000000000000000000000",
  "sgpCompressionRatio": "17.0",
  "percentageCirculatingStaked": "34.2",
  "lastUpdatedBlock": 1234567
}

Staking Position Object Fields Reference

FieldTypeDescription
positionIdstringUnique staking position identifier
tierintegerStaking tier 1 through 5
amountstringStaked amount in wei
startBlockintegerBlock at which staking commenced
unlockBlockintegerBlock at which the position unlocks
unlockTimestampstringISO 8601 estimated unlock time
estimatedYieldstringProjected total yield in wei at current rate
governanceWeightstringGovernance voting weight for this position
statusstringactive, unlocking, or completed

Next Steps