ChainOS API Reference

API Overview

ChainOS provides multiple API interfaces for interacting with the blockchain, including REST API, gRPC, and WebSocket endpoints. This reference guide covers the available endpoints, request formats, and response structures.

API Interfaces

ChainOS offers three primary API interfaces:

REST API

HTTP-based API for easy integration with web applications and services.

Default Port: 1317
Content Type: application/json
Authentication: None (use over HTTPS with proper access controls)

gRPC

High-performance RPC framework for efficient client-server communication.

Default Port: 9090
Protocol: Protocol Buffers over HTTP/2
Authentication: None (use with TLS and proper access controls)

WebSocket (Tendermint RPC)

Real-time event subscription and blockchain interaction.

Default Port: 26657
Protocol: WebSocket
Authentication: None (use with TLS and proper access controls)

Security Warning

When exposing API endpoints publicly, always implement proper security measures:

Use HTTPS/TLS for all connections
Implement rate limiting to prevent abuse
Configure firewall rules to restrict access
Consider using an API gateway for additional security layers

REST API

The REST API provides HTTP endpoints for querying blockchain data and submitting transactions.

Configuration

To enable the REST API, configure the following in your app.toml file:

[api]
# Enable defines if the API server should be enabled.
enable = true

# Address defines the API server to listen on.
address = "tcp://0.0.0.0:1317"

# EnableUnsafeCORS defines if CORS should be enabled (unsafe - use it at your own risk).
enabled-unsafe-cors = false

Common Endpoints

Here are the most commonly used REST API endpoints:

Node Information

GET /node_info

Returns information about the connected node.

Example Response:

{
  "node_info": {
    "protocol_version": {
      "p2p": "8",
      "block": "11",
      "app": "0"
    },
    "id": "2b89c755963a03a2a2c846d5efb97c06e6d2cdfe",
    "listen_addr": "tcp://0.0.0.0:26656",
    "network": "chainos-1",
    "version": "v1.5.05",
    "channels": "40202122233038606100",
    "moniker": "ChainOS-Validator",
    "other": {
      "tx_index": "on",
      "rpc_address": "tcp://0.0.0.0:26657"
    }
  },
  "application_version": {
    "name": "chainosd",
    "server_name": "chainosd",
    "version": "v1.5.05",
    "commit": "a7c6462a7a4f447e7f59c12745ba0645a7c6462a",
    "build_tags": "netgo,ledger",
    "go": "go version go1.18.3 linux/amd64"
  }
}

Account Information

GET /auth/accounts/{address}

Returns account information for the specified address.

Example Response:

{
  "account": {
    "@type": "/chainos.auth.v1beta1.BaseAccount",
    "address": "chainos1abcdefghijklmnopqrstuvwxyz0123456789",
    "pub_key": {
      "@type": "/chainos.crypto.secp256k1.PubKey",
      "key": "AzFq8V7Jj7TGqCUF3B3hYVpXsJ9QjMC9UHZ7sBXk8Xvq"
    },
    "account_number": "12345",
    "sequence": "42"
  }
}

Account Balance

GET /bank/balances/{address}

Returns the balance for the specified address.

Example Response:

{
  "balances": [
    {
      "denom": "uos",
      "amount": "1000000000"
    }
  ],
  "pagination": {
    "next_key": null,
    "total": "1"
  }
}

Submit Transaction

POST /txs
Content-Type: application/json

{
  "tx": {
    "msg": [...],
    "fee": {
      "amount": [
        {
          "denom": "uos",
          "amount": "5000"
        }
      ],
      "gas": "200000"
    },
    "signatures": [...],
    "memo": "Transaction memo"
  },
  "mode": "block"
}

Submits a signed transaction to the network.

Example Response:

{
  "height": "123456",
  "txhash": "ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789",
  "codespace": "",
  "code": 0,
  "data": "0A060A0473656E64",
  "raw_log": "[{\"events\":[{\"type\":\"message\",\"attributes\":[{\"key\":\"action\",\"value\":\"send\"},{\"key\":\"sender\",\"value\":\"chainos1abcdefghijklmnopqrstuvwxyz0123456789\"},{\"key\":\"module\",\"value\":\"bank\"}]},{\"type\":\"transfer\",\"attributes\":[{\"key\":\"recipient\",\"value\":\"chainos1zyxwvutsrqponmlkjihgfedcba9876543210\"},{\"key\":\"sender\",\"value\":\"chainos1abcdefghijklmnopqrstuvwxyz0123456789\"},{\"key\":\"amount\",\"value\":\"1000000uos\"}]}]}]",
  "logs": [...],
  "info": "",
  "gas_wanted": "200000",
  "gas_used": "68735",
  "tx": {...},
  "timestamp": "2025-05-15T18:30:00Z"
}

Query Transaction

GET /txs/{hash}

Returns information about a transaction by its hash.

List Validators

GET /staking/validators

Returns the list of validators.

Query Delegations

GET /staking/delegators/{delegatorAddr}/delegations

Returns delegations for a delegator address.

List Governance Proposals

GET /gov/proposals

Returns the list of governance proposals.

Pagination

Most list endpoints support pagination using the following query parameters:

limit: Maximum number of items to return
offset: Number of items to skip
key: Pagination key from a previous response
count_total: If true, return the total count of items
reverse: If true, return items in reverse order

Example:

GET /staking/validators?limit=10&offset=10

gRPC API

The gRPC API provides high-performance RPC services for interacting with the blockchain.

