A practical guide to THORChain integration, quotes, user custody, affiliate fees and reliable swap tracking

For a multichain wallet, adding native cross-chain swaps is more than showing a conversion rate. Developers must obtain executable quotes, construct secure source-chain transactions, disclose fees, validate destinations and track settlement across two networks. Integrating an established decentralized exchange (DEX) can provide these capabilities without building independent cross-chain liquidity infrastructure.

THORChain is a decentralized cross-chain exchange (DEX) that enables swaps between supported native assets, including bitcoin (BTC) and ether (ETH). A wallet can request a quote, prepare a signed deposit from the user's wallet and monitor the outbound transfer. Users do not need to acquire RUNE separately for a standard supported BTC-to-ETH swap, although the network uses RUNE-paired liquidity internally. Integrators may configure affiliate fees for eligible transactions.

Why integrate native cross-chain swaps into a wallet?

A user holding assets on multiple blockchains may otherwise move funds through a centralized exchange: deposit an asset, trade it, then withdraw to a different network. An in-wallet swap can reduce that friction and keep the transfer experience in the same product. For developers, however, the feature introduces new responsibilities around quoting, network support, transaction signing, status updates, failed transactions and refunds.

Native swaps deliver the actual destination-chain asset, rather than necessarily leaving the user with a wrapped representation. That can be valuable for users converting BTC into native ETH. But a native swap still depends on the settlement network while funds are moving; it is not the same as an instantaneous, risk-free transfer.

What are the main ways to integrate THORChain?

Integration options at a glance

Direct network integration: public quote and status endpoints, no hosted partner key, maximum signing and routing control, and more implementation responsibility. Hosted aggregator API: partner x-api-key, managed eligible routes and fee configuration. Embeddable widget: partner setup and a ready-made swap interface. Third-party SDK: requirements vary by library, underlying route provider and version.

1. Direct integration with THORChain

Developers can connect directly to THORChain's public quote and network-status interfaces without a hosted aggregator partner key. Their application must obtain a fresh quote, use the returned current inbound vault address and memo, construct the correct source-chain transaction and reconcile settlement status. Direct integration gives more control but leaves chain-specific signing, monitoring and recovery to the developer.

2. Hosted aggregator API and embeddable widget

THORChain Swap offers a hosted aggregator, partner tooling and an embeddable widget. The aggregator at api.thorchain.org/v1 is separate from THORChain's public network interfaces: it requires an x-api-key issued through the affiliate program after review. Approved partners can configure relevant affiliate and service-fee arrangements, request available routes and review earnings. The widget can reduce interface development, but teams still need to test signing, availability, error handling and user support.

THORChain's Q3 2026 marketing update describes a hosted routing approach that prioritizes THORChain and may use Maya as an alternative where supported. Available providers and quotes can change; developers should verify the actual route, fees, network state and expected output instead of assuming that a listed option is executable or offers the best price.

3. Third-party SDKs and aggregators

SDKs and routing tools such as SwapKit may combine wallet handling with THORChain and other liquidity sources. They can reduce the amount of chain-specific work required, but teams should examine the exact supported providers, versions, API requirements and data-handling model. A wrapper library does not remove the need to implement transaction-state recovery, user notifications or security checks.

A practical choice depends on the product. An existing wallet with mature chain-signing support may prefer direct integration. A website adding swaps for the first time may prefer the hosted widget. A multichain application comparing several liquidity networks may benefit from an SDK or aggregator, provided it understands how routes are selected.

How does a native THORChain swap work inside an app?

Step 1: Request an executable quote

The app requests a quote for the source asset, destination asset, amount and destination address. Where appropriate, it includes affiliate information and slippage settings. The quote provides an estimated output, itemized fees, an inbound address, a memo or other chain-specific instructions, and an expiry. THORChain's published quickstart uses normalized asset identifiers such as BTC.BTC and ETH.ETH and represents values in 1e8 base units for its quote examples; production integrations must follow the chosen endpoint's exact schema.

Step 2: Ask the user to approve the deposit

The wallet constructs and signs a transaction on the source chain. For a standard memo-based flow, the deposit must reach the correct current inbound vault and carry the specified memo. The app should never substitute a hardcoded vault address or silently change the destination. The user signs with their own wallet; the integrating app should not collect or store their private keys.

Step 3: Let the network execute and pay out

After the inbound transaction is confirmed and observed, THORChain executes the swap using liquidity in its supported pools and sends the output asset on the destination chain. A quote is indicative rather than a guarantee of immediate settlement: source confirmations, outbound scheduling, liquidity conditions and network pauses can affect timing and completion.

Step 4: Track the transaction through its final outcome

The app should distinguish deposit broadcast, source confirmation, network observation, swap execution, outbound initiation and destination confirmation. THORNode transaction status and Midgard actions can help reconcile these stages. THORChain Swap's hosted developer documentation states that it does not emit webhooks, so a reliable application may need polling and durable transaction-state recovery. A source-chain confirmation alone is not evidence that the destination asset has arrived.

How do affiliate fees work?

THORChain supports affiliate fees on eligible swaps. Its native quote documentation permits affiliate fees from 0 to 1,000 basis points: 100 basis points is 1%, and 1,000 is 10%. A valid RUNE address or correctly configured THORName can identify an affiliate. Invalid or expired identifiers can cause fees to be skipped. Multiple affiliate recipients may be configured within the network's applicable overall limits.

