Liquidy Swap API
Liquidy provide an easy way to integrate any SecuredAsset-to-SecuredAsset swap on Rujira, finding the best route between any two tokens through any of the RUJI Trade orderbooks. Liquidy API can also be used to find arbitrage opportunities across the orderbooks.
Liquidy charges 0.10% fee per swap and the optimize routing still often result for a net positive outcome for end users. Liquidy router support both a referral fee model (typically 10% of the 0.10% protocol fee shared with the integrating partner) and an affiliate fee model (additional fee the partner can add on top of the protocol fee - 100% retained by the partner).
Developer reference and live playground: https://liquidy.finance/developer/swap-api
API base: https://api.liquidy.finance
General
How it works
The Liquidy Swap API is an off-chain router. It finds the best route between any two tokens through any of the RUJI Trade books and returns a swap message you can submit directly — it does not move funds for you.
Get supported tokens — GET
/swap/tokensreturns the denoms, decimals, and display metadata for tokens the router can quote and route.Request a route — POST
/swap/route(single route) or/swap/sroute(split route) with input denom, amount in atomics, output denom, and slippage.Use the best route — the response ranks paths; typically take
routes[0]. Each route includes expected output, price impact, andtx.swap(stages +min_return).Execute on chain — send a CosmWasm execute to the router contract with
routes[0].txas the message and attach the input token asfunds(fullinput.amountfor a single route).
Router contract: thor1efrmwk6fzhaugu056mz3nkq4vl0fgpfacm3gp6fhgrdkm4q8rrmsd5a6r5
API base: https://api.liquidy.finance
Swap history (indexed transactions): https://api.liquidy.finance/history
Message shape
A single-route swap is one MsgExecuteContract: the msg field is the API's tx object; funds carries the coin you are swapping in.
Split routes return multiple legs — broadcast one execute per leg, each funded with that leg's split.amount, not the full input.
Signing with CosmJS
Use CosmJS to sign and broadcast on Rujira / Thorchain-style chains:
@cosmjs/cosmwasm-stargate—SigningCosmWasmClientand.execute()for contract calls@cosmjs/stargate— wallet, fees, andGasPrice
Optional (recommended): simulate first with the router's simulate query (see Swap tab) to verify the returned amount before broadcasting.
Swap
Endpoints
GET
https://api.liquidy.finance/swap/tokensList supported swap tokensPOST
https://api.liquidy.finance/swap/routeSingle-route request — one path, full input amountPOST
https://api.liquidy.finance/swap/srouteSplit-route request — multiple legs, split input per callQUERY
thor1efrmwk6fzhaugu056mz3nkq4vl0fgpfacm3gp6fhgrdkm4q8rrmsd5a6r5 — simulateOn-chain simulate — stages from route/sroute tx.swap
Router contract
thor1efrmwk6fzhaugu056mz3nkq4vl0fgpfacm3gp6fhgrdkm4q8rrmsd5a6r5
GET https://api.liquidy.finance/swap/tokens
Returns all supported input/output tokens.
Example Response:
POST https://api.liquidy.finance/swap/route
Single-route request. Returns ranked routes with a ready-to-execute tx.swap for the full input amount.
/route finds one swap path for the entire input amount. Execute a single contract call using routes[0].tx.swap and fund it with the full input.amount.
Request body:
Example Response:
Execute message (tx + funds):
POST https://api.liquidy.finance/swap/sroute
Split-route request. May return multiple legs — fund each contract call with that leg's split.amount. Set split_step (1–10) on input.
/sroute may return multiple legs, each with a split.fraction and split.amount. When split routing runs, you must execute one contract call per leg, sending that leg's split.amount as the coin — not the full input amount.
split_step — practical meaning
1
Finest search (99%, 98%, … 1%) — slowest, most precise
5
Default balance
10
Coarsest allowed — fastest, may miss optimal split
Smaller split_step = more fraction trials = more route simulations = better chance of finding the best split, but slower.
It only matters when split routing actually runs; otherwise /sroute returns a single 100% leg and behaves like a single-route /route call (one contract call with the full input amount).
Request body:
Example Response:
QUERY thor1efrmwk6fzhaugu056mz3nkq4vl0fgpfacm3gp6fhgrdkm4q8rrmsd5a6r5 — simulate
On-chain simulation via the router contract simulate query. Stages define the output token; copy them from routes[n].tx.swap in a /route or /sroute response.
Simulate query:
simulate.coin is the input token and amount to simulate. simulate.stages is the hop sequence through the router — the last stage's denom is the output token.
Copy stages straight from a /route or /sroute response under tx.swap:
For split routes, use each leg's split.amount as simulate.coin.amount with that leg's stages. Example shape:
RPC endpoint (public default):
Simulate query:
Simulate response:
Returned: 11.601979 RUNE (1160197874 atomics)
Arbitrage
Endpoints
GET
https://api.liquidy.finance/swap/arbsScan whitelisted denoms (~$5–10 each) for arb opportunitiesPOST
https://api.liquidy.finance/swap/arbrouteOptimized circular arb routeQUERY
thor1efrmwk6fzhaugu056mz3nkq4vl0fgpfacm3gp6fhgrdkm4q8rrmsd5a6r5 — simulateOn-chain simulate — stages from route/sroute tx.swap
GET https://api.liquidy.finance/swap/arbs?minPercent={min}
Checks 7 whitelisted denoms using default amounts (~$5–10 each). Returns circular arb opportunities where profit exceeds minPercent.
minPercent={0.1}
Checks 7 denoms with default amounts (~$5–10 each):
USDC · 5 USDC
BTC · 0.0001 BTC
ETH · 0.005 ETH
RUNE · 20 RUNE
LQDY · 50 LQDY
RUJI · 30 RUJI
TCY · 100 TCY
Example Response when arb exists:
POST https://api.liquidy.finance/swap/arbroute
Optimized circular arb steps for one denom and amount.
Request body:
Example Response:
Step 1× — USDC → LQDY → ETH → USDC
In 5 USDC (500000000 atomics) → Out 5.086411 USDC (498641116 atomics)
QUERY thor1efrmwk6fzhaugu056mz3nkq4vl0fgpfacm3gp6fhgrdkm4q8rrmsd5a6r5 — simulate
On-chain simulation via the router contract simulate query. Stages define the output token; copy them from routes[n].tx.swap in a /route or /sroute response.
Simulate query:
simulate.coin is the input token and amount to simulate. simulate.stages is the hop sequence through the router — the last stage's denom is the output token.
Copy stages straight from a /route or /sroute response under tx.swap:
For split routes, use each leg's split.amount as simulate.coin.amount with that leg's stages. Example shape:
RPC endpoint (public default)
Simulate query:
Simulate response:
Returned: 4.98745 USDC (498745002 atomics)
History
Endpoints
GET
https://api.liquidy.finance/historyIndexed swap transaction history
GET https://api.liquidy.finance/history
Query indexed swap transactions. Use query parameters to filter by sender, affiliate, tx hash, type (swap|arbitrage on latest), or fetch top swappers by volume.
Query mode:
Latest: Paginated recent swaps (page, limit, optional type=swap|arbitrage)
By sender: Swaps initiated by wallet address
By tx hash: All swap legs in one transaction
By affiliate: Swaps attributed to an affiliate address
Top swappers: Volume leaderboard (period=1d|7d|30d)
Latest
all
https://api.liquidy.finance/history?page=1&limit=20
Latest
swap
https://api.liquidy.finance/history?page=1&limit=20&type=swap
Latest
arbitrage
https://api.liquidy.finance/history?page=1&limit=20&type=arbitrage
By sender
sender
https://api.liquidy.finance/history?sender=thor1cmgr5khhcyc9x0xln8cw0mfe5dzwzwtx7g5ca7&page=1&limit=20
By tx hash
txHash
https://api.liquidy.finance/history?txHash=DDE686E173EA4A60022B7A8639F8EFF03CAE120960A3F41112D89637EB1F2D53
By affiliate
affiliate code
https://api.liquidy.finance/history?affiliate=arb&page=1&limit=20
Example Response:
https://api.liquidy.finance/history?page=1&limit=5
Last updated
