API Reference
Wallet and Balance API
Pre-launch
Section
API Reference
Documentation category
Type
Guide
Technical reference
Summary
Complete reference for SwssChain wallet API endpoints: balance, transaction history, deed settlements, Finality Certificates, and portfolio overview.
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

Wallet and Balance API

Wallet endpoints provide balance, transaction history, deed settlement records, Finality Certificate history, and portfolio overview data for any SwssChain wallet address. All wallet data is read-only via the API: staking actions and transactions are submitted through the SWSS App or directly via the RPC endpoint.

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

GET /wallet/{address}/balance

Returns SWSS Coin balance for a wallet address, including available balance and all active staking positions.

curl https://swssscan.swss.io/api/v1/wallet/0xwallet.../balance   -H "X-API-Key: your_api_key"
{
  "address": "0xwallet...",
  "availableBalance": "5000000000000000000000",
  "stakedBalance": "10000000000000000000000",
  "totalBalance": "15000000000000000000000",
  "stakingPositions": [
    {
      "positionId": "pos_abc...",
      "tier": 5,
      "amount": "10000000000000000000000",
      "unlockTimestamp": "2027-05-15T10:00:00Z"
    }
  ],
  "lastUpdatedBlock": 1234567
}

GET /wallet/{address}/transactions

Returns paginated transaction history. Supports date range filtering and deed-only filtering.

# All transactions
curl "https://swssscan.swss.io/api/v1/wallet/0xwallet.../transactions?page=1&limit=50"   -H "X-API-Key: your_api_key"

# Deed transactions only, with date range
curl "https://swssscan.swss.io/api/v1/wallet/0xwallet.../transactions?deedOnly=true&from=2026-01-01&to=2026-05-15"   -H "X-API-Key: your_api_key"

GET /wallet/{address}/deeds

Returns all deed settlements associated with a wallet address. Optionally filter by deed type using the deedType query parameter.

curl "https://swssscan.swss.io/api/v1/wallet/0xwallet.../deeds?deedType=HOME_DEED_V1"   -H "X-API-Key: your_api_key"

GET /wallet/{address}/certificates

Returns all Finality Certificates associated with deed settlements from a wallet address.

curl https://swssscan.swss.io/api/v1/wallet/0xwallet.../certificates   -H "X-API-Key: your_api_key"

GET /wallet/{address}/portfolio

Returns a complete portfolio overview including all balance components, staking positions, deed holdings, and certificate counts in a single request.

curl https://swssscan.swss.io/api/v1/wallet/0xwallet.../portfolio   -H "X-API-Key: your_api_key"
{
  "address": "0xwallet...",
  "availableBalance": "5000000000000000000000",
  "stakedBalance": "10000000000000000000000",
  "totalBalance": "15000000000000000000000",
  "stakingPositions": [ /* array of staking position objects */ ],
  "deedCount": 3,
  "certificateCount": 3,
  "transactionCount": 284,
  "lastActivityBlock": 1234567,
  "lastActivityTimestamp": "2026-05-15T10:00:01Z"
}

Wallet Balance Object Fields Reference

FieldTypeDescription
addressstringThe queried wallet address
availableBalancestringLiquid (unstaked) SWSS Coin in wei
stakedBalancestringTotal SWSS Coin locked across all staking positions in wei
totalBalancestringSum of available and staked balances in wei
stakingPositionsarrayAll active staking positions: see Staking API for full object shape
lastUpdatedBlockintegerBlock number of the most recent balance-affecting transaction

All balance values are returned as string representations of wei values (the smallest unit of SWSS Coin). To convert to whole SWSS Coin units, divide by 1018 or use ethers.formatEther() in JavaScript.

Next Steps