THORChain Integration

Architecture Overview

Swaptain acts as a user-friendly interface between Telegram users and THORChain's decentralised liquidity protocol. The bot handles wallet management, quote generation, transaction submission, and status monitoring — while THORChain handles the actual cross-chain asset swaps.

Swaptain accesses THORChain through SwapKit, a developer toolkit that provides unified access to quotes, swap execution, price data, and balance queries across all THORChain-supported chains.

THORChain in Brief

THORChain is a decentralised, permissionless liquidity protocol. Key facts:

No bridges or wrapping — trades use real native assets via THORChain vault addresses on each chain
Liquidity pools — community-funded pools of paired assets (e.g., BTC/RUNE, ETH/RUNE) that enable swaps
Validator network — a decentralised set of node operators who observe transactions, execute swaps, and manage vault security
Continuous Liquidity Pool (CLP) model — a slip-based pricing mechanism that adjusts rates based on swap size relative to pool depth

Integration Points

SwapKit API

Swaptain uses SwapKit for:

Quote generation — real-time swap rate calculations with fee estimates
Swap execution — submitting transactions to the correct chain and vault
Price data — current token prices across all supported chains
Balance queries — checking wallet balances across all connected chains

Price Data

Token prices are sourced from multiple providers for accuracy and reliability:

SwapKit — primary price source for THORChain-supported assets
CoinGecko — fallback price data for broader token coverage
On-chain data — direct pool depth queries for real-time rate accuracy

Balance Providers

Wallet balances are fetched from chain-specific providers:

SwapKit — primary balance provider for THORChain-connected chains
Mobula — EVM chain token balance queries (ERC-20, BEP-20, etc.)
Blockchair — UTXO chain balance queries (BTC, LTC, DOGE, etc.)

Balance data is cached briefly to reduce API calls and improve response times. Tap the refresh button in the bot to force a fresh balance check.

Transaction Lifecycle

When you execute a swap through Swaptain, here's the full lifecycle:

Quote

Swaptain requests a quote from SwapKit, which queries THORChain pools for current rates. You see the expected output, fees, and estimated time.

Approval (EVM only)

For ERC-20/BEP-20 token swaps, the token contract must be approved for spending. If Auto Approve is enabled (the default), Swaptain handles this automatically.

Submission

Swaptain submits the swap transaction from your wallet to the source chain. The transaction is broadcast to the network.

Inbound Confirmation

THORChain's validator network observes your inbound transaction. Confirmation times vary by chain (BTC ~10 min, ETH ~12 sec, etc.).

Pool Execution

THORChain executes the swap through its liquidity pools. For streaming swaps, this may happen over multiple blocks.

Outbound Delivery

THORChain sends the destination tokens from its vault to your Swaptain wallet on the destination chain.

Swaptain monitors each stage and sends you Telegram notifications as your swap progresses.

Vault Security

THORChain vault addresses rotate regularly for security. Swaptain always uses the current vault address for each transaction. Never save or reuse old vault addresses.

Network Reliability

THORChain is operated by a decentralised network of validator nodes. Occasionally, the network may pause (halt) for:

Scheduled upgrades
Security responses
Chain-specific issues (e.g., a connected chain experiencing problems)

During a halt, no funds are at risk. Pending inbound transactions are queued and processed once the network resumes. Swaptain will notify you if a network halt affects your swap.