VCP Explorer API

Historical interface design — not a production service

Search, verify, and audit VCP event chains with cryptographic proofs.

View API on GitHub

Overview

The VCP Explorer API provides event search, Merkle proof retrieval, and event certificate generation for the VeritasChain Protocol (VCP). It was designed against VCP Specification v1.0 (not yet updated for v1.1 or v1.2, which make external anchoring and Policy Identification mandatory) and is intended to enable external parties (regulators, brokers, prop firms, auditors) to independently verify logged events.

Cryptographic Verification

Merkle proofs with RFC 6962 domain-separated hashing are designed to enable external verification without trusting the API. "Verify, Don't Trust" principle in action.

Advanced Search

Track complete transaction lifecycles with TraceID, filter by symbol, time range, event type, and algorithm ID.

Event Certificates

Generate verification certificates containing event data, Merkle proofs, and cryptographic signatures.

VCP Module Structure

Organized event data with VCP-TRADE, VCP-RISK, and VCP-GOV modules for clear separation of concerns.

Nanosecond Precision

String-based timestamps avoid JavaScript 2^53 limit, supporting true nanosecond-level precision.

Blockchain Anchoring (Planned)

Future versions of VCP Explorer will support anchoring audit roots to Ethereum for additional tamper-evidence.

Base URL

https://explorer.veritaschain.org/api/v1
Note: The Explorer API source is public. Ordinary API routes return mock data; the separate SDK Evidence Demo is available in the public Explorer. The production URLs and SDK-spec workflow illustrated here are not an available production service. Authentication middleware is not implemented in the published API.

Authentication

Historical interface design only: the API-key header below is not enforced by the published API, which has no authentication middleware. Do not treat this example as an access-control guarantee.

HTTP Header
X-VCP-API-Key: <your_api_key>
Security: Never expose API keys in client-side code. Always use server-side requests with proper key management.

API Endpoints

GET /v1/events

Search and filter VCP events by symbol, event type, trace_id, timestamps, and more.

Query Parameters

Parameter Type Required Description Example
symbol String No Trading symbol XAUUSD, EURUSD
event_type String No Event type name ORD, EXE, REJ
event_type_code Integer No Fixed VCP code (1-255) 2 (ORD), 4 (EXE)
trace_id UUID v7 No Transaction trace ID 01934e3a-6a1b-7c82...
start_time ISO8601 No Start of time range 2025-11-24T00:00:00Z
end_time ISO8601 No End of time range 2025-11-24T23:59:59Z
limit Integer No Max results (1-500) 20 (default)
offset Integer No Pagination offset 0 (default)

Example Request

cURL
GET https://explorer.veritaschain.org/api/v1/events?symbol=XAUUSD&limit=20

curl -H "X-VCP-API-Key: your_api_key" \
  "https://explorer.veritaschain.org/api/v1/events?symbol=XAUUSD&limit=20"

Example Response

JSON
{
  "events": [
    {
      "event_id": "01934e3a-7b2c-7f93-8f2a-1234567890ab",
      "type": "ORD",
      "event_type_code": 2,
      "timestamp": "2025-11-24T14:02:05.123456789Z",
      "venue": "XAUUSD_PROP",
      "symbol": "XAUUSD",
      "hash_prefix": "8f2a7b",
      "status": "ANCHORED"
    }
  ],
  "query": {
    "symbol": "XAUUSD",
    "limit": 20
  },
  "total": 42
}
GET /v1/events/{event_id}

Retrieve full event details by ID, including header, payload (VCP-TRADE, VCP-RISK, VCP-GOV), and security metadata.

Path Parameters

Parameter Type Description
event_id UUID v7 Unique event identifier

Example Request

cURL
curl -H "X-VCP-API-Key: your_api_key" \
  "https://explorer.veritaschain.org/api/v1/events/01934e3a-6a1b-7c82-9d1b-123456789abc"

Example Response

