Introduction

Purpose

The purpose of this site is to act as a "community guide", consisting of how-tos and FAQs for things relating to THORChain. This includes instructions for how to achieve tasks on front-ends (such as THORSwap).

This site originally started as a GitHub Gist written exclusively by one person. Over time, more and more people began contributing information and reviewing procedures. At times, even official front-ends refer users to some of the procedures here!

We hope that you find the information here beneficial.

Technical details

The site is written entirely in Markdown, rendered using mdBook, a documentation-oriented static-site generator.

It is hosted using GitHub Pages, with Cloudflare sitting in front of it to provide additional benefits like security, caching, and general metrics.

The site leverages GitHub Actions; every time there is a commit pushed to the master branch of the official GitHub repository, the site auto-builds and auto-updates.

Anyone who wishes to contribute is welcome to do so via GitHub pull requests. Contributors with a strong dedication to the site can be added as official collaborators on GitHub, thus allowing them to commit directly (i.e. no PRs).

• GitHub repository: https://github.com/koitsu/tcecosystem-guide
• Branch: master

General Q&A

This section contains general Q&A items, primarily induced by repeated questions asked on the THORSwap Discord.

How can I track my LP earnings?

• THORYield mobile app for Android (via Google Play Store) (recommended)
• THORYield mobile app for iOS (via Apple Store) (recommended)
• THORYield app (web-based)

I just opened my LP and it's not showing up in THORYield!

As of mid-November 2023, THORYield is a bit slow to notice new LPs. Please give things 24-48 hours to settle.

In the meantime, you can use the THORChain Network Explorer to verify your LP exists. Simply visit the site and search for your wallet address (for symmetrical LPs, please use your THORChain address), then visit the LP tab and wait a few moments for the details to appear.

Alternately, you can use the Midgard API directly if you are technically inclined. Use the /v2/member endpoint.

If I deposit an asset asymmetrically in an LP, and I expect the opposite asset to gain in value, will I end up with more of the asset I deposited?

Yes. This is because when adding the asset you deposited, 50% of it was automatically swapped into the opposing asset.

Example: you entered into an asymmetric LP depositing BTC (thus putting you in the BTC.RUNE pool). This causes half of your deposit to be swapped for RUNE (at the time the LP was opened). If RUNE pumps, your LP position will auto-rebalance 50:50, thus you will have more ETH than originally deposited.

For further information on asymmetric LPing and 50:50 balancing, as well as impermanent loss, please see the following THORChain University blog posts:

• THORChain University - Calculating Redeemable Value of a Liquidity Pool
• THORChain University - Distinguishing Between Price Exposure and Impermanent Loss in Asymmetrical LP’ing
• THORChain University - THORChain LP — FAQ

Is the APR percentage on THORSwap/THORYield real (e.g. 500%)?

Yes. However, it's important you understand that LPs are not like bank accounts with static or guaranteed interest rates; the APR varies constantly. The numbers shown on THORSwap and THORYield refer to the gains over the past period (usually 7 days on THORSwap, and 180 days on THORYield). The APRs are LUVI-based.

Quoting SamYap of THORChain University:

• LP APRs are backward calculated, not guarantee of any future returns
• LP APRs depends significantly on RUNE price movements & calculation time periods

See https://thorchain-university.medium.com/under-the-hood-liquidity-pool-apr-3e5e662e6675 and https://thorchain-university.medium.com/under-the-hood-apr-of-a-fluctuating-position-948f49dace8a

Note: The synth leverage on @THORChain's LP goes both ways.

• When RUNE:Asset price ratio drops, you may see -100% APR (or lower).
• When RUNE:Asset price ratio increase, LPs can get a similarly "exponential" positive yield as well.

Doing LP is like betting on RUNE price performance.

Is the negative APR I see correct? How can that be?

Yes. Quoting paperX of THORSwap:

Any "negative % APR" stems from THORChain's "synths effect" and LUVI based calculations. You can read all about the details here (See part 3): https://medium.com/thorchain/introduction-to-luvi-and-midgard-apr-calculation-update-cf15e743276d

What are the risks associated with LPs?

• THORChain University - Impermanent Loss
  • Please note Impermanent Loss Protection was officially sunset in December 2023
• THORChain University - Synth Leveraging 101
• THORChain University - Synth Leveraging 201

Where can I see APR performance over time?

Try the THORChain Network Explorer. Navigate to Insights → APR. There you can see 30, 60, 90, and 180-day histories.

THORChain

Affiliate codes

Affiliate codes are actually just THORNames, but figuring out who registered them is tricky. THORChain and RuneScan/Viewblock devs sometimes know who uses what, but this information is not always made public.

THORNames, therefore affiliate codes, are case-insensitive.

Below is a list of codes obtained from various THORChain community resources, from Flipside queries to contributors to Medium articles. If you can contribute to this chart, please submit a PR via GitHub.

BEP2 and ERC20 RUNE

BEP2 RUNE was officially announced as deprecated in July 2022 when KillSwitch was enabled. This period lasted 12 months.

By July 2023, both BEP2 RUNE and ERC20 RUNE were officially unsupported by THORChain.

THORSwap also effectively removed support for both, including the "RUNE-to-native-RUNE" converter mentioned in past YouTube videos.

BEP2

As of early February 2024, two (2) exchanges Bybit and Coinlocally are no longer accepting BEP2 RUNE deposits. It is unknown whether or not such deposits will be restored.

ERC20

Swap or sell the ERC20 RUNE on any Ethereum DEX for whatever you can get for it. Uniswap is one such DEX.

History

Here are some links covering the history and evidence of the deprecation:

• Why BEP2 and ERC20 RUNE were deprecated: THORChain University - Upgrading to Native RUNE
• Upgrade timeline: https://t.me/thorchain_org/610874
• Example of THORChain Twitter/X announcement: https://t.me/thorchain_org/610902
• Example of THORChain Telegram announcement: https://t.me/thorchain_org/476777
• Example of THORChain Dev Discord announcement (screenshot): https://t.me/thorchain_org/610927
• Official statement from THORSwap circa March 2024 (screenshot): https://ibb.co/8jYMkP0

Check LP balances

In case a front-end you use is down or inaccessible, you can still check your LP balances using any of the below methods. These query THORChain infrastructure directly, so rest assured of their accuracy.

9R THORChain Tracker

Web: https://track.ninerealms.com/

• Select the LP tab
• Symmetrical LPs: search for your THORChain address (ex. thor1xxx)
• Asymmetrical LPs: search for your asset's wallet address
• Click the ^All button if you wish to see intricate details about your LPs
• An example screenshot is available in this Twitter/X post

RuneScan

Web: https://runescan.io/

• Symmetrical LPs: search for your THORChain address (ex. thor1xxx)
• Asymmetrical LPs: search for your asset's wallet address
• Select your wallet address in the pulldown directly below the search bar
• Select the LPs tab

Thoryield

• Web: https://app.thoryield.com/
• Mobile (Android): https://play.google.com/store/apps/details?id=com.thoryield.androidapp
• Mobile (iOS): https://apps.apple.com/us/app/thoryield/id1618239586

Instructions vary per interface, but simply add your relevant wallet address as an "account" where applicable. (See below services for examples of what address to add for symmetrical vs. asymmetrical LPs.)

Delays

A common scenario we get in the THORSwap Discord is a user a particular transaction (ex. swap, withdrawal, etc.) and seeing the THORSwap transaction tracker show things in a "pending" state for a very long time. In other cases, the THORSwap transaction tracker doesn't show anything, or might even show a blank page.

As of mid-November 2023, there are bugs/quirks with the THORSwap transaction tracker's "Details" feature, where parts of the UI don't get updated properly. This leads to users panicking, thinking something has gone wrong, followed by claims that their transaction is "stuck".

Most of the time (~98%) the transaction is not "stuck", but subject to one or more conditions that can delay a transaction.

Inbound confirmation counts

When THORChain receives an asset on any supported blockchain (ex. BTC, DOGE, etc.), it requires a certain number of inbound confirmations before continuing to process the transaction.

For more details about this subject, refer to inbound confirmations.

Outbound throttling

THORChain makes use of a throttling mechanism for outbound off-chain transactions that can delay transactions for up to 1 hour.

For more information on the security mechanism, refer to this THORChain University article which covers this and additional scenarios.

In mid-January 2024, THORChain implemented swapper clout to help ease some of the burden of said security mechanism. You can check your THORChain clout score by using the RUNE Tools Swapper Clout website.

Streaming swaps

THORChain offers what are called streaming swaps which help relieve slippage by breaking down a swap transaction into smaller "sub-swaps". Refer to the linked article for details.

Some front-ends, like THORSwap, employ use of streaming swaps by default. On THORSwap, the streaming parameters can be adjusted — and even disabled (for instant swaps) if the asset value is large enough.

Streaming swap duration can vary greatly, and in cases of limited liquidity in a pool, may be longer than expected (ex. 24 hours or longer).

Wallet-related delays

Every wallet requires a number of blockchain confirmation counts before funds are considered "in your wallet". The number varies per wallet; there is no standard.

Blockchain validators (miners) can sometimes take a while to verify transactions. For example, on the BTC blockchain, there have been times where validators have taken upwards of 90 minutes to validate and provide enough confirmations for funds to appear in a user's wallet. We have also seen times of over 2 hours on the BCH blockchain. This is not the fault of THORChain.

If you've verified using a blockchain explorer that funds have arrived at your address, but your wallet still isn't seeing them, contact the support team associated with your wallet (ex. Trust Wallet, Ledger, Metamask, etc.).

Dust threshold chart

Front-ends

A list of Front-ends, Exchanges and Wallets supporting THORChain can be found at THORChain Ecosystem.

A list of Affiliate fees charged by different Front-ends can be found at TCUniversity Medium.

Features and region limits may vary per Front-end. DYOR.

Gas chart for dummies

^†  On THORSwap and possibly other front-ends, it is possible to swap from asset X to Y with only the native chain for X connected. Simply enable the Custom Recipient Address feature in the Swap UI cog wheel, then manually enter the destination address for asset Y. (If you don't use this feature, then THORSwap automatically populates the recipient address for you, as long as you connect chains for both asset X and asset Y simultaneously. This can pose a problem for hardware wallets like Ledger, hence the aforementioned feature.)

^‡  Transaction cost when claiming varies per native chain. For example, it's known that for BTC, a minimum of 0.00012 BTC is required. Other chains are more difficult to calculate. Please refer to gas trackers for whatever chain your asset is on, or simply try claiming and see if you get an insufficient balance error. Additionally, THORChain has minimum threshold amounts that must be met as well.

"Native chain" means whatever chain an asset lives on. Some examples:

Inbound confirmations

THORChain requires a certain number of inbound confirmations when receiving an asset on the THORChain network. This is sometimes called the "inbound leg".

Reviewing inbound confirmations is somewhat complicated and technical:

1. Visit https://thornode.ninerealms.com/thorchain/tx/status/YOUR_TRANSACTION_HASH in your browser
   • Replace YOUR_TRANSACTION_HASH with the Transaction Hash/ID from the earlier procedure
   • If you see the message {"error":"rpc error: code = Unknown desc = internal"} then the Transaction Hash/ID is wrong
   • You can reload this page periodically to see the status of the inbound leg
2. If the transaction is found, you should be shown a JSON blob (a bunch of technical data in text)
3. Review the section called inbound_finalised. Attributes:
   • completed: false — the inbound leg is still in progress
   • completed: true — your transaction is not stuck in the inbound leg
4. Review the section called stages, subsection inbound_observed. Attributes:
   • completed: true — THORChain is aware of the transaction
   • completed: false — THORChain has not yet seen the inbound transaction (may be due to daemon lag)
5. Review the section called stages, subsection inbound_confirmation_counted. Attributes:
   • external_observed_height — block height of the source asset chain that needs to be reached before the transaction will complete
   • external_confirmation_delay_height — block height the source asset chain
   • remaining_confirmation_seconds — rough ETA of when the transaction will complete. This number usually decreases, but can increase!
6. Once the entire swap transaction is completed, section swap_finalised should have completed: true

Queues

THORChain has two (2) kinds of queues that pertain directly to outbound transactions: the Scheduled Queue, and the Outbound Queue.

You can see both of these queues using the 9R THORChain Tracker. If you want to see see both queues on a single page, visit the Tracker's /pending endpoint instead.

Scheduled Queue

Transactions in the Scheduled Queue are intentionally delayed due to THORChain's outbound throttling security mechanism.

Transactions in this queue have an ETA field, which is the amount of time remaining until a transaction is moved into the Outbound Queue.

The Scheduled Queue data comes directly from the /thorchain/queue/scheduled THORNode API endpoint.

Outbound Queue

Transactions in the Outbound Queue are actively being processed by THORChain (i.e. not delayed).

When a transaction enters this queue, it's assigned to an Asgard vault, which then signs the transaction and generates the actual outbound transaction (on the destination blockchain).

Once this process has completed, the transaction is no longer THORChain's responsibility.

Outbound Queue transactions have an AGE field. This field represents how long a transaction has been assigned to an Asgard vault, but not yet signed or having its outbound transaction accepted (on the destination blockchain).

If neither of the latter scenarios have completed within 30 minutes (or more precisely, 300 blocks (SigningTransactionPeriod)), the transaction will be reassigned to a different Asgard vault and AGE reset to 0 minutes.

In normal cases, this queue is processed quickly. However, there are some scenarios where the queue can become large. In these situations, it's common to see transactions with a large AGE field, or being shuffled around between different Asgard vaults.

Some example scenarios where this might happen:

• Asgard vault churn, which is done periodically (usually every 2.5 to 3 days)
  • Transactions with a Type of MIGRATE are indicators churn is happening
• Gas estimation quirks or bugs (such as those fixed in THORNode v1.131.0)
• Anomalous conditions which require developer attention (and possibly a chain halt)

The Outbound Queue data comes directly from the /thorchain/queue/outbound THORNode API endpoint.

THORSwap

• Due to DDoS attacks and abuse on THORSwap and 9Realms infrastructures during late 2023, rate-limits were applied to ensure service reliability. However, these limits can occasionally cause problems for users, such as having their IP address temporarily blocked for 1 hour. If you encounter this, you may want to switch to using a VPN (i.e. get a new IP address) to see if things work. However, be sure to read the next item.
• Some third-party APIs that THORSwap relies on block VPNs or block certain geographic regions. Sadly, THORSwap has no direct control over these stipulations. This can cause various problems that are not immediately obvious to users of THORSwap. This can sometimes manifest as the website not loading, wallet connections failing (especially for WalletConnect), wallet balances being wrong, or other oddities.
• Try to avoid using the Max button when doing transactions. Max does literally what it says, which means some transactions might fail because you might not have enough for gas. It's recommended that you decreasing the asset quantity by a small amount to give some "breathing room". Yes, this will leave you with some dust, but it greatly increases the odds of successful transactions.

Tracking a swap

Historically, swaps were exclusively done through THORChain. However, beginning early 2024, THORSwap began integrating other providers (a.k.a. "paths" in the THORSwap UI):

• March 2024: Chainflip
• April 2024: Maya Protocol

Below are per-provider instructions for how you can find your swap.

If you aren't sure which provider/path you used for your swap, you will need to try each of them until you find it. This can be a little confusing, especially in cases where THORChain RUNE is involved.

Maya Protocol procedure

1. Visit Xscanner or MayaScan
2. Enter your source or destination wallet address (source wallet preferred) in the search box
3. If your swap was done through Maya, you should be shown transaction details. Click on the transaction ID to see a progress meter (if streaming swaps were used), and transaction aggregation features
4. If your swap is not found, try the next protocol/path below

Chainflip procedure

1. Visit the Chainflip swap tracker
2. Scroll down the page until you find the Search by swap ID or destination address search box
3. Enter your destination wallet address. For example, if you swapped BTC into ETH, you would enter your Ethereum wallet address
4. If your swap was done through Chainflip, you should be shown details of your swap, as well as a progress indicator
5. If your swap is not found, try the next protocol/path below

THORChain procedure

1. Find the Transaction Hash/ID of your THORSwap activity. There are multiple ways to do this:
   • In THORSwap: click the Transaction History button in the upper right, then choose View Details
   • In RuneScan: search for your wallet address (either source or destination address) and look for your swap transaction. If found, click on it and there should be an icon to copy the Transaction Hash/ID
   • If you still can't find your transaction, then THORChain might be waiting for inbound confirmations
2. Visit the 9R THORChain Tracker
3. Enter the Transaction Hash/ID into the Swap Transaction ID search box at the top of the page
   • If your transaction is found, details about it will be shown
   • Depending on which queue your transaction is in, it may or may not have an ETA. Refer to THORChain queues for further details
4. If you still can't find your transaction on THORChain, you can try the procedure documented in Tracking a withdrawal

Tracking a withdrawal

These instructions can be used for any of the following scenarios:

• Withdrawing from an LP

Procedure

1. Visit the 9R THORChain Tracker /pending endpoint
2. Use Ctrl-F or Command-F to search the web page for the last 4 digits of your destination wallet address
   • "Destination wallet address" means the address to which the funds are being sent (withdrawn) to

If your transaction is found, check to see which queue it's in; this will give you an idea of how long it will be before your transaction makes it onto the blockchain. Refer to THORChain queues for details.

Ledger

Installing and using the THORChain Ledger app

1. Follow Ledger's official documentation
2. At the Pending Ledger review screen, press and release both buttons on your Ledger
3. The screen should now read THORChain ready
4. Connect your Ledger to whatever front-end supports Ledger and THORChain

Failed Ethereum transactions

Some users have had success in enabling Blind Signing inside of the Ethereum app on their Ledger.

In the Ethereum app, choose Settings → Blind Signing, then press both buttons to change it to Enabled.

Incorrect asset quantity

Ledger, especially with UTXO-based chains (ex. BTC, DOGE, etc.), tends to "spread" funds across multiple indexes^† on your Ledger. Ledger Live is able to aggregate all the assets/quantities into one lump sum. This is indirectly described in the official Ledger document titled Understanding Crypto Addresses and Derivation Paths. However, THORSwap cannot do this — it can only see one index at a time (default index 0). Here's an example:

• Pretend your Ledger Live says you have 1.2 BTC total
• Index 0 = address bc1abcd (holds 1 BTC)
• Index 16 = address bc12345 (holds 0.2 BTC)
• THORSwap says you only have 1 BTC. The 0.2 BTC that's "missing" is because it's on index 16, not 0

The workaround:

1. Ensure Ledger Live is not running or in the system tray; if so, exit it
2. Connect your Ledger to THORSwap on the chain of your choice
3. Click the Wallet button in THORSwap and examine what your wallet address is — this is the address of index 0. Save/copy this address
4. Disconnect your Ledger from THORSwap
5. Launch Ledger Live
6. In Ledger Live, send the quantity of the asset to the address you previously copied in an earlier step
   • This is a super basic transaction that will cost you gas
   • What this does is effectively put the funds you send on index 0, since this is all THORSwap can see
7. Wait a little while for network confirmations on your transaction. How long to wait depends on the chain's validators; most are pretty fast, but BTC in particular is slow (can take 30-45 minutes at times)
8. Re-connect your Ledger to THORSwap and you should see the funds you sent

^†: We're unsure if this is account indexes or address indexes, but the end result for the user is the same regardless.

Deposit LP asymm

TBD

Deposit LP symm

-- WIP --

1. Ensure Ledger Live is not running or in the system tray; if so, exit it
2. Attach your Ledger to your USB port (if not already)
3. On your Ledger, run the relevant application for the chain asset you wish to deposit.
4. Launch your web browser (Chrome and Brave confirmed working)
5. Visit the THORSwap app
6. Click the “Connect” button in the upper right
7. Under Hardware Wallets, select Ledger
8. In the Select chains menu on the left, select the chain the asset you wish to deposit belongs to.
9. Click Connect Wallet
10. If you get a pop-up that says app.thorswap.finance wants to connect , click your Ledger device, then click Connect
11. In the bottom right of the THORSwap UI, you should see some messages that pop up/dissappear that says something like Connecting XYZ Ledger #0 and Successfully connected XYZ Ledger #0
12. Click the Wallet button in the upper right and verify your wallet contents are correct.
13. On your Ledger, quit the application you currently have open and follow point 7-12 for the THORChain application.
14. In the Liquidity UI, select Deposit, then: i. Select if you want to deposit assymetrically or symmetrically in the top bar. ii. Change the top asset to the second asset you’d like to deposit. iii. Enter the asset quantity you wish to deposit. Make sure to keep some gas for the withdrawal.
15. Click Add Liquidity
16. Click Add RUNE in the deposit modal that pop up and sign the RUNE transaction on your Ledger.
17. On your Ledger, quit the THORChain application and open the application for the chain asset you wish to deposit.
18. Click Add ASSET in the deposit modal that is still open and sign the ASSET transaction on your Ledger. (Might require blind signing to be enabled for some chains)
19. Congratulations! You are now a THORChain Liquidity Provider!

Swapping assets

There are two options for swapping using a Ledger:

Use Ledger Live

Follow Ledger's official How to swap crypto using THORSwap procedure.

Use THORSwap directly

The biggest complication with Ledger devices stems from the fact that only one app can be run at a time. When trying to swap from assets X to Y, THORSwap normally prefers the chains of both assets X and Y be connected at once. X is mandatory, while having Y attached just makes THORSwap auto-populate the Recipient Address field.

A little-known feature of THORSwap is that you can actually do a swap from asset X to Y with only chain X atttached as long as you know the wallet address of Y. This method uses the Custom Recipient Address feature of THORSwap, and in the case of Ledger, can save users a lot of pain.

1. Ensure Ledger Live is not running or in the system tray; if so, exit it
2. Find the wallet address of asset Y (i.e. destination asset); save it/copy it somewhere
   • Note: it's important you get the correct address for the correct chain. It is very possible to send funds to a wrong address/wrong chain and lose the funds. Please double-check your wallet address!
3. Attach your Ledger to your USB port (if not already)
4. On your Ledger, run the relevant application for the chain asset X is on. (See below notes too)
5. Launch your web browser (Chrome and Brave confirmed working)
6. Visit the THORSwap app
7. Click the "Connect" button in the upper right
8. Under Hardware Wallets, select Ledger
9. In the Select chains menu on the left, select the chain asset X is on
10. Click Connect Wallet
11. If you get a pop-up that says app.thorswap.finance wants to connect, click your Ledger device, then click Connect
12. In the bottom right of the THORSwap UI, you should see some messages that pop up/disappear that says something like Connecting XYZ Ledger #0 and Successfully connected XYZ Ledger #0
13. Click the Wallet button in the upper right and verify your wallet contents are correct
14. In the Swap UI:
    1. To the right of the word Swap, there should be a cog wheel. Click it, then change Set Custom Recipient to On
    2. Change the top asset to asset X, then enter the asset quantity you wish to swap
    3. Change the lower asset to asset Y
15. In the Recipient Address field, paste the destination address you copied/saved in Step #2
16. Click Swap

Withdraw LP asymm

TBD

Withdraw LP symm

TBD

Useful links

• 9R Dashboards
• 9R THORChain Ops
• 9R THORChain Tracker
  • /pending endpoint
• RUNE Tools
• RuneScan
• THORChain
• THORChain Network Explorer
• THORCharts
• THORSwap
• THORSwap Community Forum
• THORSwap Feedback
• THORYield
• THORYield Transaction Tracker
• THORChain node information
  • Mimir voting results
  • THORChain Network Nodes
  • THORNode
• Service documentation
  • Midgard API v1 (Microgard)
  • Midgard API v2
  • THORChain Developer Docs
  • THORChain Ecosystem Docs
  • THORNode Docs
  • THORSwap Docs
  • THORSwap SwapKit Docs
• Blogs
  • THORChain Medium
  • THORChain University Medium
  • THORSwap Medium
• Chats
  • THORChain Developer Discord — warning: dev chat only!
  • THORSwap Discord
  • THORSwap Telegram
• Social media
  • 9R X
  • THORChain X
  • THORSwap X