API Documentation

Build complete dApps and private blockchains with no code required

Production ReadyEnterprise GradeNo Code Required

Introduction

Welcome to the Cerulea API documentation. Cerulea is a production-grade, no-code blockchain infrastructure platform that enables developers and enterprises to build fully functional decentralized applications (dApps) and private blockchain networks without writing a single line of blockchain code.

Complete dApps

Build full-stack dApps with smart contracts, tokens, and frontends

Private Blockchains

Deploy custom blockchain networks with configurable consensus

Validator Management

Manage validators, governance, and network parameters

Modular Architecture

Configure modules for DeFi, NFTs, DAOs, and more

Real-time Monitoring

Monitor and analyze blockchain performance in real-time

CI/CD Integration

Automated deployments with GitHub integration

API Architecture

The Cerulea API follows a hybrid architecture combining RESTful endpoints for resource management and JSON-RPC for blockchain interactions. This provides intuitive REST APIs for infrastructure management and powerful RPC methods for blockchain operations.

Authentication & Authorization

Cerulea uses a dual authentication system for maximum security and flexibility:

API Key Authentication

For server-to-server communication and automated workflows.

POST/auth/api-keys

Create a new API key with custom scopes and expiration

bash

curl -X POST https://api.cerulea.app/v1/auth/api-keys \
  -H "Authorization: Bearer <your_oauth_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API Key",
    "scopes": ["workspace:read", "workspace:write", "blockchain:deploy"],
    "expiresIn": "90d"
  }'

Security Best Practice: Include the API key in the X-API-Key header for all requests. Never expose API keys in client-side code.

bash

curl -X GET https://api.cerulea.app/v1/workspaces \
  -H "X-API-Key: crla_live_xxxxxxxxxxxxxxxxxxx"

OAuth 2.0

For user-facing applications and third-party integrations.

bash

# Step 1: Redirect user to authorization endpoint
https://api.cerulea.app/v1/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_CALLBACK_URL&
  response_type=code&
  scope=workspace:read blockchain:write&
  state=RANDOM_STATE_STRING

# Step 2: Exchange code for access token
curl -X POST https://api.cerulea.app/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=YOUR_CALLBACK_URL" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Available Scopes

Scope	Description
`workspace:read`	Read workspace data
`workspace:write`	Create/modify workspaces
`blockchain:read`	Query blockchain data
`blockchain:write`	Deploy/manage blockchains
`blockchain:deploy`	Deploy smart contracts
`validator:read`	View validators
`validator:write`	Manage validators
`governance:read`	View proposals
`governance:write`	Create/vote on proposals
`admin`	Full administrative access

Core REST API

Standard Response Format

json

{
  "success": true,
  "data": { /* resource data */ },
  "meta": {
    "requestId": "req_xxxxxxxx",
    "timestamp": "2025-02-25T10:30:00Z"
  }
}

Pagination

GET/resources?page=1&limit=50&sort=created_at:desc

List resources with pagination and sorting

json

{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 250,
    "totalPages": 5,
    "hasNext": true,
    "hasPrev": false
  }
}

Health Check

GET/health

Check API health and service status

json

{
  "status": "operational",
  "version": "1.0.0",
  "uptime": 99.99,
  "services": {
    "database": "healthy",
    "blockchain": "healthy",
    "storage": "healthy"
  }
}

RPC Methods

JSON-RPC 2.0 endpoint for direct blockchain interactions

POST/rpc

Execute JSON-RPC methods

json

{
  "jsonrpc": "2.0",
  "method": "blockchain.getBlock",
  "params": {
    "blockchainId": "bc_xxxxxxxx",
    "blockNumber": "latest"
  },
  "id": 1
}

Available Methods

blockchain.getBlock - Get block by number or hash
blockchain.getTransaction - Get transaction details
blockchain.getBalance - Get account balance
transaction.send - Send signed transaction
transaction.simulate - Simulate transaction execution
contract.call - Read-only contract call
contract.execute - Execute contract method

Webhooks

Receive real-time notifications when events occur in your blockchain infrastructure

POST/webhooks

Create a new webhook

json

{
  "url": "https://your-domain.com/webhook",
  "events": [
    "blockchain.block.created",
    "blockchain.transaction.confirmed",
    "contract.event.emitted",
    "validator.status.changed"
  ],
  "secret": "whsec_xxxxxxxxxxxxxxxx",
  "enabled": true,
  "filters": {
    "blockchainId": "bc_abc123"
  }
}

