ChainOS RPC Endpoints

RPC Basics

The ChainOS RPC server is based on Tendermint RPC and provides HTTP and WebSocket interfaces:

• Default Port: 26657
• HTTP Endpoint: http://node-address:26657
• WebSocket Endpoint: ws://node-address:26657/websocket

Configuration

The RPC server is configured in the config.toml file:

[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

Request Format

RPC requests follow the JSON-RPC 2.0 specification:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "method_name",
  "params": {
    "param1": "value1",
    "param2": "value2"
  }
}

For HTTP GET requests, parameters can be provided as query parameters:

http://node-address:26657/method_name?param1=value1¶m2=value2

Blockchain Endpoints

Endpoints for retrieving blockchain information:

Block

Get block information at a specified height.

GET /block?height={height}

Parameters:

• height (optional): Block height. If not provided, returns the latest block.

Example:

curl http://localhost:26657/block?height=1000

Blockchain

Get a range of blocks.

GET /blockchain?minHeight={min_height}&maxHeight={max_height}

Parameters:

• minHeight: Minimum block height
• maxHeight: Maximum block height

Example:

curl http://localhost:26657/blockchain?minHeight=1000&maxHeight=1010

Block Results

Get the results of block execution at a specified height.

GET /block_results?height={height}

Parameters:

• height (optional): Block height. If not provided, returns the latest block results.

Example:

curl http://localhost:26657/block_results?height=1000

Commit

Get block commit information at a specified height.

GET /commit?height={height}

Parameters:

• height (optional): Block height. If not provided, returns the latest commit.

Example:

curl http://localhost:26657/commit?height=1000

Genesis

Get the genesis file.

GET /genesis

Example:

curl http://localhost:26657/genesis

Node Endpoints

Endpoints for retrieving node information:

Health

Get node health status.

GET /health

Example:

curl http://localhost:26657/health

Status

Get node status information.

GET /status

Example:

curl http://localhost:26657/status

Net Info

Get network information.

GET /net_info

Example:

curl http://localhost:26657/net_info

Consensus State

Get consensus state information.

GET /consensus_state

Example:

curl http://localhost:26657/consensus_state

Dump Consensus State

Get detailed consensus state information.

GET /dump_consensus_state

Example:

curl http://localhost:26657/dump_consensus_state

Transaction Endpoints

Endpoints for working with transactions:

Broadcast Transaction (Sync)

Broadcast a transaction and wait for it to be checked.

GET /broadcast_tx_sync?tx={tx}

Parameters:

• tx: Transaction data encoded in base64

Example:

curl http://localhost:26657/broadcast_tx_sync?tx=DEADBEEFDEADBEEFDEADBEEF

Broadcast Transaction (Async)

Broadcast a transaction without waiting for a response.

GET /broadcast_tx_async?tx={tx}

Parameters:

• tx: Transaction data encoded in base64

Example:

curl http://localhost:26657/broadcast_tx_async?tx=DEADBEEFDEADBEEFDEADBEEF

Broadcast Transaction (Commit)

Broadcast a transaction and wait for it to be committed to a block.

GET /broadcast_tx_commit?tx={tx}

Parameters:

• tx: Transaction data encoded in base64

Example:

curl http://localhost:26657/broadcast_tx_commit?tx=DEADBEEFDEADBEEFDEADBEEF

Transaction

Get transaction information by hash.

GET /tx?hash={hash}&prove={prove}

Parameters:

• hash: Transaction hash (hex-encoded)
• prove (optional): Include proof of the transaction inclusion in the block (true/false)

Example:

curl http://localhost:26657/tx?hash=0xABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789&prove=true

Transaction Search

Search for transactions matching the query.

GET /tx_search?query={query}&prove={prove}&page={page}&per_page={per_page}&order_by={order_by}

Parameters:

• query: Query string (e.g., "tx.height > 5 AND tx.height < 10")
• prove (optional): Include proofs of the transactions inclusion in the block
• page (optional): Page number (1-based)
• per_page (optional): Number of items per page
• order_by (optional): Sort order (asc/desc)

Example:

curl http://localhost:26657/tx_search?query=tx.height>1000+AND+tx.height<1005&prove=true

ABCI Endpoints

Endpoints for interacting with the ABCI application:

ABCI Info

Get information about the ABCI application.

GET /abci_info

Example:

curl http://localhost:26657/abci_info

ABCI Query

Query the ABCI application.

GET /abci_query?path={path}&data={data}&height={height}&prove={prove}

Parameters:

• path: Path to the data (e.g., "/store/bank/key")
• data: Data to query (hex-encoded)
• height (optional): Block height to query (0 means latest)
• prove (optional): Include proof in the response (true/false)

Example:

curl http://localhost:26657/abci_query?path="/store/bank/key"&data=DEADBEEF&height=1000&prove=true

Validator Endpoints

Endpoints for retrieving validator information:

Validators

Get the validator set at a specified height.

GET /validators?height={height}&page={page}&per_page={per_page}

Parameters:

• height (optional): Block height. If not provided, returns the latest validator set.
• page (optional): Page number (1-based)
• per_page (optional): Number of items per page

Example:

curl http://localhost:26657/validators?height=1000&page=1&per_page=100

Event Endpoints

Endpoints for subscribing to events:

Subscribe

Subscribe to events via WebSocket.

// WebSocket request
{
  "jsonrpc": "2.0",
  "method": "subscribe",
  "id": 1,
  "params": {
    "query": "tm.event='NewBlock'"
  }
}

Parameters:

• query: Query string for filtering events

Example Queries:

• tm.event='NewBlock': Subscribe to new blocks
• tm.event='Tx' AND tx.hash='ABCD...': Subscribe to a specific transaction
• tm.event='Tx' AND transfer.recipient='chainos1...': Subscribe to transfers to a specific address

Unsubscribe

Unsubscribe from events via WebSocket.

// WebSocket request
{
  "jsonrpc": "2.0",
  "method": "unsubscribe",
  "id": 1,
  "params": {
    "query": "tm.event='NewBlock'"
  }
}

Parameters:

• query: Query string used in the subscription

Public RPC Endpoints

The following public RPC endpoints are available for ChainOS:

RPC Security

When exposing RPC endpoints publicly, follow these security best practices:

• Use HTTPS/TLS for all connections
• Implement rate limiting to prevent abuse
• Configure firewall rules to restrict access
• Consider using a reverse proxy (like Nginx) in front of the RPC server
• Disable unnecessary endpoints
• Monitor for suspicious activity