🔌

ZC-1 API Documentation

Complete developer documentation for integrating with Zero-Blockchain ZC-1 consensus protocol. Access blockchain data, submit transactions, and monitor consensus events in real-time.

🚀 Quick Start

Get started with the ZC-1 API in minutes. Our RESTful endpoints and WebSocket connections provide full access to the ZC-1 consensus layer, transaction pool, and network state. 

# Install ZC-1 SDK
npm install @zero-blockchain/zc1-sdk

# Initialize client
const { ZC1Client } = require('@zero-blockchain/zc1-sdk');
const client = new ZC1Client({
    endpoint: 'https://api.zc1.zero-blockchain.xyz',
    apiKey: 'your-api-key'
});

# Get latest block
const block = await client.getLatestBlock();

🔐 Authentication

API Key Required: All API requests require a valid API key in the Authorization header.

Authentication is handled via API keys. Include your API key in the Authorization header of every request: 

curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     https://api.zc1.zero-blockchain.xyz/v1/blocks/latest

Getting API Keys

API keys can be generated through the ZC-1 Developer Dashboard or by contacting our team. Free tier includes 1,000 requests per day, with premium tiers available for production use.

⚡ Rate Limiting

Rate Limits: Free tier: 1,000 requests/day • Premium: 100,000 requests/day

Rate limits are enforced per API key. Exceeded limits return HTTP 429 with retry-after header. WebSocket connections count as one request per connection, not per message.

📡 Core API Endpoints

GET

Get Latest Block

/v1/blocks/latest

Retrieve the most recent finalized block with all transactions and consensus metadata.

GET

Get Block by Height

/v1/blocks/{height}

Fetch specific block by height including DAG references and BFT checkpoint data.

GET

Get Transaction

/v1/transactions/{hash}

Retrieve transaction details including status, gas usage, and finality confirmation.

POST

Submit Transaction

/v1/transactions

Submit signed transaction to the mempool for inclusion in next block.

GET

Account Balance

/v1/accounts/{address}/balance

Get account balance and nonce for transaction preparation.

GET

Network Status

/v1/network/status

Current network health, validator count, and consensus metrics.

🔗 Consensus API Endpoints

GET

Validator Set

/v1/consensus/validators

Current active validator set with stake weights and VRF committee assignments.

GET

DAG Structure

/v1/consensus/dag/{epoch}

DAG block references and ordering for specified consensus epoch.

GET

BFT Checkpoints

/v1/consensus/checkpoints

Recent BFT checkpoint history with finality confirmations.

GET

VRF Committee

/v1/consensus/committee/{round}

VRF-selected committee members for specific consensus round.

🔌 Real-time WebSocket API

Connect to live blockchain events via WebSocket for real-time updates on blocks, transactions, and consensus events.

WS

Block Stream

wss://api.zc1.zero-blockchain.xyz/v1/stream/blocks

Real-time stream of new blocks as they're finalized.

WS

Transaction Stream

wss://api.zc1.zero-blockchain.xyz/v1/stream/transactions

Live transaction updates including mempool and confirmation status.

WS

Consensus Events

wss://api.zc1.zero-blockchain.xyz/v1/stream/consensus

Consensus round events, committee selections, and finality updates.

WebSocket Example

const ws = new WebSocket('wss://api.zc1.zero-blockchain.xyz/v1/stream/blocks');

ws.onopen = function() {
    // Send authentication
    ws.send(JSON.stringify({
        'type': 'auth',
        'token': 'YOUR_API_KEY'
    }));
};

ws.onmessage = function(event) {
    const data = JSON.parse(event.data);
    if (data.type === 'new_block') {
        console.log('New block:', data.block);
    }
};

📋 Response Examples

Block Response

GET /v1/blocks/latest
{
  "height": 12345,
  "hash": "0x7d8a...",
  "timestamp": 1695984623,
  "proposer": "0x1a2b...",
  "transactions": [
    {
      "hash": "0x9c8d...",
      "from": "0x3e4f...",
      "to": "0x5a6b...",
      "value": "1000000000000000000",
      "gas_used": 21000,
      "status": "finalized"
    }
  ],
  "dag_refs": ["0x1a2b...", "0x3c4d..."],
  "consensus": {
    "checkpoint_hash": "0x5e6f...",
    "vrf_proof": "0x7g8h...",
    "finality_time": 1.2
  }
}

Transaction Submit Response

POST /v1/transactions
{
  "hash": "0x9c8d...",
  "status": "pending",
  "estimated_confirmation": 2.1,
  "mempool_position": 15
}

🛠️ SDKs and Libraries

Official SDKs available for popular programming languages with full ZC-1 API support, transaction signing, and real-time event handling.

🟨

JavaScript/Node.js

@zero-blockchain/zc1-sdk

🐍

Python

zc1-python-sdk

🦀

Rust

zc1-rust-client

☕

Java

zc1-java-sdk

🚀

Go

zc1-go-client

💎

Ruby

zc1-ruby-gem

⚠️ Error Handling

The API uses standard HTTP status codes and returns detailed error information in JSON format:

Error Response Format
{
  "error": {
    "code": 400,
    "message": "Invalid transaction format",
    "details": "Missing required field: gas_limit",
    "request_id": "req_1a2b3c4d"
  }
}

Common Error Codes

📞 Support & Resources

Need help integrating with the ZC-1 API? Our developer support team is here to assist: