VCP Explorer API v1.1 - VeritasChain Standards Organization

Overview

The VCP Explorer API provides event search, Merkle proof retrieval, and event certificate generation for the VeritasChain Protocol (VCP). It is fully aligned with VCP Specification v1.0 and enables external parties (regulators, brokers, prop firms, auditors) to independently verify logged events.

Cryptographic Verification

RFC 6962-compliant Merkle proofs 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.

Regulatory Certificates

Generate audit-ready certificates containing event data, Merkle proofs, and cryptographic signatures for compliance.

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 immutability guarantees.

Base URL

https://explorer.veritaschain.org/api/v1

Note: The Explorer API deployment is in progress. Until the live endpoint is available, this documentation serves as the implementation reference. Developers should not attempt to call these endpoints until deployment is announced.

Authentication

All API requests require authentication using an API key in the request header:

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 regulatory-grade certificate containing event data, Merkle proof, signature metadata, and verification results.

Use Cases

Regulator Audits: Provide verifiable evidence of algorithmic trading events
Payout Disputes: Prove 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 (coming soon)"
}

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
20	`ALG`	Algorithm update	Governance
21	`RSK`	Risk parameter change	Risk
98	`HBT`	Heartbeat	System
99	`ERR`	Error	System
100	`SNC`	Sync event	System
101	`REC`	Recovery event	System

Merkle Proof Verification Guide

The VCP Explorer API follows RFC 6962 Certificate Transparency standard for Merkle tree proofs. 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: str, audit_path: list, expected_root: str) -> bool:
    """
    Verify Merkle inclusion proof (RFC 6962).
    
    Args:
        event_hash: SHA-256 hash of the event (leaf node)
        audit_path: List of sibling hashes from leaf to root
        expected_root: Expected Merkle root hash
    
    Returns:
        True if proof is valid, False otherwise
    """
    current_hash = event_hash
    
    for sibling_hash in audit_path:
        # Concatenate in sorted order (canonical)
        if current_hash < sibling_hash:
            combined = current_hash + sibling_hash
        else:
            combined = sibling_hash + current_hash
        
        # Hash the concatenation
        current_hash = sha256(combined)
    
    # Compare computed root with expected root
    return current_hash == expected_root

Why This Matters: This verification process ensures that events cannot be tampered with after being logged. The blockchain anchor provides an additional layer of immutability, as the Merkle root is permanently recorded on Ethereum mainnet.

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

Event Metadata: event_id, timestamp, event type, trading symbol
Trading Details: order data, execution prices, volumes
Risk Data: active risk parameters, triggered controls
Governance Data: algorithm ID, model hash, decision factors
Cryptographic Proof: event hash, Merkle proof, digital signature
Blockchain Anchor: network, transaction hash, block number
Verification Result: automated verification status
Certificate Metadata: certificate ID, issuer, timestamp

When to Use Certificates

Regulatory Compliance

Submit to financial authorities as evidence of trading transparency and algorithmic governance.

Dispute Resolution

Provide cryptographic proof of execution timing and pricing in payout disputes.

Third-Party Audits

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

VC-Certified Proof

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

Certificate Format: Certificates are available in both JSON and PDF formats. PDF certificates include QR codes linking to online verification.

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