REST API - Immutable Ledger & Merkle Tree Proof Generation

Overview

The VeilChain REST API provides programmatic access to create and manage immutable ledgers with merkle trees. Build tamper-proof audit logs and generate cryptographic proofs for data integrity verification. All endpoints return JSON and use standard HTTP response codes.

Base URL: https://api.veilchain.io/v1 (or your self-hosted instance)

Authentication

All API requests require a Bearer token:

Authorization: Bearer YOUR_API_KEY

Ledgers

List Ledgers

GET /ledgers

Returns all ledgers accessible to your API key.

Response:

{
  "ledgers": [
    {
      "id": "ldg_abc123",
      "name": "audit-logs",
      "description": "Application audit trail",
      "size": 1247,
      "root": "3a7f4c2b...",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T14:22:00Z"
    }
  ]
}

Create Ledger

POST /ledgers

Request Body:

{
  "name": "audit-logs",
  "description": "Application audit trail"
}

Response: 201 Created

{
  "id": "ldg_abc123",
  "name": "audit-logs",
  "description": "Application audit trail",
  "size": 0,
  "root": "e3b0c442...",
  "createdAt": "2024-01-15T10:30:00Z"
}

Get Ledger

GET /ledgers/:id

Returns detailed information about a specific ledger.

Response:

{
  "id": "ldg_abc123",
  "name": "audit-logs",
  "description": "Application audit trail",
  "size": 1247,
  "root": "3a7f4c2b...",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T14:22:00Z"
}

Entries

Append Entry to Immutable Ledger

POST /ledgers/:id/entries

Appends a new entry to the tamper-proof merkle tree ledger. This operation is immutable - once an entry is added to the audit log, it cannot be modified or deleted, ensuring data integrity.

Request Body:

{
  "data": {
    "action": "user_login",
    "userId": "user_123",
    "ip": "192.168.1.1",
    "timestamp": "2024-01-15T14:22:00Z"
  },
  "idempotencyKey": "req_unique_123"
}

Response: 201 Created

{
  "id": "ent_def456",
  "index": 1247,
  "hash": "9f86d081...",
  "root": "3a7f4c2b...",
  "createdAt": "2024-01-15T14:22:00Z"
}

Headers:

X-Idempotency-Key - Optional. Prevents duplicate entries for the same request.

Append Batch

POST /ledgers/:id/entries/batch

Appends multiple entries atomically.

Request Body:

{
  "entries": [
    { "data": { "action": "event_1" } },
    { "data": { "action": "event_2" } },
    { "data": { "action": "event_3" } }
  ]
}

Response: 201 Created

{
  "entries": [
    { "id": "ent_001", "index": 1247, "hash": "..." },
    { "id": "ent_002", "index": 1248, "hash": "..." },
    { "id": "ent_003", "index": 1249, "hash": "..." }
  ],
  "root": "3a7f4c2b...",
  "startIndex": 1247,
  "count": 3
}

Get Entry

GET /ledgers/:id/entries/:index

Retrieves an entry by its index.

Response:

{
  "id": "ent_def456",
  "index": 1247,
  "hash": "9f86d081...",
  "data": {
    "action": "user_login",
    "userId": "user_123"
  },
  "createdAt": "2024-01-15T14:22:00Z"
}

Merkle Proofs

Get Merkle Inclusion Proof

GET /ledgers/:id/proofs/:index

Generates a cryptographic merkle proof that an entry exists in the immutable ledger. Use these tamper-proof proofs for data integrity verification.

Response:

{
  "leaf": "9f86d081...",
  "index": 1247,
  "proof": [
    "a1b2c3d4...",
    "e5f6g7h8...",
    "i9j0k1l2..."
  ],
  "directions": ["left", "right", "left"],
  "root": "3a7f4c2b...",
  "treeSize": 2048
}

Verify Proof (Offline)

Proofs can be verified entirely offline using the SDK:

import { MerkleTree, deserializeProof } from '@veilchain/core';

// Proof from API response
const serializedProof = { /* ... */ };

// Deserialize and verify
const proof = deserializeProof(serializedProof);
const isValid = MerkleTree.verify(proof);

Consistency Proofs

Get Consistency Proof

GET /ledgers/:id/consistency?from=1000&to=2000

Proves that the ledger at size from is a prefix of the ledger at size to. Used for auditing.

Response:

{
  "fromSize": 1000,
  "toSize": 2000,
  "fromRoot": "abc123...",
  "toRoot": "def456...",
  "proof": ["hash1...", "hash2...", "hash3..."]
}

Error Responses

All errors follow this format:

{
  "error": {
    "code": "LEDGER_NOT_FOUND",
    "message": "Ledger with id 'ldg_xyz' not found",
    "details": {}
  }
}

Common Error Codes:

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Missing or invalid API key
`FORBIDDEN`	403	API key lacks permission
`LEDGER_NOT_FOUND`	404	Ledger doesn’t exist
`ENTRY_NOT_FOUND`	404	Entry index out of bounds
`INVALID_REQUEST`	400	Malformed request body
`RATE_LIMITED`	429	Too many requests
`INTERNAL_ERROR`	500	Server error

Rate Limits

Plan	Requests/min	Entries/day
Free	60	1,000
Pro	600	100,000
Enterprise	Unlimited	Unlimited

Rate limit headers are included in all responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1705325520