REST API¶

Learn how to interact with Koinos using the REST API for HTTP-based blockchain access.

Overview¶

The Koinos REST API provides HTTP endpoints for blockchain interaction, making it easy to integrate with web applications and services that prefer REST over JSON-RPC.

Base URL¶

Mainnet: https://api.koinos.io
Testnet: https://testnet.koinosfoundation.org/jsonrpc

The mainnet host exposes both REST routes and JSON-RPC. The current public testnet endpoint is JSON-RPC.

Common Endpoints¶

Chain Information¶

# Get head block info
GET /v1/chain/head_info

# Get block by height
GET /v1/chain/get_block?height=12345

# Get block by ID
GET /v1/chain/get_block?id=0x1220...

Account Information¶

# Get account balance
GET /v1/chain/get_account_nonce?account=1DQzuCcTKacbs9GGScRTU1Hc8BsyARTPqe

# Get account RC (mana)
GET /v1/chain/get_account_rc?account=1DQzuCcTKacbs9GGScRTU1Hc8BsyARTPqe

Contract Calls¶

# Read contract (GET)
POST /v1/chain/read_contract
Content-Type: application/json

{
  "contract_id": "19GYjDBVXU7keLbYvMLazsGQn3GTWHjHkK",
  "entry_point": 0x82a3537ff,
  "args": "base64-encoded-args"
}

Example Usage¶

JavaScript/Node.js¶

export async function getHeadInfo(fetchImpl = fetch) {
  return getJson("/v1/chain/head_info", fetchImpl);
}

View complete file · Run example

Python¶

import requests
import base64

API_BASE = 'https://api.koinos.io'

def get_head_info():
    response = requests.get(f'{API_BASE}/v1/chain/head_info')
    return response.json()

def get_account_rc(account):
    response = requests.get(
        f'{API_BASE}/v1/chain/get_account_rc',
        params={'account': account}
    )
    return response.json()

cURL¶

# Get head block
curl -X GET "https://api.koinos.io/v1/chain/head_info"

# Get account RC
curl -X GET "https://api.koinos.io/v1/chain/get_account_rc?account=1DQzuCcTKacbs9GGScRTU1Hc8BsyARTPqe"

# Read contract
curl -X POST "https://api.koinos.io/v1/chain/read_contract" \
  -H "Content-Type: application/json" \
  -d '{
    "contract_id": "19GYjDBVXU7keLbYvMLazsGQn3GTWHjHkK",
    "entry_point": 2186741247,
    "args": "base64-encoded-arguments"
  }'

Error Handling¶

export async function withRetry(operation, retries = 2) {
  let lastError;
  for (let attempt = 0; attempt <= retries; attempt += 1) {
    try {
      return await operation();
    } catch (error) {
      lastError = error;
      if (attempt < retries) {
        await new Promise((resolve) => setTimeout(resolve, 250 * 2 ** attempt));
      }
    }
  }
  throw lastError;
}