Integrate the contracts

This page is for wallets, trading interfaces, bots and backend services that call Rondo directly. It takes an integration from an empty project to a confirmed fill without requiring knowledge of the reference frontend.

Read

Select a market, verify its binding and page the order book at one block.

Trade

Quote with the contract, approve the payment ceiling and submit a guarded fill.

Reconcile

Decode settlement events and re-read the order after confirmation.

Integration model

Each market is an independent proxy with its own order ids, roles, pause state, escrow and configuration. The identity of an order is therefore:

(chainId, swapper proxy, orderId)

The Swapper proxy is the source of truth and the only contract that receives transactions. The Lens is a replaceable read helper for atomic book pages and fill diagnostics. ERC-20 approvals always name the Swapper as spender, never the Lens.

Lens.openOrders ──→ choose order ──→ Swapper.previewFill
                                            │
payment token.approve(Swapper) ─────────────┤
                                            ▼
                              Swapper.fillOrder
                                            │
                                            ▼
                                    OrderFilled log

Never transfer a token directly to the proxy. Maker escrow is credited only by createOrder or createPeggedOrder; a plain ERC-20 transfer creates no order and no accounting entry.

Production registry

Network: Kaia mainnet · chain id 8217
Public RPC: https://public-en.node.kaia.io
Explorer: https://kaiascan.io All current markets use contract version 1.2.0 and the same quote token:

Kaia USDT  0xd077A400968890Eacc75cdc901F0356c943e4fDb  6 decimals

Market	Swapper proxy	Lens	Base token	Base decimals	First event block
JPYC / USDT	`0xF9ac7195D17eeEB96460607a850106192485250A`	`0x9e5502D1e6CDE9A2b1603E9B350fDE3F15919e7D`	`0xE7C3D8C9a439feDe00D2600032D5dB0Be71C3c29`	18	224142345
IDRX / USDT	`0xd65b29B72599A99E1E8049a549869E1F8F7a3c0B`	`0xB341D5D2074924D81091e3f3cEcB14FCf8411675`	`0x18Bc5bcC660cf2B9cE3cd51a404aFe1a0cBD3C22`	2	224401678
IDRP / USDT	`0x14A41b8F0d18c9F2f5DBca2b0b104D335f16A5EE`	`0xE4FF83DC8A467a083903Dc6099Dd78E9ED993552`	`0xC16d986585407A74Ab87d17C3d0Dc19822E3EB35`	6	224401747

Addresses can change only through a new market or Lens deployment; runtime settings can change at any time. Keep the registry versioned, but read pause, roles, minimums, fees, oracle status and order data on-chain. Deployment details.

Obtain the ABI

The complete user-facing signatures and tuple layout are described in Contract API, and the full Swapper and Lens arrays are directly available on ABI JSON. For a client that discovers and takes orders, use the smaller copy-ready viem fragments below. They contain only the entries that flow needs. The maker extension appears in Maker integration.

import {parseAbi} from "viem";

const orderTuple =
  "(address maker,uint64 expiry,uint16 feeBps,uint8 status,uint8 kind,address sellToken,uint16 premiumBps,address buyToken,uint256 sellAmount,uint256 buyAmount,uint256 sellRemaining,uint256 minRate)" as const;

export const swapperAbi = parseAbi([
  "function version() view returns (string)",
  "function baseToken() view returns (address)",
  "function quoteToken() view returns (address)",
  "function feed() view returns (address)",
  "function ORACLE_TWAP_INTERVAL() view returns (uint256)",
  "function ORACLE_TWAP_MIN_COUNT() view returns (int256)",
  "function paused() view returns (bool)",
  "function canTake(address) view returns (bool)",
  "function minOrderAmount(address) view returns (uint256)",
  "function getOraclePrice() view returns (uint256 answer,uint256 updatedAt,bool stale)",
  `function getOrder(uint256 orderId) view returns (${orderTuple})`,
  "function previewFill(uint256 orderId,uint256 sellAmountOut) view returns (uint256 amountIn,uint256 fee,uint256 netOut)",
  "function previewFillForAmountIn(uint256 orderId,uint256 amountIn) view returns (uint256 sellAmountOut,uint256 actualAmountIn,uint256 fee,uint256 netOut)",
  "function fillOrder(uint256 orderId,uint256 sellAmountOut,uint256 maxAmountIn)",
  "event OrderFilled(uint256 indexed orderId,address indexed taker,address indexed maker,address sellToken,uint256 amountOut,uint256 amountIn,uint256 fee,uint256 sellRemaining)",
]);

export const lensAbi = parseAbi([
  "function swapper() view returns (address)",
  `function openOrders(uint256 offset,uint256 limit) view returns (uint256[] ids,${orderTuple}[] orders,uint256 nextOffset)`,
  "function quoteFill(uint256 orderId,uint256 sellAmountOut,address taker) view returns (uint256 amountIn,uint256 fee,uint256 netOut,uint8 problem)",
]);

export const erc20Abi = parseAbi([
  "function symbol() view returns (string)",
  "function decimals() view returns (uint8)",
  "function balanceOf(address) view returns (uint256)",
  "function allowance(address,address) view returns (uint256)",
  "function approve(address,uint256) returns (bool)",
]);

1. Connect and verify the selected market

The examples use viem, but the call sequence is library-independent.

import {
  createPublicClient,
  createWalletClient,
  custom,
  http,
  parseEventLogs,
  type Address,
} from "viem";
import {kaia} from "viem/chains";

const publicClient = createPublicClient({
  chain: kaia,
  transport: http("https://public-en.node.kaia.io"),
});

const walletClient = createWalletClient({
  chain: kaia,
  transport: custom(window.ethereum),
});

const market = {
  swapper: "0xd65b29B72599A99E1E8049a549869E1F8F7a3c0B" as Address,
  lens: "0xB341D5D2074924D81091e3f3cEcB14FCf8411675" as Address,
  base: "0x18Bc5bcC660cf2B9cE3cd51a404aFe1a0cBD3C22" as Address,
  quote: "0xd077A400968890Eacc75cdc901F0356c943e4fDb" as Address,
};

const [version, base, quote, paused, lensBinding] = await Promise.all([
  publicClient.readContract({address: market.swapper, abi: swapperAbi, functionName: "version"}),
  publicClient.readContract({address: market.swapper, abi: swapperAbi, functionName: "baseToken"}),
  publicClient.readContract({address: market.swapper, abi: swapperAbi, functionName: "quoteToken"}),
  publicClient.readContract({address: market.swapper, abi: swapperAbi, functionName: "paused"}),
  publicClient.readContract({address: market.lens, abi: lensAbi, functionName: "swapper"}),
]);

const same = (a: Address, b: Address) => a.toLowerCase() === b.toLowerCase();
if (version !== "1.2.0") throw new Error(`Unsupported Rondo version: ${version}`);
if (!same(base, market.base) || !same(quote, market.quote)) throw new Error("Token binding mismatch");
if (!same(lensBinding, market.swapper)) throw new Error("Lens is bound to another proxy");
if (paused) throw new Error("This market is paused");

Also read each token’s live symbol() and decimals(). The registry value is useful for validation, not a reason to run every token through JPYC’s 18-decimal conversion.

2. Read a consistent order book

Prefer Lens.openOrders to a separate openOrderIds → getOrders sequence. It returns each id and its tuple atomically. Pin a block across pages so an order closing between page requests cannot move an unseen id into a page already consumed.

const blockNumber = await publicClient.getBlockNumber();
const block = await publicClient.getBlock({blockNumber});

const book = [];
let offset = 0n;

while (true) {
  const [ids, orders, nextOffset] = await publicClient.readContract({
    address: market.lens,
    abi: lensAbi,
    functionName: "openOrders",
    args: [offset, 200n],
    blockNumber,
  });

  for (let i = 0; i < ids.length; i++) {
    const order = orders[i];
    // Storage may still say Open after the deadline until someone sweeps it.
    if (order.status === 1 && block.timestamp <= order.expiry) {
      book.push({id: ids[i], ...order});
    }
  }

  if (nextOffset === offset) break;
  offset = nextOffset;
}

Interpret an `Order`

Field	Meaning
`status`	`0 None · 1 Open · 2 Filled · 3 Cancelled · 4 Expired`
`kind`	`0 Fixed · 1 Pegged`
`sellToken`	Escrowed by the maker; the taker receives it
`buyToken`	Paid by the taker directly to the maker
`sellAmountOut`	Not stored: the gross `sellToken` amount requested by one fill
`feeBps`	Fee snapshot captured when the order was created
`sellRemaining`	Gross escrow still available
`buyAmount`	Fixed-order full proceeds; zero for Pegged orders
`premiumBps` · `minRate`	Pegged-order terms; zero for Fixed orders

If sellToken == baseToken, the maker offers the regional stablecoin and the taker pays USDT. If sellToken == quoteToken, the maker offers USDT and the taker pays the regional stablecoin.

Profitability is not a settlement guard. The contract accepts a valid in-band fixed order even when its current taker edge is negative. If your product promises “best” or “profitable” orders, compute and disclose that policy separately using the current oracle and the net output after fees.

3. Quote from what the taker wants to pay

Users commonly enter the token leaving their wallet, while fillOrder takes the gross output released from escrow. Convert the payment with previewFillForAmountIn:

import {parseUnits} from "viem";

const orderId = 1n;
const paymentDecimals = 6; // Read from order.buyToken; this example pays USDT.
const typedAmountIn = parseUnits("25", paymentDecimals);

const [sellAmountOut, actualAmountIn, fee, netOut] =
  await publicClient.readContract({
    address: market.swapper,
    abi: swapperAbi,
    functionName: "previewFillForAmountIn",
    args: [orderId, typedAmountIn],
  });

if (sellAmountOut === 0n) throw new Error("Payment is too small to release one token unit");

The return values are all raw token units:

sellAmountOut: gross escrow released and the second argument to fillOrder.
actualAmountIn: what the taker currently pays. It can be below the typed amount when the order remainder caps the fill.
fee: retained in the order’s sellToken.
netOut = sellAmountOut - fee: what reaches the taker’s wallet.

previewFill and previewFillForAmountIn price a fill but do not prove that it can settle. A quote can still be blocked by pause, expiry, size, role, balance or allowance. Use the Lens preflight and a transaction simulation before opening the wallet.

Minimum-fill rule

A full fill of sellRemaining is always allowed. Otherwise, while the order itself is at least minOrderAmount[sellToken], sellAmountOut must also reach that minimum. The rule is about the gross output in this fill, not the payment and not the remainder left behind.

4. Preflight, approve and fill

For Fixed orders, maxAmountIn should equal the quote because their rate cannot change. Pegged orders reprice from the five-minute Orakl reference when mined, so add a user-selected tolerance:

const order = await publicClient.readContract({
  address: market.swapper,
  abi: swapperAbi,
  functionName: "getOrder",
  args: [orderId],
});

const toleranceBps = 50n; // 0.50%; chosen by the taker
const maxAmountIn = order.kind === 1
  ? (actualAmountIn * (10_000n + toleranceBps)) / 10_000n
  : actualAmountIn;

const [account] = await walletClient.getAddresses();
if (!account) throw new Error("Connect a wallet first");

const canTake = await publicClient.readContract({
  address: market.swapper,
  abi: swapperAbi,
  functionName: "canTake",
  args: [account],
});
if (!canTake) throw new Error("This account cannot take orders while the gate is enabled");

const balance = await publicClient.readContract({
  address: order.buyToken,
  abi: erc20Abi,
  functionName: "balanceOf",
  args: [account],
});
if (balance < maxAmountIn) throw new Error("Insufficient payment-token balance");

const allowance = await publicClient.readContract({
  address: order.buyToken,
  abi: erc20Abi,
  functionName: "allowance",
  args: [account, market.swapper],
});

if (allowance < maxAmountIn) {
  const {request} = await publicClient.simulateContract({
    account,
    address: order.buyToken,
    abi: erc20Abi,
    functionName: "approve",
    args: [market.swapper, maxAmountIn],
  });
  const approvalHash = await walletClient.writeContract(request);
  await publicClient.waitForTransactionReceipt({hash: approvalHash});
}

const [amountInNow, feeNow, netOutNow, problem] =
  await publicClient.readContract({
    address: market.lens,
    abi: lensAbi,
    functionName: "quoteFill",
    args: [orderId, sellAmountOut, account],
  });
if (problem !== 0) throw new Error(`Fill preflight failed with problem ${problem}`);
if (amountInNow > maxAmountIn) throw new Error("Price moved beyond the selected tolerance");

const {request} = await publicClient.simulateContract({
  account,
  address: market.swapper,
  abi: swapperAbi,
  functionName: "fillOrder",
  args: [orderId, sellAmountOut, maxAmountIn],
});

const hash = await walletClient.writeContract(request);
const receipt = await publicClient.waitForTransactionReceipt({hash});
if (receipt.status !== "success") throw new Error("Fill reverted");

const [fill] = parseEventLogs({
  abi: swapperAbi,
  eventName: "OrderFilled",
  logs: receipt.logs,
  strict: true,
}).filter((log) => log.args.orderId === orderId);

if (!fill) throw new Error("Successful receipt did not contain this order's fill event");

Approve and compare the balance against maxAmountIn, not only the current Pegged quote. The Lens checks the current amountIn; fillOrder is the component that enforces the final ceiling.

Lens `FillProblem`

Value	Name	Action
0	`None`	Continue to simulation
1	`NotOpen`	Refresh the book
2	`Paused`	Do not submit
3	`NotWhitelisted`	Ask the operator or choose an eligible account
4	`Expired`	Refresh; anyone may sweep the order
5	`ZeroAmount`	Enter a positive size
6	`ExceedsRemaining`	Cap at `sellRemaining`
7	`BelowMinFill`	Raise the gross output to the current minimum or take all
8	`StaleOracle`	Pegged only; wait for the feed
9	`BelowMakerFloor`	Pegged order is temporarily unfillable
10	`InsufficientBalance`	Fund the taker’s payment token
11	`InsufficientAllowance`	Approve the Swapper proxy

Even None is not a settlement guarantee: the order may change before inclusion, maxAmountIn may be crossed, or a token transfer may be unavailable. Always simulate the exact transaction and still handle an on-chain revert.

5. Confirm and reconcile the settlement

Decode OrderFilled from the successful receipt. Its amounts are authoritative:

Event field	Accounting meaning
`amountOut`	Gross escrow released (`sellAmountOut`)
`amountIn`	Payment sent from taker to maker
`fee`	Protocol fee retained in `sellToken`
`amountOut - fee`	Net tokens received by the taker
`sellRemaining`	Order remainder after this fill

The maker’s average realised rate for a partially filled Pegged order must be reconstructed from its OrderFilled events because every fill can use a different oracle price. Sum raw amountIn and gross amountOut first, then apply token decimals when displaying the ratio. After the receipt, re-read getOrder(orderId). Do not predict whether the order is still open from the submitted amount alone: another fill may have landed first. For event indexing, scan from the market’s First event block in the registry, not genesis. Use bounded block windows because public RPC providers limit eth_getLogs, persist the last confirmed block, and make (chainId, proxy, txHash, logIndex) the event key. The events required to reconstruct the book are documented in Events & errors.

Maker integration

Making is permissioned per market. Check isMaker(account) before presenting an order form. Both order types escrow sellToken, so approve the Swapper for sellAmount before creation. Add these entries when supporting makers:

export const makerAbi = parseAbi([
  "function isMaker(address) view returns (bool)",
  "function feeBps() view returns (uint16)",
  "function bandBps() view returns (uint16)",
  "function maxOrderDuration() view returns (uint64)",
  "function maxPremiumBps() view returns (uint16)",
  "function minOrderAmount(address) view returns (uint256)",
  "function isWithinBand(address sellToken,uint256 sellAmount,address buyToken,uint256 buyAmount) view returns (bool)",
  "function peggedRateNow(address sellToken,uint16 premiumBps,uint16 feeBps) view returns (uint256)",
  "function createOrder(address sellToken,uint256 sellAmount,address buyToken,uint256 buyAmount,uint64 expiry) returns (uint256 orderId)",
  "function createPeggedOrder(address sellToken,uint256 sellAmount,uint16 premiumBps,uint256 minRate,uint64 expiry) returns (uint256 orderId)",
  "function cancelOrder(uint256 orderId)",
  "event OrderCreated(uint256 indexed orderId,address indexed maker,address indexed sellToken,address buyToken,uint256 sellAmount,uint256 buyAmount,uint64 expiry,uint16 feeBps,uint256 oracleAnswer)",
  "event PeggedOrderCreated(uint256 indexed orderId,address indexed maker,address indexed sellToken,address buyToken,uint256 sellAmount,uint16 premiumBps,uint256 minRate,uint64 expiry,uint16 feeBps,uint256 oracleAnswer)",
  "event OrderCancelled(uint256 indexed orderId,address indexed by,bool forced,uint256 refunded)",
]);

Fixed order

Read minOrderAmount(sellToken), maxOrderDuration, bandBps and oracle freshness.
Convert both amounts using their own decimals.
Call isWithinBand(sellToken,sellAmount,buyToken,buyAmount).
Simulate and send createOrder(address,uint256,address,uint256,uint64).
Decode OrderCreated from the receipt to obtain the final orderId.

The contract reads the oracle only when a Fixed order is created. Its later fills use the posted ratio and continue during an oracle outage.

Oracle-pegged order

Read feeBps, bandBps, maxPremiumBps, maxOrderDuration and the current oracle state.
Ensure premiumBps <= maxPremiumBps.
Read currentRate = peggedRateNow(sellToken,premiumBps,feeBps).
Choose a floor tolerance no wider than bandBps and calculate minRate = currentRate × (10,000 − toleranceBps) / 10,000.
Simulate and send createPeggedOrder(sellToken,sellAmount,premiumBps,minRate,expiry).
Decode PeggedOrderCreated for the orderId and terms accepted on-chain.

minRate is buy-token raw units per RATE_SCALE = 1e18 gross sell-token units. Do not construct it from a formatted decimal string; use peggedRateNow and integer arithmetic. A Pegged fill requires a fresh oracle and stops automatically below the maker’s floor. Cancellation remains available.

premiumBps is the taker’s edge after the fee, not the maker’s total cost. At a 25 bps premium and 30 bps fee, the maker gives up roughly 55 bps. Pricing details.

Makers cancel with cancelOrder(orderId). It works while paused and after expiry, and returns the remaining escrow. Anyone may call expireOrders(ids) after deadlines; refunds still go only to the makers. Add the following directly provided error ABI when simulating or decoding:

export const swapperErrorAbi = parseAbi([
  "error AccessControlUnauthorizedAccount(address,bytes32)",
  "error BelowMakerFloor(uint256,uint256)",
  "error BelowMinFill(uint256,uint256)",
  "error BelowMinOrderAmount(uint256,uint256)",
  "error DurationTooLong(uint64,uint64)",
  "error EnforcedPause()",
  "error ExceedsRemaining(uint256,uint256)",
  "error FloorAboveMarket(uint256,uint256)",
  "error FloorTooLoose(uint256,uint256)",
  "error InvalidExpiry(uint64)",
  "error InvalidOracleAnswer(int256)",
  "error OracleTwapUnavailable()",
  "error InvalidTokenPair(address,address)",
  "error NotOrderMaker(uint256,address)",
  "error OrderExpired(uint256,uint64)",
  "error OrderNotOpen(uint256,uint8)",
  "error PremiumTooHigh(uint16,uint16)",
  "error PriceOutOfBand(uint256,uint256,uint256)",
  "error ReentrancyGuardReentrantCall()",
  "error SafeCastOverflowedUintDowncast(uint8,uint256)",
  "error SafeERC20FailedOperation(address)",
  "error SlippageExceeded(uint256,uint256)",
  "error StaleOracle(uint256,uint64)",
  "error TakerNotWhitelisted(address)",
  "error UnexpectedTransferAmount(uint256,uint256)",
  "error UnsupportedToken(address)",
  "error ZeroAddress()",
  "error ZeroAmount()",
  "error ZeroMakerFloor()",
]);

Combine it with the flow ABI before decoding:

import {decodeErrorResult} from "viem";

try {
  await publicClient.simulateContract(/* exact request */);
} catch (error) {
  const data = extractRevertData(error); // library/app-specific error traversal
  const decoded = decodeErrorResult({abi: [...swapperAbi, ...swapperErrorAbi], data});
  console.error(decoded.errorName, decoded.args);
}

At minimum, provide explicit recovery for OrderNotOpen, OrderExpired, BelowMinFill, ExceedsRemaining, SlippageExceeded, StaleOracle, OracleTwapUnavailable, BelowMakerFloor, EnforcedPause, TakerNotWhitelisted and ERC-20 transfer failures. Refresh order and configuration state after any revert instead of resubmitting the same arguments. Complete error meanings.

Integration checklist

Assert Kaia chain id 8217 before every write.
Treat (chainId, proxy, orderId) as the order identity.
Verify version, baseToken, quoteToken and lens.swapper at startup.
Read token symbols and decimals from the actual token contracts.
Pin one block across all order-book pages.
Filter dynamically expired orders even if stored status is still Open.
Use contract quotes for transaction arguments; local math is display-only.
Remember that sellAmountOut is gross and the taker receives sellAmountOut - fee.
For Pegged orders, approve and fund maxAmountIn, not only the current quote.
Run Lens preflight, then simulate the exact write with the real account.
Decode the receipt event and re-read the order after confirmation.

Contract API

User-facing callable signatures and tuple layout.

ABI JSON

Complete copy-ready Swapper and Lens ABI arrays.

The Lens

Atomic paging and guard-aware preflight behaviour.

Events & errors

Settlement logs and recoverable revert reasons.

Building an interface

UX rules once the direct contract integration is correct.

Contract reference

Integration guides

Integrate the contracts

Read

Trade

Reconcile

Integration model

Production registry

Obtain the ABI

1. Connect and verify the selected market

2. Read a consistent order book

Interpret an `Order`

3. Quote from what the taker wants to pay

Minimum-fill rule

4. Preflight, approve and fill

Lens `FillProblem`

5. Confirm and reconcile the settlement

Maker integration

Fixed order

Oracle-pegged order

Decode failures into user actions

Integration checklist

Contract API

ABI JSON

The Lens

Events & errors

Building an interface

Read

Trade

Reconcile

​Integration model

​Production registry

​Obtain the ABI

​1. Connect and verify the selected market

​2. Read a consistent order book

​Interpret an Order

​3. Quote from what the taker wants to pay

​Minimum-fill rule

​4. Preflight, approve and fill

​Lens FillProblem

​5. Confirm and reconcile the settlement

​Maker integration

​Fixed order

​Oracle-pegged order

​Decode failures into user actions

​Integration checklist

​Related references

Contract API

ABI JSON

The Lens

Events & errors

Building an interface

Integration model

Production registry

Obtain the ABI

1. Connect and verify the selected market

2. Read a consistent order book

Interpret an `Order`

3. Quote from what the taker wants to pay

Minimum-fill rule

4. Preflight, approve and fill

Lens `FillProblem`

5. Confirm and reconcile the settlement

Maker integration

Fixed order

Oracle-pegged order

Decode failures into user actions

Integration checklist

Related references