REST and ZMQ

Tidecoin Core exposes a read-only HTTP REST surface and ZeroMQ publish notifications alongside JSON-RPC. REST is useful for simple block and transaction reads. ZMQ is useful for push notifications when an indexer or service wants to react quickly to new blocks or mempool activity.

This page covers enablement and operational concerns. Endpoint and topic references belong in REST API and ZMQ.

REST enablement

REST is disabled by default. Enable it explicitly:


server=1
rest=1
rpcbind=127.0.0.1

REST uses the node’s HTTP server and should be treated as an operational API, not a public website. Keep it bound to localhost or a private interface unless there is a reverse proxy and firewall policy in front of it.

Common REST endpoint families implemented by the node include:

Endpoint family	Purpose
`/rest/chaininfo`	Chain state summary.
`/rest/block/<hash>`	Block data.
`/rest/block/notxdetails/<hash>`	Block data without transaction details.
`/rest/headers/<hash>`	Header ranges.
`/rest/tx/<txid>`	Transaction data.
`/rest/mempool/info`	Mempool summary.
`/rest/mempool/contents`	Mempool transaction listing.
`/rest/getutxos`	UTXO lookup.
`/rest/deploymentinfo`	Deployment state.
`/rest/blockhashbyheight/<height>`	Block hash lookup by height.
`/rest/spenttxouts/<hash>`	Spent txout data where available.

Use JSON-RPC for authenticated control and wallet operations. REST should remain read-only and narrowly exposed.

ZMQ enablement

Configure one or more publishers:


zmqpubhashblock=tcp://127.0.0.1:28332
zmqpubhashtx=tcp://127.0.0.1:28333
zmqpubrawblock=tcp://127.0.0.1:28334
zmqpubrawtx=tcp://127.0.0.1:28335
zmqpubsequence=tcp://127.0.0.1:28336

Supported publisher options:

Option	Publishes
`-zmqpubhashblock=<address>`	Block hashes.
`-zmqpubhashtx=<address>`	Transaction hashes.
`-zmqpubrawblock=<address>`	Raw block bytes.
`-zmqpubrawtx=<address>`	Raw transaction bytes.
`-zmqpubsequence=<address>`	Sequence notifications for block and transaction events.

Each publisher also has a high-water-mark option:

Publisher	HWM option
`pubhashblock`	`-zmqpubhashblockhwm=<n>`
`pubhashtx`	`-zmqpubhashtxhwm=<n>`
`pubrawblock`	`-zmqpubrawblockhwm=<n>`
`pubrawtx`	`-zmqpubrawtxhwm=<n>`
`pubsequence`	`-zmqpubsequencehwm=<n>`

Check active publishers with:


tidecoin-cli getzmqnotifications

Subscriber model

ZMQ notifications are event hints. A subscriber should:

Subscribe to the needed topic.
Receive the hash or raw object.
Fetch canonical details through RPC or REST.
Persist the processed block hash and height.
On restart, compare stored state to getblockchaininfo.
Rewind if the stored tip is no longer on the active chain.

Do not rely on ZMQ alone for correctness. Subscribers can miss messages during restarts, reconnects, high-water-mark drops, or local outages.

Operational guidance

Concern	Guidance
Binding	Prefer `tcp://127.0.0.1:<port>` or an IPC socket for local subscribers.
Exposure	Do not expose REST or ZMQ directly to the public internet.
Backpressure	Increase HWM only when the subscriber and retention model can handle bursts.
Recovery	Always have an RPC backfill path.
Security	Keep wallet RPC separate from public REST/ZMQ infrastructure.
Monitoring	Alert when subscribers fall behind or stop receiving block events.

For explorers and exchanges, ZMQ should trigger ingestion, while block hash comparison and reorg handling should still follow the polling patterns in RPC Integration Patterns.

Debugging

Useful commands and flags:


tidecoin-cli getzmqnotifications
tidecoin-cli getblockchaininfo
tidecoin-cli getnetworkinfo


debug=zmq
debug=http

Check debug.log for notifier setup errors, invalid bind addresses, and HTTP access errors.

Source of truth

Topic	Source
REST startup flag	`../tidecoin/src/init.cpp`
REST endpoints	`../tidecoin/src/rest.cpp`
ZMQ flags	`../tidecoin/src/init.cpp`
ZMQ topics and examples	`../tidecoin/doc/zmq.md`
Active notifier RPC	`../tidecoin/src/zmq/zmqrpc.cpp`

See also: RPC Security, Monitoring, REST API, ZMQ.