> For the complete documentation index, see [llms.txt](https://docs.rujira.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rujira.network/developers/ruji-product-integration-guides/liquidy-swap-api.md). # 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: 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. ``` { "contract": "thor1efrmwk6fzhaugu056mz3nkq4vl0fgpfacm3gp6fhgrdkm4q8rrmsd5a6r5", "msg": routes[0].tx, "funds": [{ "denom": "", "amount": "" }] } ``` 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](https://github.com/cosmos/cosmjs) to sign and broadcast on Rujira / Thorchain-style chains: * `@cosmjs/cosmwasm-stargate` — `SigningCosmWasmClient` and `.execute()` for contract calls * `@cosmjs/stargate` — wallet, fees, and `GasPrice` ``` import { SigningCosmWasmClient } from "@cosmjs/cosmwasm-stargate"; await client.execute( senderAddress, routerContract, route.tx, // routes[0].tx from the API "auto", undefined, [{ denom: inputDenom, amount: inputAmount }], ); ``` 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: ``` [ { "code": "rune", "denom": "rune", "coingecko_id": "thorchain", "decimals": 8, "name": "rune" }, { "code": "btc", "denom": "btc-btc", "coingecko_id": "bitcoin", "decimals": 8, "name": "btc" }, { "code": "dai", "denom": "eth-dai-0x6b175474e89094c44da98b954eedeac495271d0f", "coingecko_id": "dai", "decimals": 8, "name": "dai" }, { "code": "usdc", "denom": "eth-usdc-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "coingecko_id": "usd-coin", "decimals": 8, "name": "usdc" } ] ``` #### 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: ``` { "input": { "denom": "eth-usdc-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "amount": "500000000", "slippage": "0.01" }, "output": { "denom": "rune" } } ``` Example Response: ``` Best — USDC → RUJI → RUNE Returns 11.601979 RUNE (1160197875 atomics) ``` ``` { "direct_route_comparison": "0.0003237745838446937", "routes": [ { "amount": "1160197875", "price_impact": 0.00044361, "fee": 0.011613592340000001, "route": [ "RUJI", "RUNE" ], "tx": { "swap": { "stages": [ { "address": "thor1j9euq8fjd5zdxdkx7auser7kp84tmwtx3snuptpec6azakzwv3dqq6ahwp", "denom": "x/ruji" }, { "address": "thor17cawwg2lsnvcne69fek6nsqkf8snma6gc5ccceshul86rl0u3q4s5l5d0a", "denom": "eth-usdc-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" } ], "min_return": { "denom": "rune", "amount": "1148595896" } } } } ], "timestamp": 1785078193415 } ``` Execute message (tx + funds): ``` { "typeUrl": "/cosmwasm.wasm.v1.MsgExecuteContract", "value": { "sender": "", "contract": "thor1efrmwk6fzhaugu056mz3nkq4vl0fgpfacm3gp6fhgrdkm4q8rrmsd5a6r5", "msg": { "swap": { "stages": [ { "address": "thor1j9euq8fjd5zdxdkx7auser7kp84tmwtx3snuptpec6azakzwv3dqq6ahwp", "denom": "x/ruji" }, { "address": "thor17cawwg2lsnvcne69fek6nsqkf8snma6gc5ccceshul86rl0u3q4s5l5d0a", "denom": "eth-usdc-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" } ], "min_return": { "denom": "rune", "amount": "1148595896" } } }, "funds": [ { "denom": "eth-usdc-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "amount": "500000000" } ] } } ``` #### 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: ``` { "input": { "denom": "eth-usdc-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "amount": "500000000", "slippage": "0.01", "split_step": 3 }, "output": { "denom": "rune" } } ``` Example Response: ``` Best — USDC → RUJI → RUNE 100% — in 5 USDC (500000000 atomics) Returns 11.601979 RUNE (1160197875 atomics) ``` ``` { "single_route_comparison": "0.00", "routes": [ { "split": { "fraction": 1, "amount": "500000000" }, "amount": "1160197875", "price_impact": 0.00044361, "fee": 0.011613592340000001, "route": [ "RUJI", "RUNE" ], "tx": { "swap": { "stages": [ { "address": "thor1j9euq8fjd5zdxdkx7auser7kp84tmwtx3snuptpec6azakzwv3dqq6ahwp", "denom": "x/ruji" }, { "address": "thor17cawwg2lsnvcne69fek6nsqkf8snma6gc5ccceshul86rl0u3q4s5l5d0a", "denom": "eth-usdc-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" } ], "min_return": { "denom": "rune", "amount": "1148595896" } } } } ], "timestamp": 1785078580779 } ``` #### 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`: ``` routes[0].tx.swap.stages "tx": { "swap": { "stages": [ ... ], // ← use this array "min_return": { ... } } } ``` For split routes, use each leg's `split.amount` as `simulate.coin.amount` with that leg's stages. Example shape: ``` { "simulate": { "coin": { "denom": "...", "amount": "..." }, "stages": [ { "address": "thor1...", "denom": "..." }, { "address": "thor1...", "denom": "..." } ] } } ``` RPC endpoint (public default): ``` https://rpc-thorchain.rorcual.xyz ``` Simulate query: ``` { "simulate": { "coin": { "denom": "eth-usdc-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "amount": "500000000" }, "stages": [ { "address": "thor1j9euq8fjd5zdxdkx7auser7kp84tmwtx3snuptpec6azakzwv3dqq6ahwp", "denom": "x/ruji" }, { "address": "thor17cawwg2lsnvcne69fek6nsqkf8snma6gc5ccceshul86rl0u3q4s5l5d0a", "denom": "eth-usdc-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" } ] } } ``` Simulate response: `Returned: 11.601979 RUNE (1160197874 atomics)` ``` { "returned": "1160197874", "fee": "1161360" } ``` ## 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: ``` { "results": [ { "denom": "eth-usdc-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "hasArbitrage": true, "inputAmount": "500000000", "outputAmount": "502150000", "routeCount": 4, "bestRoute": { "amount": "502150000", "price_impact": 0.00012, "fee": 0.0050215, "route": [ "LQDY", "BTC", "USDC" ], "tx": { "swap": { "stages": [ { "address": "thor1dwsnlqw3lfhamc5dz3r57hlsppx3a2n2d7kppccxfdhfazjh06rs5077sz", "denom": "btc-btc" }, { "address": "thor1t76lvqjq7avt6kxnul4pt0zaq6y06fhkw29wxs5rm4kt873s6y9sdp8rxf", "denom": "thor.lqdy" }, { "address": "thor1ax94w4rldvdgc4xgsfwgve7g7xfyxhvuvquvx57vtmr6y4alev0qw3mlvr", "denom": "eth-usdc-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" } ], "min_return": { "denom": "eth-usdc-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "amount": "500000000" }, "affiliate_code": "arb" } } } } ], "meta": { "denomsChecked": [ { "denom": "eth-usdc-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "amount": "500000000" }, { "denom": "btc-btc", "amount": "10000" }, { "denom": "rune", "amount": "2000000000" } ], "denomsCheckedCount": 3, "minPercent": 0.1 } } ``` #### POST `https://api.liquidy.finance/swap/arbroute` Optimized circular arb steps for one denom and amount. Request body: ``` { "denom": "eth-usdc-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "amount": "500000000" } ``` Example Response: `Step 1× — USDC → LQDY → ETH → USDC` \ `In 5 USDC (500000000 atomics) → Out 5.086411 USDC (498641116 atomics)` ``` [ { "multiplier": 1, "inputAmount": "500000000", "outputAmount": "508641116", "hasArbitrage": false, "route": { "amount": "508641116", "price_impact": 0.00223304, "fee": 0.00509150266, "route": [ "LQDY", "ETH", "USDC" ], "tx": { "swap": { "stages": [ { "address": "thor1tnd06uswj8033d0kzd5d7zre73u3uc44r2vvez26z5m4kr68vtusf2snva", "denom": "eth-eth" }, { "address": "thor15gdwez2jt8tdpukx4x4upul4pjtl8f4hx8dsj9a7htsszmas89gqqkx3kf", "denom": "thor.lqdy" }, { "address": "thor1ax94w4rldvdgc4xgsfwgve7g7xfyxhvuvquvx57vtmr6y4alev0qw3mlvr", "denom": "eth-usdc-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" } ], "min_return": { "denom": "eth-usdc-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "amount": "500000000" }, "affiliate_code": "arb" } } }, "timestamp": 1785079404497 } ] ``` #### 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`: ``` routes[0].tx.swap.stages "tx": { "swap": { "stages": [ ... ], // ← use this array "min_return": { ... } } } ``` For split routes, use each leg's `split.amount` as `simulate.coin.amount` with that leg's stages. Example shape: ``` { "simulate": { "coin": { "denom": "...", "amount": "..." }, "stages": [ { "address": "thor1...", "denom": "..." }, { "address": "thor1...", "denom": "..." } ] } } ``` RPC endpoint (public default) ``` https://rpc-thorchain.rorcual.xyz ``` Simulate query: ``` { "simulate": { "coin": { "denom": "eth-usdc-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "amount": "500000000" }, "stages": [ { "address": "thor1tnd06uswj8033d0kzd5d7zre73u3uc44r2vvez26z5m4kr68vtusf2snva", "denom": "eth-eth" }, { "address": "thor15gdwez2jt8tdpukx4x4upul4pjtl8f4hx8dsj9a7htsszmas89gqqkx3kf", "denom": "thor.lqdy" }, { "address": "thor1ax94w4rldvdgc4xgsfwgve7g7xfyxhvuvquvx57vtmr6y4alev0qw3mlvr", "denom": "eth-usdc-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" } ] } } ``` Simulate response: `Returned: 4.98745 USDC (498745002 atomics)` ``` { "returned": "498745002", "fee": "499245" } ``` ## 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 modetypeGET
Latestallhttps://api.liquidy.finance/history?page=1&limit=20
Latestswaphttps://api.liquidy.finance/history?page=1&limit=20&type=swap
Latestarbitragehttps://api.liquidy.finance/history?page=1&limit=20&type=arbitrage
By sendersenderhttps://api.liquidy.finance/history?sender=thor1cmgr5khhcyc9x0xln8cw0mfe5dzwzwtx7g5ca7&page=1&limit=20
By tx hashtxHashhttps://api.liquidy.finance/history?txHash=DDE686E173EA4A60022B7A8639F8EFF03CAE120960A3F41112D89637EB1F2D53
By affiliateaffiliate codehttps://api.liquidy.finance/history?affiliate=arb&page=1&limit=20
Example Response: `https://api.liquidy.finance/history?page=1&limit=5` ``` { "swaps": [ { "txHash": "FEBCA499B86EA7F97DADF90266CC06BFECC8FE4216A81727DE0A20B98EA6DCCD", "to": "eth-usdc", "from": "eth-usdc", "fromAmount": 2, "affiliate": "none", "affiliateFee": 0, "affiliateFeeUsd": 0, "blockHeight": 27169135, "layer1InputAddress": null, "layer1OutputAddress": "thor14ejgrnmt7ljw4vn7wpr6lpyj0up507v0wf2mf9", "platformFee": 0.00200398, "platformFeeUsd": 0.0020039198806, "priceUsd": 0.99997, "referralFee": 0, "referralFeeUsd": 0, "route": "eth-usdc:lqdy:eth-eth:eth-usdc", "rujiVolumeUsd": 5.99982, "sender": "thor14ejgrnmt7ljw4vn7wpr6lpyj0up507v0wf2mf9", "timestamp": 1785080537128, "toAmount": 2.00197077, "type": "arbitrage", "volumeUsd": 1.99994 }, { "txHash": "1FF3437F9D6718A5A97A4E775FBDF19FCD079582FD9AAD89099CE95C352279D6", "to": "eth-eth", "from": "eth-eth", "fromAmount": 0.00105401, "affiliate": "none", "affiliateFee": 0, "affiliateFeeUsd": 0, "blockHeight": 27169080, "layer1InputAddress": null, "layer1OutputAddress": "thor1lj3q7dfg4zwrmtkmqg4u44vy4l44uc68gx892g", "platformFee": 0.00000106, "platformFeeUsd": 0.0020286597999999998, "priceUsd": 1913.83, "referralFee": 0, "referralFeeUsd": 0, "route": "eth-eth:eth-usdc:lqdy:eth-eth", "rujiVolumeUsd": 6.051587874899999, "sender": "thor1lj3q7dfg4zwrmtkmqg4u44vy4l44uc68gx892g", "timestamp": 1785080189156, "toAmount": 0.00105551, "type": "arbitrage", "volumeUsd": 2.0171959583 }, { "fromAmount": 24.3131339, "from": "tcy", "to": "tcy", "txHash": "DDE686E173EA4A60022B7A8639F8EFF03CAE120960A3F41112D89637EB1F2D53", "affiliate": "none", "affiliateFee": 0, "affiliateFeeUsd": 0, "blockHeight": 27168984, "layer1InputAddress": null, "layer1OutputAddress": "thor1cmgr5khhcyc9x0xln8cw0mfe5dzwzwtx7g5ca7", "platformFee": 0.02435312, "platformFeeUsd": 0.00304496800608, "priceUsd": 0.125034, "referralFee": 0, "referralFeeUsd": 0, "route": "tcy:btc-btc:rune:tcy", "rujiVolumeUsd": 9.119905152157802, "sender": "thor1cmgr5khhcyc9x0xln8cw0mfe5dzwzwtx7g5ca7", "timestamp": 1785079593699, "toAmount": 24.3287655, "type": "arbitrage", "volumeUsd": 3.0399683840526004 }, { "fromAmount": 0.00052815, "from": "eth-eth", "to": "eth-eth", "txHash": "EBDA9D7072988D1F0FDCA4228404851193E0F455C7EEFCECC46676D0EEA78192", "affiliate": "none", "affiliateFee": 0, "affiliateFeeUsd": 0, "blockHeight": 27168899, "layer1InputAddress": null, "layer1OutputAddress": "thor1lj3q7dfg4zwrmtkmqg4u44vy4l44uc68gx892g", "platformFee": 5.3e-7, "platformFeeUsd": 0.001005569, "priceUsd": 1897.3, "referralFee": 0, "referralFeeUsd": 0, "route": "eth-eth:eth-usdc:lqdy:eth-eth", "rujiVolumeUsd": 3.006176985, "sender": "thor1lj3q7dfg4zwrmtkmqg4u44vy4l44uc68gx892g", "timestamp": 1785079063922, "toAmount": 0.0005287, "type": "arbitrage", "volumeUsd": 1.002058995 }, { "fromAmount": 1, "from": "eth-usdc", "to": "eth-usdc", "txHash": "F3E3EE0D78DB5F7C1FFB6B5621FCDE62822E3558CF76ED03F43107E1FAC4AD33", "affiliate": "none", "affiliateFee": 0, "affiliateFeeUsd": 0, "blockHeight": 27168891, "layer1InputAddress": null, "layer1OutputAddress": "thor14ejgrnmt7ljw4vn7wpr6lpyj0up507v0wf2mf9", "platformFee": 0.00100218, "platformFeeUsd": 0.00100212187356, "priceUsd": 0.999942, "referralFee": 0, "referralFeeUsd": 0, "route": "eth-usdc:lqdy:eth-eth:eth-usdc", "rujiVolumeUsd": 2.999826, "sender": "thor14ejgrnmt7ljw4vn7wpr6lpyj0up507v0wf2mf9", "timestamp": 1785079012494, "toAmount": 1.00117091, "type": "arbitrage", "volumeUsd": 0.999942 } ], "total": 5037, "page": 1, "limit": 5, "totalPages": 1008 } ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.rujira.network/developers/ruji-product-integration-guides/liquidy-swap-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.