API Reference
Finality Certificate Endpoints
Pre-launch
Section
API Reference
Documentation category
Type
Guide
Technical reference
Summary
Complete reference for SwssChain Finality Certificate API endpoints (by tx hash, certificate hash, address, and lightweight verify) with full field reference.
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

Finality Certificate Endpoints

Finality Certificate endpoints provide programmatic access to all cryptographic settlement certificates issued on SwssChain. Every deed transaction generates exactly one Finality Certificate. Certificates are permanent, immutable, and independently verifiable by any party at any time. These endpoints are the primary integration point for applications that need to confirm legal settlement finality before proceeding with business logic.

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

GET /certificates/{txHash}

Returns the Finality Certificate for a deed transaction. This is the primary verification endpoint. The txHash parameter is the original deed transaction hash, not the certificate hash.

curl https://swssscan.swss.io/api/v1/certificates/0xtxhash...   -H "X-API-Key: your_api_key"
{
  "certificateHash": "0xcert9f2a...",
  "transactionHash": "0xtxhash...",
  "blockNumber": 1234567,
  "timestamp": "2026-05-15T10:00:01Z",
  "assetClass": "HOME_DEED_V1",
  "deedType": "Home Deed",
  "jurisdiction": "England and Wales",
  "validatorSignatures": [
    "0xsig1...",
    "0xsig2...",
    "0xsig3...",
    "0xsig4..."
  ],
  "validatorCount": 4,
  "requiredSignatures": 3,
  "verified": true,
  "tslRetirementHash": "0xtsl...",
  "permanentRecordUrl": "https://swssscan.swss.io/certificates/0xcert9f2a..."
}

GET /certificates/hash/{certificateHash}

Returns a certificate using its own hash rather than the originating transaction hash. Useful when you have stored the certificate hash but not the transaction hash.

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

GET /certificates/address/{address}

Returns paginated Finality Certificates for a wallet address. Optionally filter by deed type.

curl "https://swssscan.swss.io/api/v1/certificates/address/0xwallet...?page=1&limit=20&deedType=HOME_DEED_V1"   -H "X-API-Key: your_api_key"

GET /certificates/verify/{txHash}

Lightweight verification endpoint. Returns only verified: true/false without the full certificate payload. Faster than the full endpoint: use this for application-level checks where you need confirmation but not the complete data.

curl https://swssscan.swss.io/api/v1/certificates/verify/0xtxhash...   -H "X-API-Key: your_api_key"
{
  "transactionHash": "0xtxhash...",
  "verified": true,
  "certificateHash": "0xcert9f2a..."
}

Finality Certificate Object: Complete Field Reference

FieldTypeDescription
certificateHashstringHash of the complete certificate: the tamper-evident seal
transactionHashstringSource deed transaction hash
blockNumberintegerBlock in which the certificate was produced
timestampstringISO 8601 settlement timestamp
assetClassstringProtocol-level asset class identifier (e.g. HOME_DEED_V1)
deedTypestringHuman-readable deed type name
jurisdictionstringLegal jurisdiction recorded at consensus layer
validatorSignaturesarrayCryptographic signatures from all active validators
validatorCountintegerNumber of validators that signed this certificate
requiredSignaturesintegerMinimum required (3 of 4 under BFTFA)
verifiedbooleantrue when all signatures are cryptographically valid
tslRetirementHashstringHash of the TSL supply retirement event associated with this deed
permanentRecordUrlstringShareable Explorer URL for this certificate: suitable for legal documentation

SwssChain JSON-RPC Method

curl https://YOUR_RPC_URL   -H "Content-Type: application/json"   -d '{
    "jsonrpc": "2.0",
    "method": "swss_getFinalityCertificate",
    "params": ["0xtxhash..."],
    "id": 1
  }'

Next Steps