Docs›RPC API
ExplorerGitHub
🔌 RPC

RPC API Reference

The node exposes a simple HTTP JSON API on 127.0.0.1:23332. Use it to integrate miners, explorers, and custom tools.

⚠
Localhost only. Bind RPC to 127.0.0.1 — never expose port 23332 to the internet. There is no authentication.

GET /health

Check if the node is running.

request
curl http://localhost:23332/health
response
{"ok": true}

GET /getblockcount

Return current chain height and total block count.

response
{"blocks": 151, "chain_id": "tensorium-testnet-0", "height": 150}

GET /getdifficulty

Return current difficulty (leading zero bits required).

response
{"chain_id": "tensorium-testnet-0", "height": 150, "leading_zero_bits": 26}

GET /getblock/:height

Return full block data at the given height. Hashes are returned as byte arrays — convert to hex for display.

request
curl http://localhost:23332/getblock/0     # genesis
curl http://localhost:23332/getblock/100
response (abbreviated)
{
  "block": {
    "header": {
      "chain_id": "tensorium-testnet-0",
      "height": 0,
      "leading_zero_bits": 26,
      "nonce": 95202247,
      "previous_hash": [0, 0, ...],   // byte array → convert to hex
      "merkle_root":   [33, 214, ...],
      "timestamp_seconds": 1748649600,
      "version": 1
    },
    "transactions": [{
      "id":      [...],               // txid as byte array
      "inputs":  [],                  // empty for coinbase
      "outputs": [{"address": "txm1...", "value_atoms": 1523557865}],
      "payload": [...]                // coinbase data as bytes
    }]
  },
  "hash": [0, 0, 0, 53, ...]          // block hash as byte array
}
ℹ
Byte arrays. Hashes and transaction IDs are returned as [u8; 32] JSON arrays. Convert to hex with: arr.map(b => b.toString(16).padStart(2,'0')).join('')

GET /getblocktemplate/:miner_address

Return a candidate block for mining. Includes pending mempool transactions. Used by txmminer.

request
curl http://localhost:23332/getblocktemplate/txm1youraddress
response
{
  "template": {
    "header": { "height": 151, "leading_zero_bits": 26, "nonce": 0, ... },
    "transactions": [...]
  }
}

The miner must set the nonce field to find a valid block hash, then submit via /submitblock.

POST /submitblock

Submit a mined block. Validates PoW, appends to chain, broadcasts to peers, and clears confirmed transactions from mempool.

request
curl -X POST http://localhost:23332/submitblock \
  -H "Content-Type: application/json" \
  -d '{ "header": {..., "nonce": 95202247}, "transactions": [...] }'
response — accepted
{"accepted": true, "height": 151, "hash": [...], "canonical": true}
response — rejected
{"error": "block's parent is not known"}

POST /sendrawtransaction

Submit a signed transaction to the mempool. Validates, pools, and broadcasts to peers.

request
curl -X POST http://localhost:23332/sendrawtransaction \
  -H "Content-Type: application/json" \
  -d '{"id":[...],"inputs":[...],"outputs":[...],"payload":[]}'
response
{"accepted": true, "txid": [...]}

GET /getmempoolinfo

Return current mempool contents.

response
{"count": 2, "txids": [[...], [...]]}

GET /getbanlist

Return currently banned peers.

response
{"count": 1, "entries": [{"ip": "1.2.3.4", "score": 100, "banned_until": 1234567890}]}

GET /unban/:ip

Remove an IP from the ban list.

request
curl http://localhost:23332/unban/1.2.3.4