JSON (abbreviated)
{
  "header": {
    "event_id": "01934e3a-7b2c-7f93-8f2a-1234567890ab",
    "trace_id": "01934e3a-6a1b-7c82-9d1b-0987654321dc",
    "timestamp_int": "1732453325123456789",
    "timestamp_iso": "2025-11-24T14:02:05.123456789Z",
    "event_type": "ORD",
    "event_type_code": 2,
    "symbol": "XAUUSD"
  },
  "payload": {
    "trade_data": {
      "symbol": "XAUUSD",
      "side": "BUY",
      "order_type": "MARKET",
      "price": "2350.500",
      "order_size": "5.00"
    },
    "vcp_risk": {
      "snapshot": {
        "max_drawdown_limit": "10000.00",
        "exposure_utilization": "0.45"
      }
    },
    "vcp_gov": {
      "algo_id": "neural-scalper-v1.2",
      "algo_type": "AI_MODEL",
      "confidence_score": "0.92"
    }
  },
  "security": {
    "event_hash": "8f2a7b9d1b0c3e4f...",
    "merkle_root": "a1b2c3d4e5f6a7b8...",
    "signature": "MEUCIQDXyz123abc..."
  }
}
GET /v1/events/{event_id}/proof

Return VCP Merkle Inclusion Proof (RFC 6962-style) to enable external verification without trusting the API.

"Verify, Don't Trust": This endpoint enables independent verification of event authenticity using cryptographic proofs.

Example Request

cURL
curl -H "X-VCP-API-Key: your_api_key" \
  "https://explorer.veritaschain.org/api/v1/events/01934e3a-6a1b-7c82-9d1b-123456789abc/proof"

Example Response

JSON
{
  "event_id": "01934e3a-7b2c-7f93-8f2a-1234567890ab",
  "event_hash": "8f2a7b9d1b0c3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f",
  "merkle_proof": {
    "root_hash": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
    "leaf_index": 42,
    "audit_path": [
      "7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b",
      "9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d"
    ],
    "tree_size": 1024
  },
  "anchor": {
    "network": "ethereum-mainnet",
    "tx_hash": "0x1234567890abcdef...",
    "block_number": 1942055
  }
}
GET /v1/events/{event_id}/certificate

Generate a verification certificate containing event data, Merkle proof, signature metadata, and verification results.

Use Cases

  • Regulator Audits: Provide verifiable evidence of algorithmic trading events
  • Payout Disputes: Provide verifiable evidence of execution authenticity and timing
  • Compliance Reports: Generate audit trails for financial authorities
  • Third-Party Verification: Enable independent verification by external parties

Example Request

cURL
curl -H "X-VCP-API-Key: your_api_key" \
  "https://explorer.veritaschain.org/api/v1/events/01934e3a-6a1b-7c82-9d1b-123456789abc/certificate"

Example Response

JSON
{
  "certificate_id": "cert_01934e3a_7b2c_7f93",
  "event_id": "01934e3a-7b2c-7f93-8f2a-1234567890ab",
  "verified": true,
  "issued_at": "2025-11-25T12:00:00Z",
  "issuer": "VSO VCP Explorer v1.1",
  "verification": {
    "event_hash": "8f2a7b9d1b0c3e4f...",
    "merkle_root": "a1b2c3d4e5f6a7b8...",
    "signature_valid": true,
    "blockchain_anchored": true,
    "anchor_block": 1942055
  },
  "event_summary": {
    "timestamp": "2025-11-24T14:02:05.123456789Z",
    "event_type": "ORD",
    "symbol": "XAUUSD",
    "side": "BUY",
    "price": "2350.500"
  },
  "certificate_url": "https://explorer.veritaschain.org/certificates/cert_01934e3a_7b2c_7f93.pdf"
}

Event Types Reference

VCP Specification v1.0 defines fixed event type codes for consistency across implementations:

Code Type Description Category
1 SIG Signal/Decision generated Trading
2 ORD Order sent Trading
3 ACK Order acknowledged Trading
4 EXE Full execution Trading
5 PRT Partial fill Trading
6 REJ Order rejected Trading
7 CXL Order cancelled Trading
8 MOD Order modified Trading
9 CLS Position closed Trading
20 ALG Algorithm update Governance
21 RSK Risk parameter change Governance
22 AUD Audit request Governance
98 HBT Heartbeat System
99 ERR Error System
100 REC Recovery System
101 SNC Clock sync status System

