Reference

RPC Reference

JSON-RPC 2.0 API for interacting with a RillCoin node programmatically.

Connection

Network	Default Endpoint
Mainnet	`http://127.0.0.1:18332`
Testnet	`http://127.0.0.1:28332`
Regtest	`http://127.0.0.1:38332`

Request Format

All requests are HTTP POST to the node's RPC port. The Content-Type must be application/json. Requests follow the JSON-RPC 2.0 specification.

Example curl request

curl -X POST http://127.0.0.1:28332 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"getblockcount","params":[],"id":1}'

Error Format

json

{
  "jsonrpc": "2.0",
  "error": {
    "code":    -1,
    "message": "block not found"
  },
  "id": 1
}

Methods

getblockcount

Returns the current chain tip block height.

params[]returnsu64

Request

json

{"jsonrpc":"2.0","method":"getblockcount","params":[],"id":1}

Response

json

{"jsonrpc":"2.0","result":42381,"id":1}

getblockhash

Returns the block hash at the given height.

params[height: u64]returnsString (hex)

Request

json

{"jsonrpc":"2.0","method":"getblockhash","params":[42381],"id":1}

Response

json

{
  "jsonrpc": "2.0",
  "result":  "a3f8c9d2e1b4f7a6...64b2",
  "id": 1
}

getblock

Returns full block data including header fields and transaction IDs.

params[hash: String]returnsBlockJson

Request

json

{
  "jsonrpc": "2.0",
  "method":  "getblock",
  "params":  ["a3f8c9d2e1b4f7a6...64b2"],
  "id": 1
}

Response

json

{
  "jsonrpc": "2.0",
  "result": {
    "hash":              "a3f8c9d2...64b2",
    "height":            42381,
    "version":           1,
    "prev_hash":         "9b2c7e1d...3a4f",
    "merkle_root":       "d1e2f3a4...89ab",
    "timestamp":         1740000000,
    "difficulty_target": 486604799,
    "nonce":             1929374837,
    "tx_count":          47,
    "tx": ["7f3a9c2b...", "4e5d8c1a..."]
  },
  "id": 1
}

getblockheader

Returns block header fields only, without transaction data.

params[hash: String]returnsHeaderJson

Request

json

{
  "jsonrpc": "2.0",
  "method":  "getblockheader",
  "params":  ["a3f8c9d2...64b2"],
  "id": 1
}

Response

json

{
  "jsonrpc": "2.0",
  "result": {
    "hash":              "a3f8c9d2...64b2",
    "version":           1,
    "prev_hash":         "9b2c7e1d...3a4f",
    "merkle_root":       "d1e2f3a4...89ab",
    "timestamp":         1740000000,
    "difficulty_target": 486604799,
    "nonce":             1929374837
  },
  "id": 1
}

gettransaction

Returns transaction metadata by TXID (BLAKE3 hash, hex-encoded).

params[txid: String]returnsTransactionJson

Request

json

{
  "jsonrpc": "2.0",
  "method":  "gettransaction",
  "params":  ["7f3a9c2b1d4e5f6a..."],
  "id": 1
}

Response

json

{
  "jsonrpc": "2.0",
  "result": {
    "txid":      "7f3a9c2b1d4e5f6a...",
    "version":   1,
    "vin_count": 2,
    "vout_count": 2,
    "lock_time": 0
  },
  "id": 1
}

sendrawtransaction

Submits a hex-encoded bincode-serialized transaction to the mempool and broadcasts it to peers. Returns the transaction ID on success.

params[hex_data: String]returnsString (txid)

Request

json

{
  "jsonrpc": "2.0",
  "method":  "sendrawtransaction",
  "params":  ["01000000..."],
  "id": 1
}

Response

json

{
  "jsonrpc": "2.0",
  "result":  "7f3a9c2b1d4e5f6a...",
  "id": 1
}

getmempoolinfo

Returns mempool statistics including transaction count, total size in bytes, and total fees.

params[]returnsMempoolInfo

Request

json

{"jsonrpc":"2.0","method":"getmempoolinfo","params":[],"id":1}

Response

json

{
  "jsonrpc": "2.0",
  "result": {
    "size":      43,
    "bytes":     18724,
    "total_fee": 43000
  },
  "id": 1
}

getpeerinfo

Returns the number of currently connected P2P peers.

params[]returnsPeerInfo

Request

json