Fee revenue is conditional on completed, eligible volume and the applicable fee arrangement. It is not guaranteed profit: high fees reduce the amount users receive and may make a quote less competitive. Integrators should disclose their fees clearly, compare net execution outcomes and understand whether their chosen aggregator shares revenue among multiple providers or services.

For example, a 30-basis-point affiliate fee is 0.30% of the applicable calculation base, not $0.30 per swap. Actual credited amounts depend on conversion and settlement rules. Show users the estimated destination amount after visible fees, rather than emphasizing only the partner's fee percentage.

What does the user pay for a native swap?

The full cost of a native swap can include the source-chain network fee, liquidity-related swap fee, destination-chain outbound fee and any affiliate or interface fee. Costs change with congestion, liquidity depth and trade size. The most useful comparison is the estimated net amount delivered to the destination wallet, not one advertised fee in isolation.

THORChain also provides streaming swaps, which split eligible transactions into multiple sub-swaps over time to reduce price impact for larger orders. Streaming does not guarantee the best price or the fastest completion. Wallet interfaces should explain the potential timing trade-off and show realistic output estimates and limits.

What should developers get right before launch?

Test the full lifecycle before enabling a route

Before production, test a small supported end-to-end swap and its refund path where practical. Validate address formats, precision, memo limits, quote expiry, current vault addresses, minimum amounts and EVM destination restrictions. Record source and destination transaction IDs and reconcile them after restarts. Do not expose a chain or asset pair as live based only on documentation: request a current executable quote.

Use fresh quotes and inbound addresses

Quote values and inbound addresses are time-sensitive, and network vault configurations can change. Fetch or validate a fresh quote before a user signs, honor its expiry and follow chain-specific memo instructions. An outdated inbound address or malformed memo may delay a transaction or change its refund behavior.

Handle halted routes and incomplete swaps

Check live pool and chain status before displaying an executable route. Persist transaction identifiers and state so a restart does not lose a pending swap. Handle delays, outbound failures and refunds when THORChain or another connected chain pauses, without promising an unsupported recovery time.

Validate addresses, asset identifiers and amounts

The source and destination networks may use different address encodings, precision and memo behavior. Validate destination formats, quote units, dust thresholds and minimum amounts. Present a clear confirmation screen showing exactly what users send and expect to receive; do not let a chain mismatch become an irreversible loss.

Design a transparent user experience

Show estimated net output, applicable fees, price impact and whether streaming execution is enabled. Give users separate broadcast, observed, pending payout, completed and refunded states. A small end-to-end test may reveal integration problems but cannot eliminate trading, network or operational risk.

Which chains can a THORChain integration reach?

THORChain's published ecosystem information includes Bitcoin, Ethereum, BNB Smart Chain, Avalanche, Base, XRP Ledger, TRON, Dogecoin, Litecoin, Bitcoin Cash, Cosmos, Solana and Zcash among its supported networks. Developers should check live chain and pool status, the exact available asset pair and current documentation before claiming a route is available. A chain being listed does not mean every token on it or every conversion path is operational.

Frequently asked questions

Does a wallet need an API key to integrate THORChain?

Not for direct integration through THORChain's public interfaces. The separate hosted THORChain Swap aggregator API requires a partner key issued after affiliate-program review.

Does the integrating application need custody of user assets?

No. In a typical self-custody integration, users authorize a source-chain deposit from their own wallet and receive native output at the selected destination. During the exchange, assets pass through THORChain's vault and validator system; self-custody at signing does not mean the transfer is instantaneous or without risk.

Can a wallet generate revenue from THORChain swaps?

Potentially. Integrators can configure eligible affiliate fees, and revenue depends on completed swap volume, the fee arrangement and the underlying network mechanism. Neither revenue nor profitability is guaranteed.

Does a user need to own RUNE to swap BTC for ETH?

No. RUNE functions within THORChain's liquidity pools. A user can send a supported source asset and receive the supported destination asset without separately buying RUNE.

Can a large cross-chain swap be split automatically?

Yes, for eligible routes. THORChain supports streaming swaps, which divide an order into sub-swaps to manage price impact. Integrators should explain the possible additional waiting time and monitor all legs until final settlement.

Can swaps be initiated without connecting a wallet to the interface?

THORChain Swap documents an alternative memoless flow for certain eligible transactions. Route availability and requirements must be checked at the time of use. Users still authorize and send assets, and developers must verify current instructions, quote conditions and destination addresses.

The bottom line

Adding native cross-chain swaps requires accurate quotes, chain-correct signing, transparent fees, live route checks and dependable settlement tracking. THORChain's decentralized exchange infrastructure and separate hosted aggregator tools give developers a choice between more implementation control and faster integration.

The central product decision is where the developer wants to own complexity: wallet signing, routing, quote presentation, affiliate fees or user-support workflows. Whichever integration path is chosen, the user should be able to understand what they are sending, what they may receive and what happens if the transaction does not settle as expected.

Information checked November 12, 2026. Network support, routes, API requirements and fee terms can change. Developers should validate live conditions and current documentation before release. This article is educational, not financial advice.


Don’t forget to like and share the story!

Vested Interest Disclosure: HackerNoon has reviewed the report for quality, but the claims herein belong to the author. #DYOR.