SierraChain Developer Documentation

Overview

SierraChain is a permissioned settlement blockchain designed for African fintech ecosystems. It provides independently verifiable settlement proofs, immutable audit trails, settlement wallet operations, and blockchain-backed confirmation records for financial participants.

The current public developer surface includes settlement wallet APIs, reserve and capture flows, multi-party settlement, blockchain proof APIs, explorer verification, webhook notifications, and SDKs for .NET, Python, and Node.js.

Platform Positioning

SierraChain is not a cryptocurrency product. It is settlement verification infrastructure. Real-world money movement remains governed by the relevant banks, switches, wallets, payment aggregators, and regulators. SierraChain records settlement evidence so participants can verify what happened without relying only on another organization’s database.

Authentication

Partner APIs use API-key authentication. Include the participant API key in the X-API-Key header.

X-API-Key: YOUR_API_KEY

Example:

curl -s https://api.sierrachain.io/api/v1/wallets/me \
-H "X-API-Key: YOUR_API_KEY"

Environments

Data Formats

Amounts

Settlement amounts are sent as decimal strings. Do not convert settlement amounts into integers in SDKs or partner applications.

{
  "amount": "123.45",
  "currency": "SLE"
}

API responses may return stored decimal precision, for example 123.45000000. Display layers should format this as 123.45 while preserving precision internally.

Fees

Fees may be zero or fractional. Handle values such as 0E-8, 0.0001, and 0.25 safely as decimal values.

References

Use unique references for settlement operations. Recommended pattern:

PARTNER-YYYYMMDD-SEQUENCE
TPAY-20260623-000001

Wallets

Wallets represent participant settlement positions on SierraChain. Each participant may have one or more wallets, such as settlement wallets, fee wallets, or reserve wallets.

GET /api/v1/wallets/me

curl -s https://api.sierrachain.io/api/v1/wallets/me \
-H "X-API-Key: YOUR_API_KEY"

Example response:

{
  "items": [
    {
      "walletAddress": "TERAPAY001_SETTLEMENT",
      "walletType": "settlement",
      "ownerClientId": "TERAPAY001",
      "status": "active",
      "availableBalance": "99000.00000000",
      "lockedBalance": "0E-8",
      "currency": "SLE"
    }
  ]
}

Wallet Transfer

Moves available balance from the authenticated participant wallet to another active wallet. A completed wallet transfer can create an on-chain settlement proof.

POST /api/v1/wallets/transfer

curl -s -X POST https://api.sierrachain.io/api/v1/wallets/transfer \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "destinationWalletAddress": "MARIEPAY001_SETTLEMENT",
  "amount": "123.45",
  "transactionReference": "SETTLE-001",
  "externalReference": "ORDER-001",
  "description": "TeraPay settlement to MariePay"
}'

Example response:

{
  "success": true,
  "transaction": {
    "id": "a6c051f0-d496-482f-baf7-a1bfe1bda9bf",
    "transactionReference": "SETTLE-001",
    "amount": "123.45000000",
    "transactionType": "transfer",
    "transactionStatus": "completed",
    "blockchainTransactionHash": "0ac5c0dd452309bb66b43a6d74f311a30f3f9a4d899777940f116e8f161cffde",
    "blockchainBlockHeight": 25,
    "externalReference": "ORDER-001"
  }
}

Reserve Funds

Locks funds in the authenticated participant wallet. Available balance decreases and locked balance increases. Use reserve when settlement should be guaranteed before final capture.

POST /api/v1/wallets/reserve

{
  "amount": "500.00",
  "reservationReference": "RSV-001",
  "externalReference": "ORDER-001",
  "description": "Reserve funds for settlement"
}

Release Funds

Releases previously reserved funds back to the source wallet when a payment is cancelled, expires, or fails business validation.

POST /api/v1/wallets/release

{
  "reservationReference": "RSV-001",
  "releaseReference": "REL-001",
  "description": "Release reserved funds"
}

Capture Settlement

