API Overview

Cloud Service provides multiple APIs for interacting with the blockchain, building applications, and integrating with services.

Available APIs

API	Protocol	Use Case	Port
JSON-RPC	HTTP POST	Node management, wallet operations	16180
REST API	HTTP GET	Blockchain data, transactions	16180
WebSocket	WS	Real-time notifications	16181
ZeroMQ	ZMQ	Event streaming	Configurable

Quick Start

Enable APIs

Add to your cs.conf:

# Enable JSON-RPC
server=1
rpcuser=your_username
rpcpassword=your_password
rpcport=16180
rpcallowip=127.0.0.1

# Enable REST API
rest=1

# Enable WebSocket
wsport=16181

# Enable ZeroMQ
zmqpubrawblock=tcp://127.0.0.1:28332
zmqpubrawtx=tcp://127.0.0.1:28333
zmqpubhashblock=tcp://127.0.0.1:28334

Authentication

All API requests require authentication:

# Basic authentication
curl -u your_username:your_password \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc": "1.0", "id": "curl", "method": "getblockchaininfo", "params": []}' \
     http://localhost:16180/

JSON-RPC API

The JSON-RPC API provides full access to node and wallet functionality.

Request Format

{
    "jsonrpc": "1.0",
    "id": "request_id",
    "method": "method_name",
    "params": [param1, param2, ...]
}

Response Format

{
    "result": { ... },
    "error": null,
    "id": "request_id"
}

Example: Get Blockchain Info

curl -u user:password \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc": "1.0", "id": "1", "method": "getblockchaininfo", "params": []}' \
     http://localhost:16180/

Response:

{
    "result": {
        "chain": "main",
        "blocks": 524288,
        "headers": 524288,
        "bestblockhash": "0000000000000000000...",
        "difficulty": 12345678.90123456,
        "mediantime": 1234567890,
        "verificationprogress": 0.999999,
        "chainwork": "0000000000000000000000000000000000000000000000000000000000000000",
        "pruned": false
    },
    "error": null,
    "id": "1"
}

REST API

The REST API provides simple HTTP endpoints for blockchain data.

Endpoints

Endpoint	Description
/rest/chaininfo	Blockchain information
/rest/block/<hash>	Block details
/rest/tx/<txid>	Transaction details
/rest/address/<address>	Address information
/rest/mempool/info	Mempool information
/rest/mempool/contents	Mempool transactions

Example: Get Block

curl http://localhost:16180/rest/block/0000000000000000000.json

Example: Get Transaction

curl http://localhost:16180/rest/tx/txid.json

WebSocket API

Real-time notifications for blockchain events.

Connection

const ws = new WebSocket('ws://localhost:16181');

ws.on('open', () => {
    console.log('Connected to Cloud Service WebSocket');
});

ws.on('message', (data) => {
    console.log('Received:', JSON.parse(data));
});

Subscriptions

// Subscribe to new blocks
{"action": "subscribe", "channel": "new-blocks"}

// Subscribe to address transactions
{"action": "subscribe", "channel": "address-tx", "address": "csc1q..."}

// Subscribe to mempool
{"action": "subscribe", "channel": "mempool"}

ZeroMQ

Event streaming for high-throughput applications.

Configuration

# cs.conf
zmqpubrawblock=tcp://127.0.0.1:28332
zmqpubrawtx=tcp://127.0.0.1:28333
zmqpubhashblock=tcp://127.0.0.1:28334
zmqpubrawtx=tcp://127.0.0.1:28335

Python Example

import zmq
import struct

context = zmq.Context()
socket = context.socket(zmq.SUB)
socket.connect("tcp://127.0.0.1:28332")
socket.setsockopt(zmq.SUBSCRIBE, b"rawtx")

while True:
    message = socket.recv_multipart()
    topic = message[0]
    body = message[1]
    print(f"Received {topic}: {body[:20].hex()}...")

SDKs and Libraries

Official SDKs

Language	Package	Repository
JavaScript	@cscoin/sdk	GitHub
Python	cs-python	GitHub
Go	go-cscoin	GitHub
Rust	cs-rust	GitHub

JavaScript Example

const { Cloud Service } = require('@cscoin/sdk');

const csc = new Cloud Service({
    host: 'localhost',
    port: 16180,
    user: 'your_username',
    pass: 'your_password'
});

// Get blockchain info
const info = await csc.getBlockchainInfo();
console.log(info);

// Send transaction
const txid = await csc.sendToAddress('csc1q...', 10.5);
console.log(txid);

Python Example

from cscoin import Cloud Service

csc = Cloud Service(
    host='localhost',
    port=16180,
    user='your_username',
    password='your_password'
)

# Get blockchain info
info = csc.get_blockchain_info()
print(info)

# Send transaction
txid = csc.send_to_address('csc1q...', 10.5)
print(txid)

Rate Limiting

Endpoint	Limit
JSON-RPC	100 requests/minute
REST API	200 requests/minute
WebSocket	1000 messages/minute
ZeroMQ	Unlimited (local)

Error Handling

Common Errors

Code	Error	Description
-1	Invalid request	Malformed JSON-RPC
-32601	Method not found	Unknown method
-5	Invalid address	Invalid address format
-6	Insufficient funds	Not enough balance
-8	Invalid parameter	Wrong parameter type

Error Response

{
    "result": null,
    "error": {
        "code": -6,
        "message": "Insufficient funds"
    },
    "id": "1"
}

Next Steps

• RPC Commands — Complete RPC reference
• REST API — REST endpoints
• WebSockets — Real-time notifications