{"jsonrpc":"2.0","method":"getpeerinfo","params":[],"id":1}

Response

json

{
  "jsonrpc": "2.0",
  "result": {
    "connected": 8
  },
  "id": 1
}

getinfo

Returns a summary of node state: block height, best hash, peer count, circulating supply, and decay pool balance.

params[]returnsNodeInfo

Request

json

{"jsonrpc":"2.0","method":"getinfo","params":[],"id":1}

Response

json

{
  "jsonrpc": "2.0",
  "result": {
    "blocks":             42381,
    "bestblockhash":      "a3f8c9d2...64b2",
    "connections":        8,
    "circulating_supply": 8432750.0,
    "decay_pool":         12847.32
  },
  "id": 1
}

getblocktemplate

Returns a block template for mining. Includes all pending transactions sorted by fee rate, with a pre-computed Merkle root including the coinbase transaction to mining_address.

params[mining_address: String]returnsBlockTemplate

Request

json

{
  "jsonrpc": "2.0",
  "method":  "getblocktemplate",
  "params":  ["trill1qminingaddress..."],
  "id": 1
}

Response

json

{
  "jsonrpc": "2.0",
  "result": {
    "version":           1,
    "prev_hash":         "a3f8c9d2...64b2",
    "merkle_root":       "d1e2f3a4...89ab",
    "timestamp":         1740000120,
    "difficulty_target": 486604799,
    "nonce":             0,
    "height":            42382,
    "transactions": [
      {
        "txid": "7f3a9c2b...",
        "data": "01000000...",
        "fee":  1000
      }
    ]
  },
  "id": 1
}

submitblock

Submits a hex-encoded bincode-serialized block. Returns "ok" on success. Returns an error if the block is invalid.

params[hex_data: String]returnsString

Request

json

{
  "jsonrpc": "2.0",
  "method":  "submitblock",
  "params":  ["01000000a3f8..."],
  "id": 1
}

Response

json

{"jsonrpc":"2.0","result":"ok","id":1}

getutxosbyaddress

Returns all unspent transaction outputs for a given address. Values are in rills (divide by 100,000,000 for RILL). Includes cluster_id for decay tracking.

params[address: String]returnsUTXO[]

Request

json

{
  "jsonrpc": "2.0",
  "method":  "getutxosbyaddress",
  "params":  ["trill1qw5r3k8d9..."],
  "id": 1
}

Response

json

{
  "jsonrpc": "2.0",
  "result": [
    {
      "txid":         "7f3a9c2b...",
      "index":        0,
      "value":        10000000000,
      "block_height": 42100,
      "is_coinbase":  false,
      "cluster_id":   "a3f8c9d2...",
      "pubkey_hash":  "5r3k8d9v..."
    }
  ],
  "id": 1
}

getclusterbalance

Returns the total balance of all UTXOs tagged with the given cluster_id hex string. Divide by 100,000,000 to get RILL.

params[cluster_id: String]returnsu64 (rills)

Request

json

{
  "jsonrpc": "2.0",
  "method":  "getclusterbalance",
  "params":  ["a3f8c9d2..."],
  "id": 1
}

Response

json

{
  "jsonrpc": "2.0",
  "result":  10000000000000,
  "id": 1
}

getblockchaininfo

Returns comprehensive blockchain state including height, circulating supply, decay pool balance, IBD status, UTXO count, mempool size, and peer count.

params[]returnsBlockchainInfo

Request

json

{"jsonrpc":"2.0","method":"getblockchaininfo","params":[],"id":1}

Response

json

{
  "jsonrpc": "2.0",
  "result": {
    "height":               42381,
    "best_block_hash":      "a3f8c9d2...64b2",
    "circulating_supply":   843275000000000,
    "decay_pool_balance":   1284732000000,
    "initial_block_download": false,
    "utxo_count":           1284920,
    "mempool_size":         43,
    "peer_count":           8
  },
  "id": 1
}

getsyncstatus

Returns the node's current sync state — whether it is actively syncing or fully caught up.

params[]returnsSyncStatus

Request

json

{"jsonrpc":"2.0","method":"getsyncstatus","params":[],"id":1}

Response

json

{
  "jsonrpc": "2.0",
  "result": {
    "syncing":        false,
    "current_height": 42381,
    "peer_count":     8,
    "best_block_hash": "a3f8c9d2...64b2"
  },
  "id": 1
}

Wallet & CLI Node Setup