SierraChain API Documentation

Overview

SierraChain is a blockchain-backed settlement, reconciliation, audit, and transaction proof network. TeraPay is the first participant, but SierraChain is designed as a neutral network for fintechs, banks, merchants, and public-sector payment flows.

Authentication

Partner APIs use the X-API-Key header.

X-API-Key: tpk_live_xxxxxxxxxxxxx

Environments

Transactions

POST /api/v1/transactions

{
  "externalTransactionId": "TPAY-TEST-001",
  "idempotencyKey": "TPAY-TEST-001",
  "amount": "10.50",
  "reference": "INV-001",
  "memo": "Test transaction from TeraPay"
}

GET /api/v1/transactions/by-external-id/{externalTransactionId}

curl -s https://api.sierrachain.io/api/v1/transactions/by-external-id/TPAY-TEST-001 \
-H "X-API-Key: YOUR_API_KEY"

Wallets

Wallets represent participant settlement positions on SierraChain. The first production use should treat wallets as an internal settlement ledger unless partner-visible balances are formally approved.

GET /api/v1/wallets/me

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

Wallet Transfer

Moves available balance from the authenticated participant wallet to another active wallet.

POST /api/v1/wallets/transfer

{
  "destinationWalletAddress": "MARIEPAY001_SETTLEMENT",
  "amount": "1000.00",
  "transactionReference": "SETTLE-001",
  "externalReference": "ORDER-001",
  "description": "TeraPay settlement to MariePay"
}

Reserve Funds

Locks funds in the authenticated participant wallet. Available balance decreases and locked balance increases.

POST /api/v1/wallets/reserve

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

Release Funds

Releases a reservation back to the source wallet when a payment is cancelled or fails.

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.

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.

POST /api/v1/wallets/settlements/multiparty

{
  "settlementReference": "MP-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"
    }
  ]
}

Webhooks

POST /api/v1/webhooks/subscriptions

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

Explorer and Proofs

GET /rpc/tx/{hash}

GET /rpc/proof/{hash}

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

SDKs

.NET

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

await client.TransferAsync(new WalletTransferRequest {
    DestinationWalletAddress = "MARIEPAY001_SETTLEMENT",
    Amount = "1000.00",
    TransactionReference = "SETTLE-001"
});

Python

from sierrachain import SierraChainClient

client = SierraChainClient("YOUR_API_KEY", "https://api.sierrachain.io")
client.transfer(
    destination_wallet_address="MARIEPAY001_SETTLEMENT",
    amount="1000.00",
    transaction_reference="SETTLE-001"
)

Node.js

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

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

await client.transfer({
  destinationWalletAddress: "MARIEPAY001_SETTLEMENT",
  amount: "1000.00",
  transactionReference: "SETTLE-001"
});

Error Codes

Pilot Go-live Checklist

• Configure DNS: api.sierrachain.io, docs.sierrachain.io, explorer.sierrachain.io.
• Install SSL certificates.
• Rotate development secrets and database password.
• Run backup restore test.
• Complete TeraPay integration test.
• Decide wallet policy: internal-only or partner-visible.
• Freeze features for pilot launch.