Merkle Proof Verification Guide

The VCP Explorer API uses Merkle proofs with the domain-separated hashing of RFC 6962 (Certificate Transparency). This enables anyone to independently verify event authenticity without trusting the API.

Verification Steps

1. Fetch Event

Retrieve the full event details using GET /v1/events/:id. Extract the event_hash from the security section.

2. Fetch Proof

Get the Merkle proof using GET /v1/events/:id/proof. This contains the audit path and root hash.

3. Compute Root

Combine event_hash with audit_path using SHA-256 in a binary Merkle tree structure.

4. Verify Root

Compare computed root with returned merkle_root. If they match, the event is verified.

Pseudo-code Implementation

Python-like Pseudocode
def verify_merkle_proof(event_hash: bytes, leaf_index: int, audit_path: list, expected_root: bytes) -> bool:
    """
    Verify a Merkle inclusion proof with RFC 6962 domain separation
    (VCP v1.1 section 6.2: leaf = SHA-256(0x00 || data), node = SHA-256(0x01 || left || right)).
    
    As written, this sketch is valid when the batch size (tree_size) is a power of two.
    For other sizes the pairing follows the tree construction of VCP v1.1 section 6.2.1,
    in which the last node of an odd level is hashed with itself.
    
    Args:
        event_hash: EventHash of the event (the leaf input), as bytes
        leaf_index: Position of the event in the batch (from the proof)
        audit_path: List of sibling hashes from leaf to root, as bytes
        expected_root: Expected Merkle root hash, as bytes
    
    Returns:
        True if proof is valid, False otherwise
    """
    index = leaf_index
    current_hash = sha256(b"\x00" + event_hash)   # leaf prefix
    
    for sibling_hash in audit_path:
        # Order is positional (left/right from the leaf index), never sorted
        if index % 2 == 1:   # current node is a right child
            current_hash = sha256(b"\x01" + sibling_hash + current_hash)
        else:                # current node is a left child
            current_hash = sha256(b"\x01" + current_hash + sibling_hash)
        index //= 2
    
    # Compare computed root with expected root
    return current_hash == expected_root
Why This Matters: This verification process makes tampering with events detectable once their Merkle root has been published or anchored. External anchoring of the root (to Ethereum) is planned and is not yet available in the Explorer.

Event Certificate Guide

Event certificates provide a comprehensive, audit-ready package containing all verification data in a single document.

What's Included in a Certificate

When to Use Certificates

Regulatory Inquiries

A certificate could be provided to an authority as supporting technical material; no authority has accepted or recognised such certificates.

Dispute Resolution

Provide verifiable cryptographic evidence of execution timing and pricing in payout disputes.

Third-Party Audits

Enable external auditors to verify trading events without accessing live systems.

VC-Certified Evidence

Demonstrate VCP compliance for VeritasChain Certified (VC-Certified) applications.

Certificate Format: Certificates are returned as JSON. PDF certificates with QR codes: Planned — no date set.

HTTP Status Codes

Status Meaning Description
200 OK Request succeeded
400 Bad Request Invalid request parameters or malformed JSON
401 Unauthorized Invalid or missing API key
404 Not Found Event ID not found
429 Too Many Requests Rate limit exceeded
500 Server Error Internal server error

Related Resources

VCP Specification v1.0

Complete technical specification for the VeritasChain Protocol.

View Specification

VCP Explorer API GitHub

Source code and implementation reference for the Explorer API.

View Repository

Conformance Test Guide v1.0

Test procedures and checklists for VCP v1.0 implementations (a guide; no test tooling is published).

View Conformance Guide

VCP Example Payloads

Sample event payloads for various trading scenarios.

View Examples

VeritasChain Certified (VC-Certified)

Apply for VC-Certified status: a VSO-approved Conformity Assessment Body assesses your system's conformance to the VCP specification.

Learn About Certification

VSO Home

VeritasChain Standards Organization main website.

Visit VSO