Skip to content

Developer docs

THORChain Wallet documentation

A technical walk-through of THORChain Wallet: what it stores, how it builds a swap, and which parts of THORChain it relies on.

Overview

THORChain Wallet is a desktop application for Windows, macOS and Linux. It holds native assets on every chain THORChain connects and swaps between them through THORChain, a decentralised network of validators that runs liquidity pools paired with RUNE.

The wallet does not run a swap engine, an order book or a custodial balance of its own. For each swap it builds a standard transaction for the source chain, attaches a THORChain instruction, and hands it to the network. Validators and pools do the rest, and the result lands back at an address you control.

This page explains how that works in practice: what the app stores, how it derives addresses, how a swap is assembled, what can go wrong and how the wallet handles it. It is written for curious users and for developers who want to verify the wallet's behaviour.

How the app is put together

The wallet has three layers, and each one has a narrow job:

  • Vault: holds the encrypted recovery phrase and does all signing. It never talks to the network.
  • Chain adapters: one per supported chain. They read balances, estimate network fees and broadcast signed transactions using that chain's public infrastructure.
  • Swap planner: requests quotes from THORChain, checks them against your settings and prepares the transaction the vault will sign.

Because the vault is separate from everything that uses the network, a bug in a chain adapter cannot read your keys. The planner can only ask the vault to sign a transaction you have reviewed and confirmed on screen.

Keys and storage

A new wallet generates a 24 word BIP-39 recovery phrase on your computer using the operating system's secure random source. Addresses for every chain are derived from that phrase with each chain's standard derivation path, so the same phrase restores the same addresses in any compatible wallet.

  • The phrase is encrypted on disk with a key derived from your password using a slow, memory hard function, which makes guessing attacks expensive.
  • Keys are decrypted only in memory, only while signing, and cleared afterwards.
  • The app locks after an idle period you choose, from one minute to one hour.
  • No key material is ever sent over the network. Signing always happens locally.

You can view the phrase again from Settings after entering your password. The wallet will warn you before showing it and hide it again when the window loses focus.

Restoring and moving devices

To move to a new computer, install the wallet there and choose Restore. Enter your recovery phrase and set a new password. The password is local to each device and is not related to the phrase.

After a restore, the wallet scans each chain for used addresses and rebuilds your balances from public chain data. Swap history is rebuilt from THORChain's public records for your addresses, so past swaps reappear with their status and fees.

Labels, contacts and display preferences are stored locally and do not travel with the phrase. You can export them as a file from Settings and import them on the new device.

Supported chains

The wallet supports the chains THORChain currently connects:

  • Bitcoin BTC
  • Ethereum ETH
  • Solana SOL
  • Dogecoin DOGE
  • Litecoin LTC
  • Bitcoin Cash BCH
  • XRP Ledger XRP
  • Avalanche AVAX
  • BNB Smart Chain BSC
  • TRON TRX
  • Cosmos ATOM
  • Zcash ZEC
  • Monero XMR
  • Bittensor TAO
  • THORChain RUNE

When THORChain adds a chain, it becomes available in the wallet after an update. When a chain is paused by the network, it stays visible: you can still see and send balances on that chain, but swaps into or out of it are disabled until trading resumes.

Tokens on EVM chains are shown when THORChain has a pool for them. Other tokens you hold at the same address remain on chain and can be viewed in any compatible wallet.

Anatomy of a swap

1. Quote

The wallet requests a quote from a THORNode. The response contains the expected output, every fee, the inbound vault address, an expiry time and a ready made memo. The planner checks that the vault address is the one the network currently publishes, and refuses quotes that do not match.

2. Review

You see the amount you send, the minimum you will receive, the fees in both assets, the estimated time and the destination address decoded from the memo. Nothing is signed until you confirm.

3. Inbound transaction

You sign a normal transaction on the source chain that sends funds to the vault. On UTXO chains such as Bitcoin the memo goes in an OP_RETURN output. On EVM chains the wallet calls THORChain's router contract with the memo as a parameter. On Cosmos based chains it travels in the transaction memo field.

4. Observation

Validators watch the source chain. Once the deposit reaches that chain's confirmation threshold and enough validators agree it happened, the swap is queued.

