> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ratiofx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# System Overview

> High-level architecture of the Ratio Stablecoin Orchestration Layer

Ratio uses a hybrid architecture — combining the trust and auditability of on-chain settlement with the performance and flexibility of off-chain orchestration. Partners experience instant settlement; inventory management and risk monitoring happen behind the scenes.

## Design philosophy

Ratio's FX Engine mirrors how institutional FX dealer desks operate — using oracle-based pricing, rules-based spread construction, and inventory-aware mid-rate adjustment — rather than an AMM bonding curve. The goal is predictable, institutionally acceptable execution with zero AMM slippage and full on-chain auditability.

<Note>
  The architecture separates the user experience (instant settlement) from market execution (inventory management). Partners always receive instant, atomic settlement regardless of the protocol's internal inventory position.
</Note>

## Architecture layers

<img src="https://mintcdn.com/ratiolabs/_WZ1jJo-JiN7xW7b/images/system-architecture.svg?fit=max&auto=format&n=_WZ1jJo-JiN7xW7b&q=85&s=9366bfb8c301205f9521c0a04ea692b0" alt="System Architecture" width="680" height="310" data-path="images/system-architecture.svg" />

Ratio consists of three layers:

<AccordionGroup>
  <Accordion title="On-chain layer (Kaia blockchain)">
    Handles everything that requires trust and immutability:

    * **Swap execution** — Atomic FX swaps that settle in a single transaction
    * **Pool accounting** — Stablecoin pool balances, LP token management, and fee distribution
    * **Oracle price feeds** — Real-time FX rates from institutional-grade oracles pushed on-chain
    * **LP token mechanics** — kToken minting, burning, and auto-compounding of swap fee rewards

    All settlement data is recorded on-chain, providing an immutable audit trail for every transaction.
  </Accordion>

  <Accordion title="Off-chain layer (backend services)">
    Handles everything that requires speed and flexibility:

    * **FX quote construction** — Multi-step pricing pipeline that fetches oracle rates, evaluates risk conditions, constructs spreads, and issues executable quotes
    * **Risk monitoring** — Continuous evaluation of oracle health, market volatility, pool inventory, and system exposure
    * **Inventory rebalancing** — Coordination with external market makers to restore pool health when imbalances exceed thresholds
    * **Partner and configuration management** — Partner credentials, fee schedules, corridor parameters, and operational controls
  </Accordion>

  <Accordion title="Partner integration layer (API)">
    Partners interact with Ratio through a REST API that abstracts all internal complexity. The API supports:

    * Two quote types (indicative and firm)
    * Webhook-based event notifications
    * Real-time system health queries
    * Full fee transparency in every response

    Partners request quotes, execute swaps, and receive settlement confirmations without interacting with the blockchain directly.
  </Accordion>
</AccordionGroup>

## How the layers interact

A typical swap flows through all three layers:

<Steps>
  <Step title="Partner requests a quote">
    Via the REST API (integration layer).
  </Step>

  <Step title="Backend constructs the quote">
    Fetches oracle prices, checks risk conditions, builds spread (off-chain layer).
  </Step>

  <Step title="Partner accepts the quote">
    Submits execution request via the API.
  </Step>

  <Step title="Swap executes atomically on Kaia">
    Source pool debited, destination pool credited, fees distributed (on-chain layer).
  </Step>

  <Step title="Settlement confirmation returned">
    Via API response and/or webhook callback.
  </Step>
</Steps>

The entire flow completes in seconds. From the partner's perspective, it's a single API call that returns a confirmed settlement.

## Smart contract architecture

Ratio's on-chain components are deployed as purpose-built smart contracts on Kaia. The contracts handle swap execution, pool management, fee collection and distribution, oracle price aggregation, and LP deposit/withdrawal accounting.

All contracts are upgradeable and configurable — pool parameters, fee schedules, and operational thresholds can be updated without redeploying contracts or interrupting service.

## Scalability

<CardGroup cols={2}>
  <Card title="New corridors" icon="route">
    Adding a currency pair requires only configuration (oracle feeds, pool parameters, fee tiers). No code changes or contract deployments.
  </Card>

  <Card title="New stablecoins" icon="coins">
    Each stablecoin gets its own pool. Adding a stablecoin is an operational task, not an engineering one.
  </Card>

  <Card title="Volume growth" icon="chart-line">
    The off-chain pricing engine handles quote construction independently of on-chain throughput. Kaia's sub-second blocks support high transaction volumes.
  </Card>

  <Card title="Partner growth" icon="users">
    Partner-specific configuration (fee overrides, corridor access, volume limits) is managed without protocol changes.
  </Card>
</CardGroup>