# XChainJS Liquidity Example (THORChain)

This example demonstrates how to interact with THORChain liquidity pools using XChainJS.

It shows how to:

• check pool information


• calculate liquidity positions


• add and remove liquidity


• work with assets and amounts in a safe, chain-agnostic way

The example is fully runnable and available both on GitHub and CodeSandbox.

🔗 Live Demo & Source Code

• ▶ Live demo (CodeSandbox):
  
  
  https://codesandbox.io/p/devbox/github/xchainjs/xchainjs-lib/tree/master/examples/liquidity




• 📦 Source code (GitHub):
  
  
  https://github.com/xchainjs/xchainjs-lib/tree/master/examples/liquidity

📌 What This Example Does

This project demonstrates liquidity management on THORChain using XChainJS.

It covers:

• querying liquidity pool data


• calculating pool shares


• adding liquidity to a pool


• removing liquidity from a pool


• handling assets and amounts consistently

This example is useful for developers building:

• DeFi dashboards


• liquidity provider (LP) tools


• wallets with LP features


• THORChain analytics tools


• backend services for DeFi protocols

🧰 Tech Stack

• TypeScript


• Node.js


• XChainJS


• THORChain


• @xchainjs/xchain-util


• @xchainjs/xchain-thorchain

📂 Project Location

Inside the XChainJS monorepo:

examples/

 └─ liquidity/

The example focuses on liquidity logic, not UI.

🔄 How the Liquidity Flow Works

Add liquidity flow:

User Assets

   ↓

XChainJS Asset & Amount Utilities

   ↓

THORChain Client

   ↓

Pool Share Calculation

   ↓

Add Liquidity Transaction

Remove liquidity flow:

LP Position

   ↓

THORChain Client

   ↓

Withdraw Calculation

   ↓

Remove Liquidity Transaction

🧩 Core Concepts

Liquidity Pools

THORChain liquidity pools consist of:

• one external asset (e.g. BTC, ETH)


• RUNE

Liquidity providers deposit both sides to earn fees.

This example shows how to interact with these pools programmatically.

Asset Representation

Assets are represented using a standardized format:

<CHAIN>.<SYMBOL>

Examples:

• BTC.BTC


• ETH.ETH


• THOR.RUNE

Asset parsing and validation is handled via


@xchainjs/xchain-util.

Amount & Decimal Handling

Liquidity calculations require precise handling of:

• pool units


• asset amounts


• base units vs human-readable values

This example relies on XChainJS utilities to avoid rounding and precision errors.

⚙️ Installation

Clone the repository

git clone https://github.com/xchainjs/xchainjs-lib.git

cd xchainjs-lib/examples/liquidity

Install dependencies

npm install

Run the example

npm start

🚀 Running in the Browser

You can also run this example instantly using CodeSandbox:

https://codesandbox.io/p/devbox/github/xchainjs/xchainjs-lib/tree/master/examples/liquidity

🧪 Code Example (Simplified)

import { assetFromString, assetAmount } from '@xchainjs/xchain-util'



const poolAsset = assetFromString('BTC.BTC')

const runeAmount = assetAmount(100)

const assetAmountToAdd = assetAmount(0.01)



if (!poolAsset) {

  throw new Error('Invalid pool asset')

}

This abstraction ensures consistency across all supported chains.

✅ Why Use XChainJS for Liquidity Management

• Unified API for THORChain pools


• TypeScript-first for safer DeFi logic


• Reusable utilities for assets and amounts


• Suitable for production-grade DeFi tooling

🧠 When This Example Is Useful

Use this example if you are:

• learning how THORChain liquidity works


• building LP dashboards or analytics


• adding liquidity features to a wallet


• experimenting with DeFi backends


• working with XChainJS utilities

🔗 Related Resources

• XChainJS GitHub
  
  
  https://github.com/xchainjs/xchainjs-lib




• XChainJS utilities
  
  
  https://www.npmjs.com/package/@xchainjs/xchain-util




• THORChain documentation
  
  
  https://docs.thorchain.org




• Live liquidity example
  
  
  https://codesandbox.io/p/devbox/github/xchainjs/xchainjs-lib/tree/master/examples/liquidity

📝 Summary

This example provides a clear, runnable reference for working with

THORChain liquidity pools using XChainJS.

It is a solid foundation for building real-world DeFi applications

in JavaScript and TypeScript.