Understand the Talero node HTTP surface without crossing into operator-only territory

Scope and contract

The Talero node serves multiple HTTP response families:

• Plain text liveness checks.
• Prometheus metrics for operators.
• JSON-RPC over POST /rpc.
• JSON REST endpoints under /api/v1 and selected aliases under /api.
• Server-sent event streams.
• Optional static file hosting from the local static/ directory.

This page focuses on the stable and public-safe contract. Where the binary contains routes that are heavy, trusted-only, topology-revealing, or better suited to private operator tooling, they are either summarized at a high level or intentionally excluded.

Endpoint families

Top-level endpoints

If you need structured public-safe JSON rather than plain text or Prometheus text, prefer /api/v1 over the top-level routes.

Streaming endpoints

Talero exposes two HTTP streaming surfaces in the node:

/api/v1/head/stream accepts an optional events query parameter containing a comma-separated list of safe event names. If omitted, the stream defaults to head,reorg.

curl -N https://rpc.talero.info/api/v1/head/stream?events=head,reorg

These streams are delivery channels, not durable message queues. Clients should be ready to reconnect and rebuild state from regular REST or RPC queries.

Metrics surfaces

Talero intentionally splits machine-readable status summaries from operator scrape endpoints:

Public docs should treat Prometheus exposure as private by default. A public-safe deployment can expose JSON summaries without publishing the full metrics scrape.

Public-safe summary routes under /api/v1

These routes are the stable public-safe REST core of the node. They are appropriate for status pages, dashboards, wallets, explorers, and general integrations that want structured HTTP responses without depending on JSON-RPC.

Explorer-grade and chain-data routes

Talero also exposes REST routes that support explorer-style browsing, chain lookup, and paginated transaction access. These are still public-facing routes, but some of them are larger, more indexer-shaped, or subject to privacy redaction.

Public-safe does not mean immutable response shape across all deployment modes. Address-centric routes in particular can be masked, reduced, or rate-limited on hardened public edges.

Batch and query conventions

A large part of the REST tree uses a few recurring conventions. Understanding these makes the HTTP surface easier to integrate.

Common query patterns

• limit is widely used on listing routes and is always bounded server-side.
• cursor, cursorBlockNumber, and cursorTxIndex appear on paginated transaction listings.
• format=compact can reduce block payload size on block-listing routes.
• include=bundle, include=tx, or include=receipt can expand some transaction-list views.

Logs over HTTP

GET /api/v1/logs supports HTTP-native filters such as fromBlock, toBlock, address, topic0 through topic3, and limit.

curl -sS 'https://rpc.talero.info/api/v1/logs?fromBlock=1000&toBlock=1100&address=0x1111111111111111111111111111111111111111&limit=200'

Batch lookups

Batch POST routes accept a JSON body with a hashes array. Talero validates size and hash format, then returns a map of found items plus a missing list.

curl -sS -X POST https://rpc.talero.info/api/v1/receipts \
  -H 'content-type: application/json' \
  -d '{
    "hashes": [
      "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
    ]
  }'

Compatibility aliases and static hosting

The node also publishes selected short-form aliases under /api. These are compatibility helpers, not a separate API family.

The node also mounts static files at / from a local static/ directory. That is deployment-specific content and should not be treated as part of the stable node API contract.

Caching and freshness

Talero uses short-lived REST caching and weak ETags on selected read routes. This matters if you are building dashboards, polling loops, or public gateway caches.

• /api/v1/head, /api/v1/stats, and /api/v1/metrics use very short cache windows suitable for dashboards.
• Hot block-list pages can be micro-cached, while more dynamic or cursor-driven pages may use weaker or no-store policies.
• Address transaction history can use different cache behavior for the first page versus historical cursor pages.
• Client integrations should still treat the chain as live data even when short cache headers are present.

Public cacheability is a performance hint, not a consensus guarantee. Finality-sensitive decisions should come from finality-specific surfaces, not from HTTP cache headers.

Safety model for HTTP surfaces

The Talero node does not treat all HTTP routes equally. Public-safe routes are intentionally narrower than the total binary surface.

Public-safe versus private surfaces

• /health, /rpc, and selected /api/v1 routes can support public consumers.
• /metrics and /prom/metrics are operator-oriented and should stay private by default.
• Topology-oriented, trusted-only, and override-style routes belong on private infrastructure only.

Privacy and abuse controls

• Address-centric REST routes and search can be redacted according to the active privacy policy.
• REST search and address routes also participate in anti-abuse and honeytrap-style protection paths.
• Heavy helper routes can be denied or throttled on hardened public edges.

Shared policy with JSON-RPC

• Some REST routes use the same public-guard logic as their JSON-RPC equivalents.
• Safe mode can tighten public availability for heavier public surfaces.
• Trusted-only routes remain trusted-only even when reachable over HTTP.

Error model

The HTTP surface uses conventional HTTP status codes instead of JSON-RPC error objects. Public clients should expect the following patterns: