Developer Reference
Finality Certificate Programmatic Verification
Pre-launch
Section
Developer Reference
Documentation category
Type
Guide
Technical reference
Summary
Complete developer guide to programmatic Finality Certificate verification: JavaScript, Python, and curl examples with application integration patterns.
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 Programmatic Verification

Every deed transaction settled on SwssChain generates a Finality Certificate automatically at the consensus layer. Any developer can programmatically verify any certificate using the SwssChain Explorer API. This page covers verification in JavaScript (with and without a framework), Python, and via curl: plus guidance on integrating verification into application business logic.

When to Verify Programmatically

Programmatic verification is appropriate whenever your application receives a deed transaction hash and must confirm legal settlement finality before proceeding. Common scenarios include:

  • A property platform confirming deed completion before releasing funds to a seller
  • A compute marketplace confirming a Compute Deed settlement before provisioning GPU access
  • An AI agent platform confirming registration before activating agent capabilities
  • A legal records system archiving the Finality Certificate alongside its own records
  • An audit trail system that must store certificate hashes for future verification

JavaScript Verification

async function verifyFinalityCertificate(txHash) {
  const response = await fetch(
    'https://swssscan.swss.io/api/certificates/' + txHash,
    { headers: { 'Content-Type': 'application/json' } }
  );

  if (!response.ok) {
    throw new Error(`Certificate not found for tx: ${txHash}`);
  }

  const certificate = await response.json();

  if (!certificate.verified) {
    throw new Error(`Certificate verification failed for tx: ${txHash}`);
  }

  return {
    verified: true,
    deedType: certificate.deedType,
    blockNumber: certificate.blockNumber,
    timestamp: certificate.timestamp,
    jurisdiction: certificate.jurisdiction,
    signatureCount: certificate.validatorSignatures.length,
    certificateHash: certificate.certificateHash
  };
}

// Usage
const cert = await verifyFinalityCertificate('0x1deed...');
console.log(`${cert.deedType} settled in block ${cert.blockNumber}`);
console.log(`Signed by ${cert.signatureCount} validators`);

Python Verification

import requests

def verify_finality_certificate(tx_hash: str) -> dict:
    url = f'https://swssscan.swss.io/api/certificates/{tx_hash}'
    response = requests.get(url, timeout=10)
    response.raise_for_status()

    certificate = response.json()

    if not certificate.get('verified'):
        raise ValueError(f'Certificate verification failed for tx: {tx_hash}')

    return {
        'verified': True,
        'deed_type': certificate['deedType'],
        'block_number': certificate['blockNumber'],
        'timestamp': certificate['timestamp'],
        'jurisdiction': certificate['jurisdiction'],
        'signature_count': len(certificate['validatorSignatures']),
        'certificate_hash': certificate['certificateHash']
    }

# Usage
cert = verify_finality_certificate('0x1deed...')
print(f"{cert['deed_type']} settled in block {cert['block_number']}")

curl Verification

curl https://swssscan.swss.io/api/certificates/0xYOUR_TX_HASH

Expected Response Shape

{
  "certificateHash": "0xcert9f2a...",
  "transactionHash": "0x1deed7a3f...",
  "blockNumber": 1234567,
  "timestamp": "2026-05-15T10:00:00Z",
  "assetClass": "HOME_DEED_V1",
  "deedType": "Home Deed",
  "jurisdiction": "England and Wales",
  "validatorSignatures": [
    "0xsig1...",
    "0xsig2...",
    "0xsig3...",
    "0xsig4..."
  ],
  "verified": true
}

Integrating Verification into Application Logic

  • Always verify before releasing funds or provisioning access. A verified: true response confirms all required validators have signed the certificate: do not rely on the transaction hash alone.
  • Store the certificate hash alongside your application records. The certificate hash serves as the tamper-evident reference for future audits. Any party can re-verify the certificate at any time by querying the Explorer API with the original transaction hash.
  • Certificates are permanent. A certificate issued at mainnet launch is as verifiable in 2050 as it is today. There is no expiry, no archival process, and no dependency on any external system beyond the SwssChain public ledger.
  • Handle the 404 case. If a transaction hash does not yet have a certificate, the API returns a 404. On SwssChain's 1-second block time, certificates are typically available within 2 to 3 seconds of the transaction being included in a block.

Next Steps