REST API
How to call the node's REST API under /api/v1: base URL, errors, pagination, caching, the read-only RPC tunnel and one example per route family.
Every node serves a JSON API over HTTP under /api/v1. It reads the node's own databases: there is no separate indexer to run. The dashboard and the browser wallet use nothing else.
Base URL #
The API listens on the same port as JSON-RPC:
| Network | Base URL on the node's machine |
|---|---|
| Mainnet | http://127.0.0.1:10604/api/v1 |
| Testnet | http://127.0.0.1:11604/api/v1 |
| Regtest | http://127.0.0.1:12604/api/v1 |
By default the port accepts connections from localhost only. To reach it from elsewhere, see Security.
curl -s http://127.0.0.1:10604/api/v1/healthlotus-cli getblockchaininfoconst r = await fetch('http://127.0.0.1:10604/api/v1/health');
console.log(await r.json());{"status":"ok","height":1427139,"best_block_hash":"0000000000cc5180...","median_time":1794871298,"ibd":false,"uptime_seconds":6298,"version":12041500,"subversion":"/lotusd:12.4.15(EB32.0)/"}status is syncing during the initial block download.
Versioning and the OpenAPI document #
All routes are under /api/v1. The node describes them itself in an OpenAPI document:
curl -s http://127.0.0.1:10604/api/v1/openapi.json | jq '.paths | keys[]'Its info.version is the version of the node that produced it. Feed it to any OpenAPI tool to browse the API or generate a client. The Reference below is generated from it.
Authentication #
Public routes need no credentials and no API key. A few operator routes (/stratum*, /sharechain*, /scryptchains, /pool/*) need the node's JSON-RPC credentials as HTTP basic auth and answer 401 unauthorized without them. See Security.
Responses #
Replies are JSON (Content-Type: application/json). A route that returns one object returns it directly. A route that returns a list wraps it:
{
"data": [ ... ],
"pagination": {"total": 209, "limit": 25, "offset": 0, "has_more": true}
}Amounts are integers in satoshis (fields such as balance_sats).
Errors #
An error has an HTTP status and always the same body:
{"error":"not_found","message":"Endpoint not found: /api/v1/nope","status":404}error is a stable code to test in programs; message is for people.
| Status | error | Meaning |
|---|---|---|
| 400 | route specific, for example invalid_hex | The request is malformed |
| 401 | unauthorized | Operator route called without credentials |
| 403 | method_not_allowed, forbidden | Not allowed on the public API |
| 404 | not_found, tx_not_found, ... | Unknown route or object |
| 429 | rate_limited | A node-wide budget is used up; see Retry-After |
| 503 | node_warming_up | The node is starting. Retry |
| 503 | explorer_indexing | The explorer indexes are being built after a first sync. Retry |
| 503 | explorer_disabled, module_disabled | This node does not run the explorer index or that module |
The warming-up 503 #
The HTTP port opens before the chain is loaded. Until the node is ready, every route answers:
HTTP/1.1 503 Service Unavailable
Retry-After: 2
X-Node-State: starting
{"error":"node_warming_up","message":"...","status":503}Treat a 503 as temporary and retry after the Retry-After delay.
Pagination #
Core list routes take limit and offset and return the pagination object above. Stop when has_more is false.
curl -s 'http://127.0.0.1:10604/api/v1/blocks?limit=2&offset=0'/addresses/<address>/history pages with opaque cursors instead: its pagination object carries next_cursor, which you pass back as before to get the next (older) page.
Module routes (social, tokens, poker) have their own shape: page and pageSize in, numPages out, and on the long lists a nextCursor to pass back (before= on social/activity, after= on social/profiles). Prefer the cursor on deep lists.
Caching #
The node caches GET answers for a few seconds per route (1 s for health, 5 s for chain, 15 s for a transaction, one hour for openapi.json). Two headers tell you what you got:
| Header | Meaning |
|---|---|
X-Cache | HIT (from the cache) or MISS (computed for you) |
X-Cached-At | Unix time at which the answer was computed |
POST requests and requests with include_unconfirmed=1 are never cached. Poll a fixed URL: a query parameter the route does not read (a cache buster) is not cached.
The API's JSON answers carry no ETag. The protocol documents (/api/v1/docs/<name>) do, and answer 304 Not Modified to a matching If-None-Match.
Send Accept-Encoding: gzip (curl --compressed) to get compressed replies.
CORS #
Every answer carries Access-Control-Allow-Origin: *, and OPTIONS preflight requests are answered, so a page on any origin can call the API from the browser.
Rate limits #
The node does not limit public REST requests per client; an operator who publishes the API puts a reverse proxy with rate limiting in front (see Security). A public node may therefore answer 429 or 503 from its proxy. A few costly routes have a node-wide budget and answer 429 rate_limited with Retry-After.
The read-only RPC tunnel #
/api/v1/rpc/<method> runs a JSON-RPC command without credentials, if the method is on the node's allowlist: read-only queries, plus sendrawtransaction, submitblock, submitheader and sendavalancheproof. GET /api/v1/rpc lists the allowed methods. Any other method answers 403 method_not_allowed.
Pass parameters by position (0=, 1=), by name, or as a JSON array in a POST body:
curl -s 'http://127.0.0.1:10604/api/v1/rpc/getblockhash?0=1'
curl -s -X POST http://127.0.0.1:10604/api/v1/rpc/getblockhash \
-H 'content-type: application/json' -d '{"params":[1]}'lotus-cli getblockhash 1const r = await fetch('http://127.0.0.1:10604/api/v1/rpc/getblockhash?0=1');
const {result, error} = await r.json();The reply has the JSON-RPC shape: {"result": ..., "error": null, "id": null}.
Route families #
One example each. Replace $API with your base URL, for example API=http://127.0.0.1:10604/api/v1.
| Family | Routes start with | What |
|---|---|---|
| Chain | /chain, /upgrades, /utxo-snapshots | Tip, sync state, UTXO commitments, network upgrades |
| Blocks | /blocks | Block list, one block, its transactions |
| Transactions | /txs | One transaction, its inputs and outputs, decode, broadcast |
| Addresses | /addresses, /utxos | Balance, history, unspent outputs, batch queries, rich list |
| Mempool | /mempool | Current content and history |
| Stats | /stats, /overview | Cards and chart series |
| Mining | /mining | Difficulty, hashrate, blocks found, merged-mining proofs |
| Pool | /pool-public | Public data of the node's pool |
| Network | /network, /node, /health | Peers, known nodes, this node |
| Social | /social | RANK votes and profiles |
| Tokens | /slp, /alp | Token lists, transactions, balances |
| Modules | /modules, /empp, /poker, /blob, /contracts | Chain modules and their data |
| Docs | /docs | The protocol documents embedded in the node |
| Push | /events, /push/info | Polled events; see Push interfaces |
Chain #
curl -s $API/chain/tiplotus-cli getbestblockhashconst tip = await (await fetch(`${API}/chain/tip`)).json();Blocks #
<id> is a block hash or a height.
curl -s $API/blocks/1427139
curl -s "$API/blocks/1427139/txs?limit=25"lotus-cli getblock "$(lotus-cli getblockhash 1427139)"const block = await (await fetch(`${API}/blocks/1427139`)).json();Transactions #
GET /txs/<txid> answers for any confirmed transaction without -txindex. /txs/<txid>/raw needs -txindex for confirmed transactions, like getrawtransaction.
curl -s $API/txs/$TXID
curl -s -X POST $API/txs/broadcast \
-H 'content-type: application/json' -d "{\"hex\":\"$RAWTX\"}"lotus-cli getrawtransaction $TXID true
lotus-cli sendrawtransaction $RAWTXconst r = await fetch(`${API}/txs/broadcast`, {
method: 'POST',
headers: {'content-type': 'application/json'},
body: JSON.stringify({hex: rawTx}),
});
const {txid} = await r.json();Coming in 12.4.16: POST /api/v1/txs/broadcast-batch broadcasts up to 1,000 transactions in one request (the REST form of the new sendrawtransactions RPC), with a node-wide rate limit; and GET /api/v1/mining/hashrate/series returns the hashrate history per algorithm.
Addresses #
curl -s $API/addresses/$ADDR
curl -s "$API/addresses/$ADDR/utxos"
curl -s -X POST $API/addresses/batch/utxos \
-H 'content-type: application/json' \
-d "{\"addresses\":[\"$ADDR\"]}"const a = await (await fetch(`${API}/addresses/${addr}`)).json();
console.log(a.balance_sats, a.tx_count);There is no lotus-cli equivalent: JSON-RPC has no address index.
Mempool #
curl -s $API/mempoollotus-cli getrawmempoolconst {size, bytes, transactions} = await (await fetch(`${API}/mempool`)).json();Stats #
curl -s $API/stats/cardsconst cards = await (await fetch(`${API}/stats/cards`)).json();
console.log(cards.hashrate, cards.total_supply_sats, cards.burned_sats);Mining #
curl -s $API/mininglotus-cli getmininginfoconst m = await (await fetch(`${API}/mining`)).json();Pool #
curl -s $API/pool-public/summaryconst pool = await (await fetch(`${API}/pool-public/summary`)).json();Network #
curl -s $API/networklotus-cli getnetworkinfoconst net = await (await fetch(`${API}/network`)).json();Social #
curl -s "$API/social/activity?platform=twitter&pageSize=20"const {votes, nextCursor} =
await (await fetch(`${API}/social/activity?pageSize=20`)).json();See RANK.
Tokens #
curl -s $API/slp/stats
curl -s $API/alp/tokensconst stats = await (await fetch(`${API}/slp/stats`)).json();Modules #
curl -s $API/modulesconst {modules} = await (await fetch(`${API}/modules`)).json();Docs #
curl -s $API/docs
curl -s $API/docs/rankconst md = await (await fetch(`${API}/docs/rank`)).text();Upgrades #
curl -s $API/upgradesconst {upgrades} = await (await fetch(`${API}/upgrades`)).json();Each upgrade has its activation_time and whether it is active on this node. See Activations.
Reference #
The live reference loads from the OpenAPI document of the node.
