For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

  1. Get supported tokens — GET /swap/tokens returns the denoms, decimals, and display metadata for tokens the router can quote and route.

  2. Request a route — POST /swap/route (single route) or /swap/sroute (split route) with input denom, amount in atomics, output denom, and slippage.

  3. Use the best route — the response ranks paths; typically take routes[0]. Each route includes expected output, price impact, and tx.swap (stages + min_return).

  4. Execute on chain — send a CosmWasm execute to the router contract with routes[0].tx as the message and attach the input token as funds (full input.amount for 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-stargateSigningCosmWasmClient and .execute() for contract calls

  • @cosmjs/stargate — wallet, fees, and GasPrice

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/tokens List supported swap tokens

  • POST https://api.liquidy.finance/swap/route Single-route request — one path, full input amount

  • POST https://api.liquidy.finance/swap/sroute Split-route request — multiple legs, split input per call

  • QUERY thor1efrmwk6fzhaugu056mz3nkq4vl0fgpfacm3gp6fhgrdkm4q8rrmsd5a6r5 — simulate On-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

split_step
Behavior

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/arbs Scan whitelisted denoms (~$5–10 each) for arb opportunities

  • POST https://api.liquidy.finance/swap/arbroute Optimized circular arb route

  • QUERY thor1efrmwk6fzhaugu056mz3nkq4vl0fgpfacm3gp6fhgrdkm4q8rrmsd5a6r5 — simulate On-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/history Indexed 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)

Query mode
type
GET

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