lthn/blockchain

Fork 1

Table of Contents

RPC Quick-Start Guide

Overview
Running the Daemon in RPC Mode
Running the Wallet in RPC Mode
Making API Calls

Request Format
Response Format
BUSY Response

Examples

Using curl
Using Node.js

Atomic Units
Binary RPC API
Further Reading

RPC Quick-Start Guide

This guide covers how to run the Lethean daemon and wallet in RPC mode, and how to make your first API calls.

Overview

The Lethean RPC API follows the JSON-RPC 2.0 Specification. There are two separate RPC servers:

Service	Default Port	URL
Daemon RPC	36941 (testnet: 46941)	`http://127.0.0.1:36941/json_rpc`
Wallet RPC	36944 (testnet: 46944)	`http://127.0.0.1:36944/json_rpc`
Daemon P2P	36942 (testnet: 46942)	N/A (peer connections)

The daemon also exposes HTTP endpoints for mining control (/start_mining, /stop_mining) and binary data (/getblocks.bin, /get_o_indexes.bin).

Running the Daemon in RPC Mode

The daemon starts its RPC server by default. To specify the bind address and port:

./lethean-chain-node --rpc-bind-ip 127.0.0.1 --rpc-bind-port 36941

To enable the Marketplace API, add:

./lethean-chain-node --rpc-bind-ip 127.0.0.1 --rpc-bind-port 36941 --enable-offers-service

Flags:

--rpc-bind-ip -- IP address to bind RPC server to (default: 127.0.0.1)
--rpc-bind-port -- TCP port for RPC server (default: 36941)

Running the Wallet in RPC Mode

Start the daemon (lethean-chain-node) and wait for it to synchronise.
Start the wallet CLI in RPC mode:

./lethean-wallet-cli \
  --wallet-file example.wallet \
  --password password \
  --rpc-bind-ip 127.0.0.1 \
  --rpc-bind-port 36944 \
  --daemon-address 127.0.0.1:36941

Flags:

--wallet-file -- path to an existing wallet file
--password -- wallet password
--rpc-bind-ip -- IP address to bind wallet RPC (default: 127.0.0.1)
--rpc-bind-port -- TCP port for wallet RPC
--daemon-address -- daemon address and port

Making API Calls

Request Format

All JSON-RPC calls use POST requests to the /json_rpc endpoint:

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "METHOD_NAME",
  "params": { ... }
}

Response Format

{
  "id": 0,
  "jsonrpc": "2.0",
  "result": { ... }
}

BUSY Response

Any request may receive a BUSY response if the daemon is synchronising. Retry the request later.

{
  "id": "0",
  "jsonrpc": "2.0",
  "result": {
    "status": "BUSY"
  }
}

Examples

Using curl

# Daemon RPC -- get chain info
curl -X POST http://127.0.0.1:36941/json_rpc \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":"0","method":"getinfo"}'

# Wallet RPC -- get balance
curl -X POST http://127.0.0.1:36944/json_rpc \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":"0","method":"getbalance"}'

# Create integrated address (for payment tracking)
curl -X POST http://127.0.0.1:36944/json_rpc \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":"0","method":"make_integrated_address","params":{"payment_id":"1234567890abcdef"}}'

Using Node.js

const axios = require("axios");

async function callAPI() {
  try {
    const url = "http://127.0.0.1:36941/json_rpc";
    const requestData = {
      jsonrpc: "2.0",
      id: 0,
      method: "getinfo",
    };

    const response = await axios.post(url, requestData);
    console.log(response.data);
  } catch (error) {
    console.error("Error:", error.message);
  }
}

callAPI();

Atomic Units

All amounts and balances are represented as unsigned integers measured in atomic units.

1 LTHN = 1,000,000,000,000 atomic units (10^12)

For example, 0.01 LTHN (the minimum fee) = 10,000,000,000 atomic units.

Binary RPC API

The binary API uses a compact binary protocol for faster data transfer, especially for large datasets. It was designed for wallet-to-daemon communication and uses epee serialisation.

Binary endpoints are accessed at http://RPC_IP:RPC_PORT/METHOD_NAME (e.g., /getblocks.bin, /check_keyimages.bin).