Configuration

To enable the gRPC server, configure the following in your app.toml file:

[grpc]
# Enable defines if the gRPC server should be enabled.
enable = true

# Address defines the gRPC server address to bind to.
address = "0.0.0.0:9090"

Available Services

ChainOS provides the following gRPC services:

Auth Service

Account-related queries

Account: Get account information
Params: Get auth module parameters

Bank Service

Token-related queries

Balance: Get account balance
AllBalances: Get all balances for an account
TotalSupply: Get total token supply
SupplyOf: Get supply of a specific token
Params: Get bank module parameters

Staking Service

Staking-related queries and transactions

Validators: Get validators list
Validator: Get validator information
ValidatorDelegations: Get delegations to a validator
ValidatorUnbondingDelegations: Get unbonding delegations from a validator
Delegation: Get delegation information
UnbondingDelegation: Get unbonding delegation information
DelegatorDelegations: Get delegations from a delegator
DelegatorUnbondingDelegations: Get unbonding delegations from a delegator
Redelegations: Get redelegation information
DelegatorValidators: Get validators a delegator has delegated to
DelegatorValidator: Get validator a delegator has delegated to
HistoricalInfo: Get historical information at a given height
Pool: Get staking pool information
Params: Get staking module parameters

Governance Service

Governance-related queries and transactions

Proposal: Get proposal information
Proposals: Get proposals list
Vote: Get vote information
Votes: Get votes for a proposal
Params: Get governance module parameters
Deposit: Get deposit information
Deposits: Get deposits for a proposal
TallyResult: Get tally result for a proposal

gRPC Example (Using grpcurl)

Here's an example of querying account information using grpcurl:

grpcurl -plaintext \
  -d '{"address":"chainos1abcdefghijklmnopqrstuvwxyz0123456789"}' \
  localhost:9090 \
  chainos.auth.v1beta1.Query/Account

WebSocket API

The WebSocket API allows for real-time subscription to blockchain events.

Configuration

The WebSocket API is part of the Tendermint RPC server, configured in config.toml:

[rpc]
# TCP or UNIX socket address for the RPC server to listen on
laddr = "tcp://0.0.0.0:26657"

# A list of origins a cross-domain request can be executed from
cors_allowed_origins = []

# Maximum number of simultaneous connections
max_open_connections = 1000

# Maximum number of unique client subscriptions
max_subscription_clients = 100

Event Subscriptions

You can subscribe to various blockchain events using the WebSocket API:

// Connect to WebSocket
ws = new WebSocket("ws://localhost:26657/websocket");

// Subscribe to new blocks
ws.send(JSON.stringify({
  "jsonrpc": "2.0",
  "method": "subscribe",
  "id": 1,
  "params": {
    "query": "tm.event='NewBlock'"
  }
}));

Available Events

Here are the common events you can subscribe to:

NewBlock: Fired when a new block is committed
Tx: Fired when a transaction is included in a block
ValidatorSetUpdates: Fired when the validator set changes
NewBlockHeader: Fired when a new block header is created
CompleteProposal: Fired when a proposal is complete

You can also subscribe to specific transaction events using query conditions:

// Subscribe to transfer events for a specific address
ws.send(JSON.stringify({
  "jsonrpc": "2.0",
  "method": "subscribe",
  "id": 2,
  "params": {
    "query": "tm.event='Tx' AND transfer.recipient='chainos1abcdefghijklmnopqrstuvwxyz0123456789'"
  }
}));

Client Libraries

ChainOS provides client libraries for various programming languages to simplify API interaction:

JavaScript/TypeScript

The official JavaScript client for ChainOS:

// Install
npm install @chainos/client

// Usage example
import { ChainOSClient } from '@chainos/client';

const client = new ChainOSClient('http://localhost:1317');
const balance = await client.getBalance('chainos1abcdefghijklmnopqrstuvwxyz0123456789');
console.log(balance);

Python

The official Python client for ChainOS:

# Install
pip install chainos-client

# Usage example
from chainos_client import ChainOSClient

client = ChainOSClient('http://localhost:1317')
balance = client.get_balance('chainos1abcdefghijklmnopqrstuvwxyz0123456789')
print(balance)

Go

The official Go client for ChainOS:

// Install
go get github.com/o-c-foundation/chainos-client-go

// Usage example
package main

import (
    "fmt"
    "github.com/o-c-foundation/chainos-client-go"
)

func main() {
    client := chainosclient.NewClient("http://localhost:1317")
    balance, err := client.GetBalance("chainos1abcdefghijklmnopqrstuvwxyz0123456789")
    if err != nil {
        panic(err)
    }
    fmt.Println(balance)
}

API Rate Limits

To protect your node from abuse, it's recommended to implement rate limiting for public API endpoints:

Recommended Rate Limits

Query Endpoints: 100 requests per minute per IP
Transaction Submission: 20 requests per minute per IP
WebSocket Connections: 5 connections per IP
WebSocket Subscriptions: 10 subscriptions per connection

Rate limiting can be implemented using a reverse proxy like Nginx or an API gateway.

API Versioning

ChainOS follows semantic versioning for its APIs:

REST API endpoints are versioned with a prefix (e.g., /v1/bank/balances/{address})
gRPC services are versioned in their package names (e.g., chainos.bank.v1beta1)
Breaking changes are only introduced in major version updates

Need Help?

If you need assistance with the ChainOS API, join our Discord community where our team and other developers can help.