Build And Query THORChain Data

What This Page Can Prove

This is a builder-facing integration guide for planning queries against THORChain data sources. It covers which source answers which question, how to sequence queries safely, and what current-only evidence means for integration design. It does not cover midgard-thornode-data source attribution, protocol-state explanations, or live dashboard claims. For those, see the Midgard and THORNode Data deep dive.

Building on THORChain data starts with a source choice. Midgard, THORNode, Cosmos RPC, Tendermint RPC, and gRPC answer different questions, and a good integration should not treat them as interchangeable just because they are all "API data".

Use this guide for query planning and source safety. Do not use it as transaction instructions.

Query Plan

Start with the user-facing claim or product behavior:

Dashboard metric: use Midgard, then show provider health and source freshness beside the number.
Current protocol state: use THORNode for Mimirs, inbound addresses, quotes, node/version state, and exact current blockers.
Wallet or transaction construction: use official developer docs for format, then use fresh THORNode quote and inbound-address data immediately before the user signs.
Consensus or node monitoring: use Tendermint RPC, Cosmos RPC, or gRPC according to the data family, not Midgard dashboard endpoints.
Historical or indexed analysis: label whether the result comes from Midgard intervals, an explorer, a local archive, or another model.

If a feature needs more than one live endpoint, keep the evidence scoped. A Midgard pool list can help populate choices; it does not prove a concrete route is safe or currently executable.

Source Families

The official developer docs describe five primary data sources:

Midgard: dashboard-friendly consumer data for swaps, pools, volume, users, network totals, and historical-looking time series.
THORNode: THORChain-specific state-machine data such as Mimirs, inbound addresses, quotes, transaction state, and node/version context.
Cosmos RPC: generic Cosmos SDK data such as balances and blocks.
Tendermint RPC: consensus and node-status data for monitoring and debugging.
gRPC: protobuf-based Cosmos SDK access for programmatic clients. gRPC uses protocol buffers over HTTP/2, so it needs a gRPC client rather than an ordinary browser or curl JSON request.

For production apps, public endpoints should be treated as shared infrastructure. At this review, the official guide publishes a Liquify limit of 50,000 requests per day per IP, recommends identifying the application with x-client-id, and requires exponential backoff for 429 rate limits or 503 overload responses. The same guide recommends running your own THORNode when production uptime and trust requirements exceed shared-endpoint guarantees.

Current And Historical Endpoint Routing

Do not assume one URL family owns every historical block. The official connection guide documents the mainnet hard-fork boundary explicitly:

Use the current THORNode and Tendermint endpoint families for blocks at or above 4,786,560.
Historical requests for blocks at or below 4,786,559 may require the pre-hard-fork THORNode or Tendermint endpoint families.
Liquify says its main gateway smart-routes archive requests, but an integration should still test the exact historical query and keep the requested height in its evidence.

This boundary is about where historical data can be queried. It does not imply that a pre-hard-fork response describes current protocol behavior.

Minimum Safe Query Sequence

For a swap, wallet, or route-aware integration, a conservative query sequence is:

Load available pool or asset choices from Midgard pools, and include Native RUNE where appropriate.
Read THORNode inbound addresses for the source chain and inspect chain halt, router, gas-rate, dust-threshold, and LP-action fields relevant to the action.
Read current Mimir or network diagnostics when the claim is about halts, pauses, enabled state, source warnings, or review-only unknown controls.
Request a fresh THORNode quote for the route and amount when the claim is about executable swap behavior.
Use the quote response fields for fees, expiry, recommended gas, recommended minimum input, memo, expected output, warning text, and timing.
Re-check immediately before signing if the user paused, edited input, changed route, or crossed quote expiry.

Do not silently carry a quote, inbound address, or gas rate from an old render into a later transaction flow.

Quotes, Inbound Addresses, And Caching

Quotes and inbound addresses are short-lived operational evidence.

The swap guide warns not to cache quote responses or send funds after quote expiry. It also calls out a quote endpoint rate limit of roughly one request per second per IP, so frontend inputs should debounce or throttle quote probing instead of firing on every keystroke.

The querying guide is similarly strict about inbound addresses:

Inbound addresses change with vault churn.
A chain can be halted in the inbound-address response.
Router fields matter for token deposits on EVM-style chains.
Gas rate and dust threshold are part of the current source evidence.
Public Midgard can be phished or stale, so safety-sensitive flows should compare trusted sources or run their own node.

For the wiki, this means a quote result is strong current evidence for that route and amount, but it is not a reusable transaction template or future availability proof.

Dust thresholds are live transaction inputs. The supported-chain catalog intentionally does not copy numeric dust thresholds because current inbound_addresses values can differ from old examples or a previous review. Read the selected chain's current dust_threshold, gas-rate units, router, and halt fields from the same fresh transaction evidence used for the quote.

Amounts, Assets, And Units

Most THORChain and Midgard numeric amount fields use 1e8 base units unless a field explicitly says otherwise, such as a USD field. Do not parse large base-unit values through floating point math when exactness matters.

Builder-facing checks:

Use THORChain asset notation such as BTC.BTC, ETH.ETH, or token forms from the official asset-notation docs.
Treat Midgard pool status as pool-list context. Only pools with available status are candidates for ordinary trading, but a pool list is not route execution proof.
Convert human input to base units before quote requests, and convert display output back from base units with clear labels.
Preserve null, unavailable, insufficient samples, and malformed fields as distinct states.
Do not render missing money, amount, APY, fee, or bps fields as zero.

If an integration mixes native token decimals, THORChain base units, USD strings, and bps fields, name the unit in the UI and tests.

Error Handling And Provider Posture

For the canonical dashboard evidence rules — including never rendering missing data as 0, keeping null and unavailable distinct, and letting malformed provider data fail that provider — see Dashboard Evidence Rules in the Midgard and THORNode Data guide.

Builder-specific guidance for upstream failure:

Handle 429 rate limits and 503 overload responses with backoff instead of tight retry loops.
Fail over only after validating response shape.
Keep source provider, checked time, block height, and warnings visible for trust-sensitive data.
Do not mix independent provider reads into one confident snapshot unless the UI says the sources differ.
Treat malformed Mimir values, duplicate scoped records, missing required fields, and unknown operation-like keys as degraded source posture.
Keep raw response bodies out of transaction instructions unless the user intentionally opens diagnostics.

Shipping Boundary

Before release, confirm source ownership, provider mixing, quote throttling and expiry, fresh inbound/route state at signing time, Midgard labeling, safe unit/error handling, and integration-specific tests. Public endpoints can be unavailable, rate-limited, or inconsistent; copied operational values and third-party SDKs still need their own checks.