Cerulea › Introduction

API v1.0 · June 2026

API Reference

API Documentation

Full programmatic access to the Cerulea platform. REST for resource management, JSON-RPC 2.0 for direct blockchain interaction.

15Sections

REST + RPCProtocols

EnterpriseGrade

Introduction

The Cerulea API provides programmatic access to all platform capabilities — from deploying blockchain networks and managing smart contracts to querying real-time metrics and configuring governance. The API combines RESTful endpoints for resource management with JSON-RPC 2.0 for direct blockchain interaction.

⬡

Complete dApps

Build full-stack dApps with smart contracts, tokens, and frontend interfaces.

⛓

Private Blockchains

Deploy custom blockchain networks with configurable consensus mechanisms.

◈

Validator Management

Manage validators, governance, and network parameters programmatically.

◉

Real-time Monitoring

Query and stream live blockchain performance data and analytics.

⚙

Modular Architecture

Enable and configure DeFi, NFT, DAO, and identity modules via API.

↑

CI/CD Integration

Automate deployments and upgrades with GitHub integration support.

API Architecture

Cerulea uses a hybrid architecture combining RESTful endpoints for resource management with JSON-RPC 2.0 for blockchain interactions — intuitive REST for infrastructure management, powerful RPC for direct blockchain operations.

REST API

Resource creation and management
Authentication and access control
Workspace and project operations
Webhook registration

JSON-RPC 2.0

Direct blockchain interaction
Block and transaction queries
Contract execution and calls
Transaction simulation

Base URL: https://api.cerulea.app/v1 — All REST endpoints are prefixed with this base. The RPC endpoint is POST /rpc.

Authentication

Cerulea uses a dual authentication system — API keys for server-to-server communication and OAuth 2.0 for user-facing applications and third-party integrations.

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 and modify workspaces
`blockchain:read`	Query blockchain data
`blockchain:write`	Deploy and manage blockchains
`blockchain:deploy`	Deploy smart contracts
`validator:read`	View validators
`validator:write`	Manage validators
`governance:read`	View governance proposals
`governance:write`	Create and vote on proposals
`admin`	Full administrative access

III

Core REST API

Standard Response Format

All API responses follow a consistent envelope structure.

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. All RPC calls are sent as POST /rpc with a JSON body.

POST/rpc

Execute a JSON-RPC 2.0 method

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 and status
blockchain.getBalance — Get account balance at a given block
transaction.send — Broadcast a signed transaction
transaction.simulate — Dry-run a transaction without broadcasting
contract.call — Read-only contract call (no gas)
contract.execute — Execute a state-changing contract method

Webhooks

Receive real-time signed payloads when events occur in your blockchain infrastructure. Cerulea delivers HTTP POST requests to your endpoint with a HMAC-SHA256 signature for verification.

POST/webhooks

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 added to the chain
`blockchain.transaction.confirmed`	Transaction confirmed on-chain
`contract.deployed`	Smart contract successfully deployed
`contract.event.emitted`	Contract event emitted
`validator.status.changed`	Validator joined, left, or changed status
`governance.proposal.created`	New governance proposal submitted

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)
  );
}

Workspaces

Organise your blockchain infrastructure into workspaces and projects. A workspace is the top-level container for all resources, team members, and billing.

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",
  "template": "defi-dex",
  "config": {
    "blockchain": "ethereum",
    "network": "mainnet",
    "features": ["swap", "liquidity-pools", "staking"]
  }
}

VII

dApp Builder

Build complete decentralised applications with no code required. The dApp Builder API composes components into a fully deployable application with frontend, contracts, and backend logic.

POST/dapps

Create and configure 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" }
    }
  ],
  "frontend": { "theme": "modern-dark", "customDomain": "mydefi.com" }
}

Available Components

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

VIII

Private Blockchains

Deploy and manage custom private blockchain networks with full control over consensus, validators, and runtime configuration.

POST/blockchains

Create a new private blockchain network

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; standard for enterprise deployments
proof-of-stake (PoS) — Stake-based validator selection
delegated-proof-of-stake (DPoS) — Community-elected validator set
pbft — Practical Byzantine Fault Tolerance for high-throughput private networks
raft — Raft consensus for private networks requiring simple, stable leader election

Smart Contracts

POST/contracts/deploy

Deploy a smart contract from a managed 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 (ERC-20)
`erc721-nft`	Non-fungible token (ERC-721)
`erc1155-multi`	Multi-token standard (ERC-1155)
`governance-dao`	DAO with on-chain voting
`staking-pool`	Token staking with reward distribution
`marketplace`	NFT marketplace with royalties

Validators

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 real-time validator status and uptime
PUT /validators/:id/stake — Update validator stake amount
POST /validators/:id/slash — Apply slash penalty for misbehaviour
DELETE /validators/:id — Remove a validator from the active set

Governance

POST/governance/proposals

Create a new on-chain 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

Submit a vote on an active proposal

json

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

XII

Modules

Enable and configure blockchain modules to add specific capabilities to a deployed network. Modules are provisioned at genesis or via governance upgrade.

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 infrastructure
`dao`	DAO governance and on-chain voting
`bridge`	Cross-chain bridge functionality
`oracle`	Price oracle integration (Chainlink-compatible)
`identity`	Decentralised identity (DID) framework
`privacy`	Zero-knowledge proof support
`storage`	Decentralised storage (IPFS-compatible)

XIII

Tokens

POST/tokens

Create and configure a new token on a deployed blockchain

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; standard for utility and governance tokens
ERC721 — Non-fungible tokens (NFTs); unique digital assets
ERC1155 — Multi-token standard; fungible and non-fungible in a single contract
ERC4626 — Tokenised vault standard for yield-bearing assets

XIV

Monitoring

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 time-series blockchain 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 for the requested operation
404	`NOT_FOUND`	Resource not found
422	`VALIDATION_ERROR`	Request body failed validation
429	`RATE_LIMITED`	Rate limit exceeded — retry after the indicated delay
500	`INTERNAL_ERROR`	Internal server error