Webhook Events

Event Type	Description
`blockchain.block.created`	New block mined
`blockchain.transaction.confirmed`	Transaction confirmed
`contract.deployed`	Smart contract deployed
`contract.event.emitted`	Contract event emitted
`validator.status.changed`	Validator status changed
`governance.proposal.created`	New proposal created

Webhook Signature Verification

javascript

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

Workspace & Project Management

Organize your blockchain infrastructure into workspaces and projects

POST/workspaces

Create a new workspace

json

{
  "name": "Production Environment",
  "description": "Production blockchain infrastructure",
  "settings": {
    "defaultNetwork": "mainnet",
    "billingPlan": "enterprise"
  },
  "members": [
    {
      "email": "admin@company.com",
      "role": "admin"
    }
  ]
}

POST/workspaces/:workspaceId/projects

Create a new project within a workspace

json

{
  "name": "DeFi Exchange",
  "type": "dapp",
  "description": "Decentralized exchange platform",
  "template": "defi-dex",
  "config": {
    "blockchain": "ethereum",
    "network": "mainnet",
    "features": ["swap", "liquidity-pools", "staking"]
  }
}

dApp Builder API

Build complete decentralized applications with no code required

POST/dapps

Create a new dApp

json

{
  "name": "MyDeFi Platform",
  "workspaceId": "ws_xxxxxxxx",
  "template": "defi-platform",
  "components": [
    {
      "type": "token",
      "config": {
        "name": "Platform Token",
        "symbol": "PLAT",
        "totalSupply": "1000000000",
        "decimals": 18,
        "features": ["burnable", "mintable", "pausable"]
      }
    },
    {
      "type": "staking",
      "config": {
        "stakingToken": "PLAT",
        "rewardRate": "5",
        "lockPeriod": "30d"
      }
    },
    {
      "type": "governance",
      "config": {
        "votingToken": "PLAT",
        "proposalThreshold": "100000",
        "votingPeriod": "7d"
      }
    }
  ],
  "frontend": {
    "theme": "modern-dark",
    "customDomain": "mydefi.com"
  }
}

Available Components

Component	Description
`token`	Fungible or non-fungible tokens
`staking`	Token staking mechanism
`liquidity-pool`	DEX liquidity pools
`lending`	Lending/borrowing protocol
`governance`	DAO governance system
`nft-marketplace`	NFT marketplace
`auction`	Auction mechanism
`multisig`	Multi-signature wallet

Private Blockchain Networks

Deploy and manage custom private blockchain networks with full control

POST/blockchains

Create a new private blockchain

json

{
  "name": "Enterprise Blockchain",
  "type": "private",
  "consensus": "proof-of-authority",
  "chainId": 12345,
  "config": {
    "blockTime": "5s",
    "blockGasLimit": "30000000",
    "nativeToken": {
      "name": "Enterprise Coin",
      "symbol": "ENT",
      "premine": "1000000000"
    }
  },
  "validators": [
    {
      "address": "0x1234...",
      "name": "Validator Node 1"
    }
  ],
  "features": ["smart-contracts", "permissions", "privacy"]
}

Consensus Mechanisms

proof-of-authority (PoA) - Permissioned validators
proof-of-stake (PoS) - Stake-based validation
delegated-proof-of-stake (DPoS) - Elected validators
pbft - Practical Byzantine Fault Tolerance
raft - Raft consensus for private networks

Smart Contract Management

POST/contracts/deploy

Deploy a smart contract from template

json

{
  "blockchainId": "bc_abc123",
  "template": "erc20-token",
  "params": {
    "name": "My Token",
    "symbol": "MTK",
    "totalSupply": "1000000",
    "decimals": 18
  },
  "from": "0x1234...",
  "gasLimit": "2000000"
}

Contract Templates

Template	Description
`erc20-token`	Standard fungible token
`erc721-nft`	Non-fungible token
`erc1155-multi`	Multi-token standard
`governance-dao`	DAO with voting
`staking-pool`	Staking rewards
`marketplace`	NFT marketplace

Validator Management

POST/blockchains/:blockchainId/validators

Add a new validator to the network

json

{
  "address": "0xabcdef123456...",
  "name": "Node-US-East-1",
  "stake": "100000",
  "commission": "5",
  "metadata": {
    "location": "US-East",
    "provider": "AWS"
  }
}

Validator Operations

GET /validators/:id/status - Get validator status
PUT /validators/:id/stake - Update stake amount
POST /validators/:id/slash - Slash validator (penalty)
DELETE /validators/:id - Remove validator

Governance Proposals

POST/governance/proposals

Create a new governance proposal

json

{
  "blockchainId": "bc_abc123",
  "title": "Increase Block Size",
  "description": "Proposal to increase block size from 2MB to 4MB",
  "type": "parameter-change",
  "changes": {
    "blockSize": "4MB"
  },
  "votingPeriod": "7d",
  "quorum": "50",
  "threshold": "66.67"
}

POST/governance/proposals/:proposalId/vote

Vote on a proposal

json

{
  "vote": "yes",
  "weight": "1000000",
  "reason": "This change will improve network throughput"
}

Module Configuration

Enable and configure blockchain modules for specific functionality

POST/blockchains/:blockchainId/modules

Enable a module on your blockchain

json

{
  "module": "defi",
  "config": {
    "features": ["dex", "lending", "staking"],
    "swapFee": "0.3",
    "liquidationThreshold": "75"
  }
}

Available Modules

Module	Features
`defi`	DeFi protocols (DEX, lending, staking)
`nft`	NFT minting and marketplace
`dao`	DAO governance and voting
`bridge`	Cross-chain bridge functionality
`oracle`	Price oracle integration
`identity`	Decentralized identity (DID)
`privacy`	Zero-knowledge proofs
`storage`	Decentralized storage (IPFS)

Token Management

POST/tokens

Create a new token

json

{
  "blockchainId": "bc_abc123",
  "standard": "ERC20",
  "name": "Platform Token",
  "symbol": "PLAT",
  "decimals": 18,
  "totalSupply": "1000000000",
  "features": {
    "mintable": true,
    "burnable": true,
    "pausable": true
  },
  "distribution": [
    {
      "address": "0x1234...",
      "amount": "500000000",
      "vesting": {
        "duration": "24m",
        "cliff": "6m"
      }
    }
  ]
}

Token Standards

ERC20 - Fungible tokens
ERC721 - Non-fungible tokens (NFTs)
ERC1155 - Multi-token standard
ERC4626 - Tokenized vaults

Monitoring & Analytics

GET/blockchains/:blockchainId/metrics

Get real-time blockchain metrics

json

{
  "currentBlock": 123456,
  "blockTime": 5.2,
  "transactionsPerSecond": 150,
  "activeValidators": 21,
  "totalTransactions": 5000000,
  "networkHashrate": "500 TH/s",
  "averageGasPrice": "25 gwei"
}

GET/analytics/timeseries

Query historical data

Example: ?blockchainId=bc_abc123&metric=transactions&from=2025-02-01&to=2025-02-25&granularity=1h

Error Handling

Error Response Format

json

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient balance to complete transaction",
    "details": {
      "required": "1000000000000000000",
      "available": "500000000000000000"
    },
    "requestId": "req_abc123",
    "timestamp": "2025-02-25T10:30:00Z"
  }
}

Common Error Codes

HTTP Code	Error Code	Description
400	`BAD_REQUEST`	Invalid request parameters
401	`UNAUTHORIZED`	Invalid or missing authentication
403	`FORBIDDEN`	Insufficient permissions
404	`NOT_FOUND`	Resource not found
422	`VALIDATION_ERROR`	Validation failed
429	`RATE_LIMITED`	Rate limit exceeded
500	`INTERNAL_ERROR`	Internal server error

Support & Resources

Support Email

support@cerulea.app

Status Page

status.cerulea.app

Ready to start building? Check out our examples repository and start creating your blockchain infrastructure today.

API Documentation

Introduction

Complete dApps

Private Blockchains

Validator Management

Modular Architecture

Real-time Monitoring

CI/CD Integration

API Architecture

Authentication & Authorization

API Key Authentication

OAuth 2.0

Available Scopes

Core REST API

Standard Response Format

Pagination

Health Check

RPC Methods

Available Methods

Webhooks

Webhook Events

Webhook Signature Verification

Workspace & Project Management

dApp Builder API

Available Components

Private Blockchain Networks

Consensus Mechanisms

Smart Contract Management

Contract Templates

Validator Management

Validator Operations

Governance Proposals

Module Configuration

Available Modules

Token Management

Token Standards

Monitoring & Analytics

Error Handling

Error Response Format

Common Error Codes

Support & Resources

API Reference

Documentation

Whitepaper

Examples

Support Email

Status Page