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:

1. Dashboard metric: use Midgard, then show provider health and source freshness beside the number.
2. Current protocol state: use THORNode for Mimirs, inbound addresses, quotes, node/version state, and exact current blockers.
3. Wallet or transaction construction: use official developer docs for format, then use fresh THORNode quote and inbound-address data immediately before the user signs.
4. Consensus or node monitoring: use Tendermint RPC, Cosmos RPC, or gRPC according to the data family, not Midgard dashboard endpoints.
5. 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.

Dated Transaction Example: Bitcoin OUT And Midgard Trade

Compare the Bitcoin transaction role from its OP_RETURN payload with the Midgard action that contains it. The labels refer to different layers and are complementary.

OUT:00000650D568062B71D1BF4F0F4EEFED44C3F6FB7ED3F6DBB08E962F492107C6

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:

1. Load available pool or asset choices from Midgard pools, and include Native RUNE where appropriate.
2. 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.
3. Read current Mimir or network diagnostics when the claim is about halts, pauses, enabled state, source warnings, or review-only unknown controls.
4. Request a fresh THORNode quote for the route and amount when the claim is about executable swap behavior.
5. Use the quote response fields for fees, expiry, recommended gas, recommended minimum input, memo, expected output, warning text, and timing.
6. 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.

For ADR-026 quotes, pass the intended affiliate and nonzero affiliate_bps, and keep both consistent with the executed memo. Current fee documentation says omitting either uses the default L1 floor and can make the quote disagree with execution. The dynamic floor changes the user's liquidity fee, not the integrator's own affiliate-bps setting.

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.

Treat an EVM router and vault address as one fresh pair, fetched together for the transaction flow. Do not hardcode either or cache them independently across upgrades or churn. The March 20 Router V6 notice warned that mismatching them can lose funds; later chain-specific upgrade notices are not proof that every chain has completed the same rollout.

Memoless infrastructure needs a separate preflight: check current HaltMemoless, registration cost, reference and amount validation, and the service's rate-abuse and hot-wallet exposure before accepting deposits. Builder discussion and the September 4 abuse-halt report show why an API's historical release announcement is not current availability or custody-safety proof.

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.
• Preserve case-sensitive Solana/base58 transaction identifiers exactly; do not globally uppercase transaction hashes. Midgard MR 726, merged June 30, addressed original-case lookup alongside uppercase search.

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.

Missing indexed events can invalidate reconstructed secured-asset balances; an index-derived balance is not authoritative merely because the calculation is internally consistent. Match it to protocol/account evidence at a named height. For security findings, use the canonical responsible-disclosure policy rather than posting exploit details in public Discord; consult the policy for current contacts, encryption guidance, and scope, without assuming a payout.

Swap Execution And Evidence Map

Follow one transaction hash from source-chain inclusion through THORChain observation, protocol processing and outbound scheduling to an independently checked destination transaction. This static learning map includes the waiting, failure and refund boundaries. The ordered text is also the diagram: every stage names the evidence needed and links to the explanation. It does not show a live transaction progressing.

Local Memo Decoder

Bitcoin Memo Archive Pointer

The curated OP_RETURN source entry links to recorded Bitcoin payload bytes, transaction/block references and Bitcoin-side history. Reviewed 3 October 2026 as a third-party discovery pointer, it covers Bitcoin rather than all THORChain activity. Reconcile the original bytes with primary chain evidence before interpreting the memo.

An archive's THORChain classification, confirmation label, ticker count or address grouping does not prove memo validation, THORChain processing, successful cross-chain execution or destination settlement. Use the network diagnostics for current operational evidence and keep any transaction lifecycle gaps explicit.