Ledger API Overview

Base URL

Production: https://api.softquantus.com/api/v2/ledger
Sandbox:    https://sandbox.softquantus.com/api/v2/ledger

Authentication

All requests require Bearer token:

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

---

Endpoints Summary

Records

Method	Endpoint	Description
POST	/append	Append a new record
POST	/append/batch	Append multiple records
GET	/{record_id}	Get a record
GET	/list	List records
GET	/search	Search by metadata

Verification

Method	Endpoint	Description
GET	/{record_id}/verify	Verify record integrity
GET	/{record_id}/proof	Get Merkle proof
POST	/verify/batch	Verify multiple records

Chain

Method	Endpoint	Description
GET	/chain/status	Get chain status
GET	/chain/root	Get current Merkle root

---

Quick Examples

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"
    }
  }'

Response:

{
  "success": true,
  "data": {
    "record_id": "rec_abc123",
    "sequence": 1523,
    "hash": "sha3-256:7f83b165...",
    "previous_hash": "sha3-256:a2c4e6f8...",
    "timestamp": "2026-02-06T12:00:00.000000Z",
    "signature": {
      "algorithm": "ML-DSA-65",
      "value": "base64:..."
    }
  }
}

Get Record

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

Response:

{
  "success": true,
  "data": {
    "record_id": "rec_abc123",
    "sequence": 1523,
    "data": {
      "event": "user_login",
      "user_id": "user_123"
    },
    "metadata": {
      "category": "audit"
    },
    "hashes": {
      "data_hash": "sha3-256:abc...",
      "record_hash": "sha3-256:def...",
      "previous_hash": "sha3-256:ghi..."
    },
    "timestamp": {
      "time": "2026-02-06T12:00:00.000000Z",
      "authority": "softquantus-tsa",
      "proof": "base64:..."
    },
    "signature": {
      "algorithm": "ML-DSA-65",
      "public_key_id": "pk_xyz",
      "value": "base64:..."
    }
  }
}

Verify Record

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

Response:

{
  "success": true,
  "data": {
    "valid": true,
    "record_id": "rec_abc123",
    "verified_at": "2026-02-06T12:05:00Z",
    "checks": {
      "data_hash": "valid",
      "chain": "valid",
      "signature": "valid",
      "timestamp": "valid",
      "merkle": "valid"
    }
  }
}

Get Merkle Proof

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

Response:

{
  "success": true,
  "data": {
    "record_id": "rec_abc123",
    "record_hash": "sha3-256:abc...",
    "merkle_root": "sha3-256:xyz...",
    "path": [
      {"position": "left", "hash": "sha3-256:..."},
      {"position": "right", "hash": "sha3-256:..."},
      {"position": "left", "hash": "sha3-256:..."}
    ],
    "tree_size": 1523
  }
}

List Records

curl "https://api.softquantus.com/api/v2/ledger/list?limit=10&order=desc" \
  -H "Authorization: Bearer $QCOS_API_KEY"

Search Records

curl -X POST https://api.softquantus.com/api/v2/ledger/search \
  -H "Authorization: Bearer $QCOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {"category": "audit"},
    "from": "2026-02-01",
    "to": "2026-02-06",
    "limit": 100
  }'

---

Record Schema

{
  "record_id": "string",
  "sequence": "integer",

  "data": "object (any JSON)",
  "metadata": {
    "category": "string",
    "tags": ["string"],
    "custom": "any"
  },

  "hashes": {
    "data_hash": "sha3-256:hex",
    "record_hash": "sha3-256:hex",
    "previous_hash": "sha3-256:hex"
  },

  "timestamp": {
    "time": "ISO 8601 (microseconds)",
    "authority": "string",
    "proof": "base64"
  },

  "signature": {
    "algorithm": "ML-DSA-65",
    "public_key_id": "string",
    "value": "base64"
  }
}

---

Verification Checks

Check	Description
data_hash	Data matches its hash
chain	Previous hash links correctly
signature	PQC signature is valid
timestamp	TSA token is valid
merkle	Merkle proof is valid

---

Error Codes

Code	HTTP	Description
RECORD_NOT_FOUND	404	Record ID not found
CHAIN_BROKEN	500	Chain integrity failure (alert!)
VERIFICATION_FAILED	400	Record failed verification
DATA_TOO_LARGE	400	Data exceeds 1MB
RATE_LIMITED	429	Too many appends

---

Webhooks

Subscribe to ledger events:

curl -X POST https://api.softquantus.com/api/v2/webhooks \
  -H "Authorization: Bearer $QCOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "ledger.append",
    "url": "https://your-app.com/webhook"
  }'

Events:

• ledger.append - New record created
• ledger.verified - Record verified
• ledger.alert - Integrity alert (critical)

---

© 2024-2026 SoftQuantus Innovative OÜ