Executing Swaps

Ratio does not execute trades on the partner’s behalf. POST /v1/firm-quote returns an EIP-712 signature and ready-to-send calldata — the partner submits the transaction on-chain themselves. The on-chain commitFirmQuote call is the execution — commit and execute are a single atomic transaction.

Execution flow

Approve token spend (one-time per token)

Call approve() on the input token’s ERC-20 contract, granting the FxEngine contract (see Contract details, or execution.contract from a firm quote) permission to spend the input token. Use type(uint256).max for a one-time unlimited approval. Approve before requesting the firm quote you will execute — firm quotes expire after 60 seconds.

Get a firm quote (off-chain)

Call POST /v1/firm-quote → receive quote, backend_signature, and execution (contract address + calldata).

Submit on-chain transaction

Send a transaction to execution.contract with execution.calldata. No manual struct assembly or signing required — the calldata encodes everything.

Contract validates and settles

The FxEngine contract verifies Ratio’s backend signature, checks expiry and nonce, validates amounts, and performs the atomic swap in that same transaction.

Verify settlement

Call GET /v1/executions?quote=0x{quote_id} (or ?tx=0x{tx_hash}) to confirm settlement. Returns 404 if not yet indexed — retry after a few seconds.

On-chain execution

The partner sends the transaction using the values from the firm quote response:

const tx = await wallet.sendTransaction({
  to: firmQuote.execution.contract,
  data: firmQuote.execution.calldata,
  value: firmQuote.execution.value,
  chainId: firmQuote.execution.chain_id,
});

console.log("Submitted:", tx.hash);
const receipt = await tx.wait();
console.log("Confirmed in block", receipt.blockNumber);

tx = {
    "to": firm_quote["execution"]["contract"],
    "data": firm_quote["execution"]["calldata"],
    "value": int(firm_quote["execution"]["value"]),
    "chainId": firm_quote["execution"]["chain_id"],
}
signed = w3.eth.account.sign_transaction(tx, private_key)
tx_hash = w3.eth.send_raw_transaction(signed.raw_transaction)
receipt = w3.eth.wait_for_transaction_receipt(tx_hash)

On-chain enforcement

The FxEngine contract enforces the following:

msg.sender must equal quote.partner — the partner is the caller, no separate executor
The signature must recover to an authorised swapSigner in RatioConfig
Replay protection via signerNoncesUsed[signer][quote.nonce] — each quoteId can only be committed once
block.timestamp <= quote.expiresAt
The quote’s risk state must not be HALT
The quoted prices must be fresh and within the corridor’s allowed deviation from Orakl Network price feeds on Kaia
The corridor must be enabled and amountIn (in USD) must be within the corridor’s min/max
fixFee + variableFee < amountIn and spreadFee < amountOut

Contract details

Property	Sandbox	Production
Chain ID	`1001` (Kaia Kairos)	`8217` (Kaia mainnet)
FxEngine contract	`0xbc925d8D6a3d30CCFE6Fc4B6A23A7BCb6FEe4cE1` (also returned as `execution.contract`)	Use `execution.contract` from the API response
Method	`commitFirmQuote`	`commitFirmQuote`

function commitFirmQuote(
    FirmQuote calldata quote,
    bytes calldata signature
) external nonReentrant notPaused;

Complete flow example

GET  /v1/corridors                    → discover corridor_id + token addresses
GET  /v1/rates                        → check current mid-market rates
POST /v1/quote                        → indicative price (optional)
approve(FxEngine, amount)             → one-time ERC-20 approval (on-chain)
POST /v1/firm-quote                   → quote_id + backend_signature + calldata
commitFirmQuote(quote, signature)     → atomic swap (on-chain)
GET  /v1/executions?quote=0x{id}      → verify settlement

Error cases

Scenario	Cause	Resolution
Quote expired	`block.timestamp > expiresAt`	Request a new firm quote
Insufficient allowance	Input token not approved for FxEngine	Call `approve()` before executing
Nonce already used	Same quote submitted twice	Each quote can only be executed once
Wrong sender	`msg.sender != quote.partner`	Execute from the registered wallet
Corridor halted	Risk state is `HALT`	Check `GET /v1/corridors` and wait for recovery

Get Started

Features

Architecture

Integration

Partners

Resources

Executing Swaps

Execution flow

On-chain execution

On-chain enforcement

Contract details

Complete flow example

Error cases

​Execution flow

​On-chain execution

​On-chain enforcement

​Contract details

​Complete flow example

​Error cases

Execution flow

On-chain execution

On-chain enforcement

Contract details

Complete flow example

Error cases