5. Execution and outbound

The protocol swaps the deposit to RUNE in one pool and RUNE to the output asset in another, then a vault sends the result to the destination address. In this wallet that address is your own unless you change it.

Memos

A swap memo tells THORChain what to do with your deposit. A simplified example:

=:ETH.ETH:0xYourAddress:limit/interval/quantity

  • Action: = means swap.
  • Asset: the output, here native ETH on Ethereum.
  • Destination: where the output is sent.
  • Limit: the minimum output you accept. Below it, the swap refunds.
  • Interval and quantity: streaming parameters, explained below.

The wallet always decodes the memo and shows it in plain words before you sign. If the destination is not one of your own addresses, it is highlighted so you can double check it.

Price limits and slippage

Every swap has a minimum output. It is calculated from the quote and your slippage tolerance, which defaults to a conservative value and can be changed per swap.

If pool prices move while your deposit is being confirmed and the output would fall below that minimum, THORChain does not execute the swap. Instead it refunds your deposit. This protects you from filling at a much worse price than you agreed to.

A very tight limit means more refunds in volatile markets. A loose limit means fewer refunds but a wider range of possible outcomes. The review screen shows the worst case output for the limit you choose.

Streaming swaps

Streaming swaps split one order into several sub-swaps executed over consecutive blocks. Between sub-swaps, arbitrage traders bring the pools back towards market price, so each part fills closer to fair value than a single large swap would.

  • Interval: how many blocks pass between sub-swaps.
  • Quantity: how many sub-swaps the order is split into.

The wallet suggests streaming when a single swap would have high price impact, and picks parameters that keep the total time reasonable. You can turn it off for speed. If some sub-swaps cannot meet the price limit, the filled part is delivered and the rest is refunded.

Fees

  • Source network fee: paid to miners or validators of the chain you send from. The wallet estimates it from current network conditions.
  • Liquidity fee: charged by THORChain pools. It grows with order size relative to pool depth, which is why streaming helps on large orders.
  • Outbound fee: covers the vault's transaction on the destination chain and is deducted from the output.

Every fee is shown in the quote before you sign. THORChain Wallet itself adds no hidden spread to the quoted price.

How long swaps take

Swap time is mostly set by the source chain. THORChain waits for enough confirmations to be safe, and that number scales with the size of the deposit.

  • Fast chains such as Cosmos, BNB Smart Chain or Avalanche usually complete in a minute or two.
  • Ethereum swaps usually complete within a few minutes.
  • Bitcoin swaps commonly take 10 to 30 minutes, longer for large amounts.

The Activity view shows which stage a swap is in, so you can tell the difference between waiting for confirmations and waiting for the outbound transaction.

Refunds

THORChain refunds the inbound asset to the sending address, minus network fees, in these cases:

  • The output would fall below your minimum.
  • The destination chain or pool is paused.
  • The deposit is too small to cover outbound fees.
  • The quote expired before the deposit was observed.

Refunds appear in Activity linked to the original swap, with the reason shown in plain words.

Safety checks

Before signing any swap, the planner runs a set of checks and blocks the transaction if one fails:

  • The inbound vault matches the address THORChain currently publishes for that chain.
  • The quote has not expired.
  • The decoded memo matches what is shown on the review screen.
  • On EVM chains, the router contract is the official THORChain router.

These checks protect against a compromised or misbehaving data source sending you to the wrong address.

Network endpoints

The wallet reads from two public THORChain services:

  • THORNode: quotes, inbound addresses, chain status and pool state.
  • Midgard: indexed swap history and action status for your addresses.

You can point the wallet at your own THORNode and Midgard instances under Settings, Network. Balance reads and broadcasts for each chain go to that chain's public infrastructure, also configurable. Running your own nodes means no third party sees which addresses you query.

What the network can see

Blockchains are public. Your deposits, swaps and outbound transactions are visible to anyone who looks up your addresses, the same as with any self-custody wallet.

The wallet itself sends no analytics and no account data to us. The services it queries can see your IP address and the addresses you ask about. Using your own endpoints, or a VPN, limits what they learn.