RPC API Reference

Endpoint Overview

GET /health

Check if the node is running.

curl http://localhost:33332/health

{"ok": true}

GET /getblockcount

Return current chain height and total block count.

curl http://localhost:33332/getblockcount

{"blocks": 1, "chain_id": "tensorium-mainnet", "height": 0}

GET /getdifficulty

Return current difficulty (leading zero bits required).

curl http://localhost:33332/getdifficulty

{"chain_id": "tensorium-mainnet", "height": 0, "leading_zero_bits": 42}

GET /getblock/:height

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

curl http://localhost:33332/getblock/0     # genesis
curl http://localhost:33332/getblock/100

{
  "block": {
    "header": {
      "chain_id": "tensorium-mainnet",
      "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
}

GET /getblocktemplate/:miner_address

Return a candidate block for mining. Includes pending mempool transactions. Used by tensorium-miner and custom miners.

curl http://localhost:33332/getblocktemplate/txm1youraddress

{
  "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.

curl -X POST http://localhost:33332/submitblock \
  -H "Content-Type: application/json" \
  -d '{ "header": {..., "nonce": 95202247}, "transactions": [...] }'

{"accepted": true, "height": 151, "hash": [...], "canonical": true}

{"error": "block's parent is not known"}

POST /sendrawtransaction

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

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

{"accepted": true, "txid": [...], "mempool_size": 3}

GET /getmempoolinfo

Return current mempool contents.

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

GET /getbanlist

Return currently banned peers.

{"count": 1, "entries": [{"ip": "1.2.3.4", "score": 100, "banned": true, "secs_remaining": 1234}]}

GET /unban/:ip

Remove an IP from the ban list.

curl http://localhost:33332/unban/1.2.3.4

{"unbanned": "1.2.3.4", "was_present": true}

GET /getutxos/:address

Return all known UTXOs for an address, including maturity information for coinbase outputs.

curl http://localhost:33332/getutxos/txm1qyouraddresshere

{
  "address": "txm1qyouraddresshere",
  "tip_height": 150,
  "utxo_count": 2,
  "utxos": [
    {
      "txid": "0d4d...",
      "txid_bytes": [13, 77, ...],
      "output_index": 0,
      "value_atoms": 250000000,
      "coinbase": false,
      "created_height": 149,
      "mature": true
    }
  ]
}

This is the endpoint used by @tensorium/sdk when deriving spendable balance.

Status Codes And Errors

• 200: request accepted and JSON body returned.
• 400: malformed body or invalid RPC input.
• 404: unknown endpoint or missing resource such as block height.
• Validation failures are returned as JSON objects with an error field.

SDK Shortcut

If you do not want to handcraft raw HTTP requests, use the official JavaScript SDK.

npm install @tensorium/sdk

import { TxmRPC } from '@tensorium/sdk';

const rpc = new TxmRPC('https://rpc.tensoriumlabs.com');
const info = await rpc.getBlockCount();
console.log(info.height, info.chain_id);

See the Developer Guide for balance, signing, and send examples.

Rate Limit Notes

The node RPC server is intentionally single-threaded. Localhost use is fine, but public operators should treat it as a protected backend, not as a raw internet-facing API.

• Default safe bind: 127.0.0.1:33332
• Public bind requires TENSORIUM_RPC_ALLOW_PUBLIC=1
• Put nginx in front with limit_req and limit_conn
• Whitelist only GET and POST