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.
curl "https://swssscan.swss.io/api/v1/wallet/0xwallet.../transactions?page=1&limit=50" -H "X-API-Key: your_api_key"
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
| Field | Type | Description |
address | string | The queried wallet address |
availableBalance | string | Liquid (unstaked) SWSS Coin in wei |
stakedBalance | string | Total SWSS Coin locked across all staking positions in wei |
totalBalance | string | Sum of available and staked balances in wei |
stakingPositions | array | All active staking positions: see Staking API for full object shape |
lastUpdatedBlock | integer | Block 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