Captures reserved funds and credits the destination wallet. A successful capture should generate a blockchain settlement proof.

POST /api/v1/wallets/capture

{
  "reservationReference": "RSV-002",
  "destinationWalletAddress": "MARIEPAY001_SETTLEMENT",
  "captureReference": "CAP-001",
  "externalReference": "ORDER-001",
  "description": "Capture reserved funds to MariePay"
}

Multi-party Settlement

Splits one settlement amount into multiple destination wallets atomically. This is useful for merchant settlement, platform fees, taxes, and other distribution scenarios.

POST /api/v1/wallets/settlements/multiparty

{
  "settlementReference": "MP-SETTLE-001",
  "externalReference": "ORDER-001",
  "description": "Merchant settlement with fees and tax",
  "splits": [
    {
      "destinationWalletAddress": "MERCHANT001_SETTLEMENT",
      "amount": "650.00",
      "description": "Merchant settlement"
    },
    {
      "destinationWalletAddress": "TERAPAY001_FEE",
      "amount": "30.00",
      "description": "Platform fee"
    },
    {
      "destinationWalletAddress": "GOVT001_TAX",
      "amount": "20.00",
      "description": "Tax"
    }
  ]
}

Settlement Proofs

Completed settlement operations may be anchored to SierraChain as settlement_proof transactions. These proofs provide independent verification of settlement activity.

{
  "txType": "settlement_proof",
  "reference": "CHAIN-PROOF-TEST-001",
  "externalReference": "ORDER-CHAIN-001",
  "settlementType": "transfer",
  "status": "completed",
  "amount": "123.45000000",
  "currency": "SLE",
  "sourceWallet": "TERAPAY001_SETTLEMENT",
  "destinationWallet": "MARIEPAY001_SETTLEMENT",
  "sourceClient": "TERAPAY001",
  "destinationClient": "MARIEPAY001"
}

Blockchain APIs

Network Status

GET /rpc/status

curl -s https://api.sierrachain.io/rpc/status

Latest Head

GET /rpc/head

curl -s https://api.sierrachain.io/rpc/head

Get Block

GET /rpc/getBlock?height={height}

curl -s "https://api.sierrachain.io/rpc/getBlock?height=25"

Get Block Transactions

GET /rpc/blockTxs?height={height}

curl -s "https://api.sierrachain.io/rpc/blockTxs?height=25"

Get Public Transaction Receipt

GET /rpc/tx/{hash}

curl -s https://api.sierrachain.io/rpc/tx/0ac5c0dd452309bb66b43a6d74f311a30f3f9a4d899777940f116e8f161cffde

Example response:

{
  "hash": "0ac5c0dd452309bb66b43a6d74f311a30f3f9a4d899777940f116e8f161cffde",
  "status": "completed",
  "txType": "settlement_proof",
  "reference": "CHAIN-PROOF-TEST-001",
  "externalReference": "ORDER-CHAIN-001",
  "settlementType": "transfer",
  "amount": "123.45000000",
  "fee": "0E-8",
  "currency": "SLE",
  "symbol": "SLE",
  "sourceWallet": "TERAPAY001_SETTLEMENT",
  "destinationWallet": "MARIEPAY001_SETTLEMENT",
  "sourceClient": "TERAPAY001",
  "destinationClient": "MARIEPAY001",
  "blockHeight": 25,
  "confirmations": 1
}

Recent Transactions

GET /rpc/recentTxs?limit_blocks={count}

curl -s "https://api.sierrachain.io/rpc/recentTxs?limit_blocks=10"

Inclusion and Finality Proof

GET /rpc/proof/{hash}

curl -s https://api.sierrachain.io/rpc/proof/{transactionHash}

Webhooks

SierraChain can notify participant systems when settlement or block events occur.

POST /api/v1/webhooks/subscriptions

{
  "eventType": "transaction.confirmed",
  "callbackUrl": "https://partner.example.com/sierrachain/webhook",
  "maxRetries": 5
}

Example payload:

{
  "event": "transaction.confirmed",
  "transactionHash": "0ac5c0dd452309bb66b43a6d74f311a30f3f9a4d899777940f116e8f161cffde",
  "reference": "SETTLE-001",
  "externalReference": "ORDER-001",
  "blockHeight": 25,
  "confirmations": 1
}

SDKs

SierraChain provides SDK support for .NET, Python, and Node.js. SDKs should treat settlement amounts and fees as decimal strings or decimal-safe values.

.NET

var client = new SierraChainClient("YOUR_API_KEY", "https://api.sierrachain.io");

var result = await client.TransferAsync(new WalletTransferRequest {
    DestinationWalletAddress = "MARIEPAY001_SETTLEMENT",
    Amount = "1000.00",
    TransactionReference = "SETTLE-001",
    ExternalReference = "ORDER-001",
    Description = "TeraPay settlement to MariePay"
});

Console.WriteLine(result.Transaction.BlockchainTransactionHash);

Python

from sierrachain import SierraChainClient

client = SierraChainClient(
    api_key="YOUR_API_KEY",
    base_url="https://api.sierrachain.io"
)

result = client.transfer(
    destination_wallet_address="MARIEPAY001_SETTLEMENT",
    amount="1000.00",
    transaction_reference="SETTLE-001",
    external_reference="ORDER-001",
    description="TeraPay settlement to MariePay"
)

print(result["transaction"]["blockchainTransactionHash"])

Node.js

const { SierraChainClient } = require("sierrachain-sdk");

const client = new SierraChainClient({
  apiKey: "YOUR_API_KEY",
  baseUrl: "https://api.sierrachain.io"
});

const result = await client.transfer({
  destinationWalletAddress: "MARIEPAY001_SETTLEMENT",
  amount: "1000.00",
  transactionReference: "SETTLE-001",
  externalReference: "ORDER-001",
  description: "TeraPay settlement to MariePay"
});

console.log(result.transaction.blockchainTransactionHash);

End-to-End Examples

Transfer and Verify Proof

# 1. Create wallet settlement transfer
curl -s -X POST https://api.sierrachain.io/api/v1/wallets/transfer \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "destinationWalletAddress": "MARIEPAY001_SETTLEMENT",
  "amount": "123.45",
  "transactionReference": "SETTLE-001",
  "externalReference": "ORDER-001",
  "description": "Settlement transfer"
}'

# 2. Copy blockchainTransactionHash from response

# 3. Verify public proof
curl -s https://api.sierrachain.io/rpc/tx/{blockchainTransactionHash}

Reserve, Capture, and Verify

# Reserve funds
curl -s -X POST https://api.sierrachain.io/api/v1/wallets/reserve \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "amount": "700.00",
  "reservationReference": "RSV-700-001",
  "externalReference": "ORDER-700-001",
  "description": "Reserve before capture"
}'

# Capture settlement
curl -s -X POST https://api.sierrachain.io/api/v1/wallets/capture \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "reservationReference": "RSV-700-001",
  "destinationWalletAddress": "MARIEPAY001_SETTLEMENT",
  "captureReference": "CAP-700-001",
  "externalReference": "ORDER-700-001",
  "description": "Capture reserved settlement"
}'

Error Codes

Best Practices

Use Unique References

Use references that are globally unique within your organization. This prevents accidental duplicate settlement attempts.

Store Blockchain Proofs

Store the blockchainTransactionHash, blockchainBlockHeight, transaction reference, and external reference in your own system for future reconciliation and audit.

Verify Proofs

Use /rpc/tx/{hash} or the Explorer to verify settlement proofs during reconciliation, dispute handling, and audit review.

Use Webhooks

Use webhooks for asynchronous confirmation instead of only polling APIs.

Keep PII Off-Chain

Do not place customer personal data, bank account numbers, mobile numbers, card data, or identity numbers in settlement descriptions, memos, or references.

Protect API Keys

Store keys in a secure backend, environment variables, or a secret manager. Rotate keys according to your internal security policy.

Support