TriportRPC
DashboardDocs

Heimdall consensus RPC proxy

GEThttps://api.triport.io/rpc/polygon-heimdall/status

A transparent reverse-proxy that forwards Polygon **Heimdall** consensus-layer requests (Tendermint RPC, Cosmos LCD, and the consensus Prometheus port) through a single authenticated path on the Triport edge.

Polygon— (standard project key)per-tier RPS with burst (free → basic → pro → business)

Polygon's proof-of-stake layer is split into two node types. The Bor execution layer speaks Ethereum JSON-RPC (documented separately). The Heimdall consensus layer speaks the Tendermint/CometBFT and Cosmos REST (LCD) protocols, and that is what this endpoint exposes — read access to validator sets, checkpoints, consensus state, and historic transaction search.

Everything after the /rpc/polygon-heimdall prefix is treated as a Heimdall path. The proxy strips that prefix, matches the remaining path against a fixed whitelist of safe read routes, and forwards the request to a healthy upstream consensus node. Three logical upstream ports are addressed transparently based on the route:

  • Tendermint RPC (26657) — /status, /validators, /tx_search, etc.
  • Cosmos LCD / REST (1317) — paths under /lcd/...
  • Consensus Prometheus (26660) — internal metrics port (route-gated)

The proxy is multi-region aware: requests are served from a regional pool of consensus nodes, with automatic cross-region failover when the home region has no healthy host. Pool members are continuously health-checked against the expected consensus chain ID heimdallv2-137; a node reporting a different network, or one that is catching up, is taken out of rotation.

Use this endpoint when you need direct, low-level consensus data — checkpoint status, validator set membership, or historic tx_search queries — that the execution-layer JSON-RPC cannot answer.

Gotchas

  • Read-only. Transaction broadcast paths (/broadcast_tx_sync, /broadcast_tx_async, /broadcast_tx_commit) are rejected by policy.
  • Whitelist only. Any path not in the table below returns 404.
  • Archive routes are strict. /tx_search and /block_search are served only by archive-capable nodes; if none are available you get a typed 503 rather than a partial result.
  • Path hygiene. Paths containing .., //, encoded traversal sequences, or null bytes are rejected with 400.

Parameters

There are no fixed query/body parameters at the proxy layer — the request is forwarded as-is to the consensus node, including method, body, and query string. What matters is the path (after the prefix), which must resolve to a whitelisted route.

Pathobject
Whitelisted routesobject

Response

The body is the consensus node's native response, passed through verbatim (with internal version/identity headers stripped). A /status response looks like:

Response headers

HeaderDescription
X-Mesh-SourceAlways polygon-heimdall — identifies the serving layer.
Content-TypePassed through from the consensus node (typically application/json).

Response fields

Response fields are defined by the underlying Tendermint RPC / Cosmos LCD protocol and vary per route. For /status, the most useful fields are:

FieldTypeDescription
result.node_info.networkstringConsensus chain ID. Always heimdallv2-137 for healthy nodes.
result.sync_info.latest_block_heightstringLatest committed Heimdall block height.
result.sync_info.catching_upbooleantrue if the node is still syncing.

Errors

All errors use a typed JSON envelope: {"error":{"code":"...","message":"..."}}.

CodeHTTPMeaningWhen it happens
heimdall_path_invalid400Path contains forbidden segments.., //, encoded traversal, or null byte in the path.
heimdall_route_rejected404Route rejected by policyA broadcast/operator-internal path (e.g. /broadcast_tx_sync).
heimdall_route_not_found404Route not in whitelistPath is not one of the whitelisted routes.
heimdall_archive_unavailable503No archive host available/tx_search or /block_search requested while all archive nodes are quarantined/degraded.
heimdall_upstream_exhausted503All hosts exhaustedEvery candidate node failed (transport error or 5xx) within the retry budget.

Authentication and rate-limit errors share the platform envelope — see the shared errors reference. Rate limiting is RPS-per-tier with burst; there is no daily quota.

Examples

JavaScript (fetch)

const res = await fetch(
  "https://api.triport.io/rpc/polygon-heimdall/status",
  {
    headers: { Authorization: `Bearer ${process.env.TRIPORT_API_KEY}` },
  }
);
const { result } = await res.json();
console.log("Heimdall height:", result.sync_info.latest_block_height);

TypeScript SDK (@triport/sdk)

import { Triport } from "@triport/sdk";


const triport = new Triport({ apiKey: process.env.TRIPORT_API_KEY! });


// Raw passthrough to the Heimdall consensus proxy.
const status = await triport.polygon.heimdall.get("/status");
console.log(status.result.sync_info.catching_up);

Python (triport-sdk)

import os
from triport import Triport


client = Triport(api_key=os.environ["TRIPORT_API_KEY"])


status = client.polygon.heimdall.get("/status")
print(status["result"]["sync_info"]["latest_block_height"])

Notes

  • Failover & retries. A failed request is retried once on a different host before returning heimdall_upstream_exhausted. With multi-region routing enabled, the retry may land in another region.
  • Caching. Some routes are served with a short server-side cache (e.g. /validators ~5s, /tx_search ~30s); volatile routes like /status are never cached.
  • Related endpoints. The Bor execution layer is reached through the standard Polygon JSON-RPC surface. For real-time consensus events, see the /ws/polygon-heimdall WebSocket firehose.
  • See the shared authentication and rate limits guides for how the Bearer key and per-tier limits apply across the platform.