Skip to main content

Ledger Quick Start

Create immutable records in 5 minutes.

Prerequisites​

Step 1: Install the SDK​

pip install qcos-sdk[ledger]

Step 2: Configure API Key​

export QCOS_API_KEY="qcos_live_your_key_here"

Step 3: Append Your First Record​

from qcos.ledger import LedgerClient

ledger = LedgerClient()

# Append a record
record = ledger.append(
    data={
        "event": "user_login",
        "user_id": "user_123",
        "ip_address": "192.168.1.100"
    }
)

print(f"Record ID: {record.record_id}")
print(f"Sequence: {record.sequence}")
print(f"Hash: {record.hash}")

Expected Output:

Record ID: rec_abc123
Sequence: 1
Hash: sha3-256:7f83b165...

Step 4: Retrieve a Record​

from qcos.ledger import LedgerClient

ledger = LedgerClient()

# Get a record
record = ledger.get("rec_abc123")

print(f"Data: {record.data}")
print(f"Created: {record.timestamp}")
print(f"Sequence: {record.sequence}")

Step 5: Verify a Record​

from qcos.ledger import LedgerClient

ledger = LedgerClient()

# Verify integrity
verification = ledger.verify("rec_abc123")

print(f"Valid: {verification.valid}")
print(f"Checks:")
print(f"  Chain: {verification.chain_valid}")
print(f"  Signature: {verification.signature_valid}")
print(f"  Timestamp: {verification.timestamp_valid}")

Expected Output:

Valid: True
Checks:
  Chain: True
  Signature: True
  Timestamp: True

Step 6: Get Merkle Proof​

from qcos.ledger import LedgerClient

ledger = LedgerClient()

# Get proof for third-party verification
proof = ledger.get_proof("rec_abc123")

print(f"Record hash: {proof.record_hash}")
print(f"Merkle root: {proof.merkle_root}")
print(f"Proof path: {len(proof.path)} nodes")

# Export proof for auditor
proof.export("audit_proof.json")

Step 7: List Records​

from qcos.ledger import LedgerClient

ledger = LedgerClient()

# List recent records
records = ledger.list(
    limit=10,
    order="desc"
)

for rec in records:
    print(f"{rec.sequence}: {rec.record_id} - {rec.timestamp}")

Step 8: Append with Metadata​

from qcos.ledger import LedgerClient

ledger = LedgerClient()

# Add categorization and tags
record = ledger.append(
    data={
        "event": "file_access",
        "file": "/data/sensitive.csv",
        "action": "read"
    },
    metadata={
        "category": "security",
        "severity": "info",
        "tags": ["audit", "file-access"]
    }
)

print(f"Record ID: {record.record_id}")

Complete Example​

#!/usr/bin/env python3
"""Ledger Complete Example"""

from qcos.ledger import LedgerClient

def main():
    ledger = LedgerClient()

    # 1. Append audit records
    print("Appending audit records...")

    records = []
    for i in range(3):
        record = ledger.append(
            data={
                "event": f"action_{i}",
                "timestamp": f"2026-02-06T12:0{i}:00Z"
            },
            metadata={"category": "demo"}
        )
        records.append(record)
        print(f"  Created: {record.record_id} (seq: {record.sequence})")

    # 2. Verify chain integrity
    print("\nVerifying chain integrity...")
    for record in records:
        result = ledger.verify(record.record_id)
        status = "✅" if result.valid else "❌"
        print(f"  {status} {record.record_id}")

    # 3. Get Merkle proof
    print("\nGenerating Merkle proof...")
    proof = ledger.get_proof(records[-1].record_id)
    print(f"  Record hash: {proof.record_hash[:32]}...")
    print(f"  Merkle root: {proof.merkle_root[:32]}...")
    print(f"  Proof depth: {len(proof.path)} nodes")

    # 4. Verify with Merkle proof
    print("\nVerifying with Merkle proof...")
    verified = proof.verify()
    print(f"  Proof valid: {verified}")

    # 5. Export for audit
    print("\nExporting audit report...")
    proof.export("audit_report.json")
    print("  Saved to audit_report.json")

    print("\n✅ Ledger workflow complete!")

if __name__ == "__main__":
    main()

REST API Direct Usage​

Append Record​

curl -X POST https://api.softquantus.com/api/v2/ledger/append \
  -H "Authorization: Bearer $QCOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {"event": "user_login", "user_id": "user_123"},
    "metadata": {"category": "audit"}
  }'

Get Record​

curl https://api.softquantus.com/api/v2/ledger/rec_abc123 \
  -H "Authorization: Bearer $QCOS_API_KEY"

Verify Record​

curl https://api.softquantus.com/api/v2/ledger/rec_abc123/verify \
  -H "Authorization: Bearer $QCOS_API_KEY"

Get Merkle Proof​

curl https://api.softquantus.com/api/v2/ledger/rec_abc123/proof \
  -H "Authorization: Bearer $QCOS_API_KEY"

Next Steps​

© 2024-2026 SoftQuantus Innovative OÜ