REST API
API12.4.15+

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:

NetworkBase URL on the node's machine
Mainnethttp://127.0.0.1:10604/api/v1
Testnethttp://127.0.0.1:11604/api/v1
Regtesthttp://127.0.0.1:12604/api/v1

By default the port accepts connections from localhost only. To reach it from elsewhere, see Security.

Shell
curl -s http://127.0.0.1:10604/api/v1/health
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:

Shell
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:

JSON
{
  "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:

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

StatuserrorMeaning
400route specific, for example invalid_hexThe request is malformed
401unauthorizedOperator route called without credentials
403method_not_allowed, forbiddenNot allowed on the public API
404not_found, tx_not_found, ...Unknown route or object
429rate_limitedA node-wide budget is used up; see Retry-After
503node_warming_upThe node is starting. Retry
503explorer_indexingThe explorer indexes are being built after a first sync. Retry
503explorer_disabled, module_disabledThis 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
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.

Shell
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:

HeaderMeaning
X-CacheHIT (from the cache) or MISS (computed for you)
X-Cached-AtUnix 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:

Shell
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]}'

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.

FamilyRoutes start withWhat
Chain/chain, /upgrades, /utxo-snapshotsTip, sync state, UTXO commitments, network upgrades
Blocks/blocksBlock list, one block, its transactions
Transactions/txsOne transaction, its inputs and outputs, decode, broadcast
Addresses/addresses, /utxosBalance, history, unspent outputs, batch queries, rich list
Mempool/mempoolCurrent content and history
Stats/stats, /overviewCards and chart series
Mining/miningDifficulty, hashrate, blocks found, merged-mining proofs
Pool/pool-publicPublic data of the node's pool
Network/network, /node, /healthPeers, known nodes, this node
Social/socialRANK votes and profiles
Tokens/slp, /alpToken lists, transactions, balances
Modules/modules, /empp, /poker, /blob, /contractsChain modules and their data
Docs/docsThe protocol documents embedded in the node
Push/events, /push/infoPolled events; see Push interfaces

Chain #

Shell
curl -s $API/chain/tip

Blocks #

<id> is a block hash or a height.

Shell
curl -s $API/blocks/1427139
curl -s "$API/blocks/1427139/txs?limit=25"

Transactions #

GET /txs/<txid> answers for any confirmed transaction without -txindex. /txs/<txid>/raw needs -txindex for confirmed transactions, like getrawtransaction.

Shell
curl -s $API/txs/$TXID
curl -s -X POST $API/txs/broadcast \
  -H 'content-type: application/json' -d "{\"hex\":\"$RAWTX\"}"
12.4.16+

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 #

Shell
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\"]}"

There is no lotus-cli equivalent: JSON-RPC has no address index.

Mempool #

Shell
curl -s $API/mempool

Stats #

Shell
curl -s $API/stats/cards

Mining #

Shell
curl -s $API/mining

Pool #

Shell
curl -s $API/pool-public/summary

Network #

Shell
curl -s $API/network

Social #

Shell
curl -s "$API/social/activity?platform=twitter&pageSize=20"

See RANK.

Tokens #

Shell
curl -s $API/slp/stats
curl -s $API/alp/tokens

See SLP and ALP.

Modules #

Shell
curl -s $API/modules

Docs #

Shell
curl -s $API/docs
curl -s $API/docs/rank

Upgrades #

Shell
curl -s $API/upgrades

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.

Source share/www/docs/rest-api.md in the lotusd repository
Checked against doc/api-v1.md doc/production-deployment.md src/api/api_server.cpp src/api/api_util.cpp src/api/legacy_rpc_handler.cpp src/api/health_handler.cpp src/api/tx_handler.cpp src/api/address_handler.cpp src/api/docs_handler.cpp src/api/openapi_handler.cpp src/modules/