Volume-Tiered Fee Schedule
1. Overview
Ratio uses a volume-tiered fee schedule where the platform fee (fixed + variable) and base spread vary by transaction size, per corridor. Larger transactions receive lower variable fees — mirroring institutional FX pricing where volume earns better rates.
Every corridor has its own set of fee tiers. Each tier defines a transaction size band with its own fixed fee, variable fee rate, and optional base spread override. The system resolves the applicable tier at quote time and the resolved fees flow through the entire pipeline.
- All fee tier parameters are stored in the database and configurable by admin. Zero hardcoded values.
- Fee tiers are per corridor — USD-IDR, USD-SGD, and MYR-IDR each have independent tier schedules.
- The fixed fee is denominated in the destination currency (e.g., IDR for USD→IDR swaps) but deducted from the source amount after conversion at oracle rate.
- The tier's base spread overrides only the Base component of the spread. Volatility, Liquidity, and Inventory Skew add-ons are still calculated dynamically on top.
- Partners can receive further discounts via per-partner tier overrides on top of the standard schedule.
- Transactions below the smallest tier's minimum are rejected.
2. Fee Tier Structure
Each fee tier defines:
| Field | Description | Example (USD-IDR, Small Tier) |
|---|---|---|
| Tier Name | Human-readable label | SMALL |
| Min Amount | Minimum transaction size (inclusive, in source currency) | $1,000 |
| Max Amount | Maximum transaction size (exclusive, 0 = unlimited) | $10,000 |
| Fixed Fee | Flat fee per transaction, denominated in destination currency | 10,000 IDR |
| Variable Fee | Percentage of source amount, in basis points | 5 bips (0.05%) |
| Spread Override | Replaces Base Spread component. 0 = use corridor default. | 20 bps |
Fee Resolution Priority
When calculating fees for a transaction, the system resolves parameters in this priority order:
Partner tier override → Fee tier default → Corridor default → Global fallback
- If the partner has a
partner_fee_tier_overridefor this corridor and tier → use override values - Else use the
fee_tierstable values for this corridor and size band - For spread: if tier's
spread_override_bps = 0→ use corridor'sbase_spread_bpsfrom corridor config - For corridors with no fee tiers configured → use global flat fees from protocol params (backward compatible)
3. Phase 1 Corridor Fee Schedules
USD-IDR (Source: USDT → Destination: IDRX)
| Tier | Size Band (USD) | Fixed Fee (IDR) | Variable (%) | Variable (bips) | Base Spread (bps) | Total Var + Spread |
|---|---|---|---|---|---|---|
| Micro | $10 – $1,000 | 10,000 | 0.10% | 10 | 20 | 0.30% |
| Small | $1,000 – $10,000 | 10,000 | 0.05% | 5 | 20 | 0.25% |
| Medium | $10,000 – $50,000 | 10,000 | 0.02% | 2 | 20 | 0.22% |
| Large | $50,000 – $200,000 | 10,000 | 0.01% | 1 | 15 | 0.16% |
| Institutional | $200,000+ | 0 | 0.01% | 1 | 10 | 0.11% |
USD-SGD (Source: USDT → Destination: tnSGD)
| Tier | Size Band (USD) | Fixed Fee (SGD) | Variable (%) | Variable (bips) | Base Spread (bps) |
|---|---|---|---|---|---|
| Micro | $10 – $1,000 | 1.00 | 0.10% | 10 | 15 |
| Small | $1,000 – $10,000 | 1.00 | 0.05% | 5 | 15 |
| Medium | $10,000 – $50,000 | 1.00 | 0.02% | 2 | 10 |
| Large | $50,000 – $200,000 | 0 | 0.01% | 1 | 8 |
| Institutional | $200,000+ | 0 | 0.01% | 1 | 5 |
MYR-IDR (Source: MYRC → Destination: IDRX)
Size bands are in MYR (source currency).
| Tier | Size Band (MYR) | Fixed Fee (IDR) | Variable (%) | Variable (bips) | Base Spread (bps) |
|---|---|---|---|---|---|
| Micro | 50 – 2,500 | 10,000 | 0.15% | 15 | 25 |
| Small | 2,500 – 25,000 | 10,000 | 0.08% | 8 | 25 |
| Medium | 25,000 – 150,000 | 10,000 | 0.03% | 3 | 20 |
| Large | 150,000+ | 0 | 0.02% | 2 | 15 |
4. Fee Calculation Flow
Step-by-Step: $5,000 USDT → IDRX Swap
Step 1 — Tier Resolution:
The system looks up the fee_tiers table for USD-IDR and walks tiers in order. $5,000 falls in the SMALL tier ($1,000 – $10,000).
Step 2 — Partner Override:
If the requesting partner has a partner_fee_tier_override for USD-IDR + SMALL tier, those custom values take priority. Otherwise, standard tier rates apply.
Step 3 — Platform Fee Calculation:
Fixed Fee (in IDR) = 10,000 IDR
Fixed Fee (in USD) = 10,000 / 15,800 (oracle rate) = $0.633
Variable Fee = $5,000 × 0.05% = $2.50
Total Platform Fee = $0.633 + $2.50 = $3.133
Amount to Convert = $5,000 − $3.133 = $4,996.87
The fixed fee is stored in destination currency (IDR) but deducted from the source amount (USD) after conversion at the current oracle rate. This means the fixed fee's USD cost fluctuates with the exchange rate — when IDR is strong, the USD cost of the fixed fee is slightly higher.
Step 4 — Spread Construction:
The tier's spread_override_bps = 20 replaces only the Base component. Dynamic components still add on top:
Base Spread (from tier) = 20 bps
+ Volatility Add-on = 2 bps (from real-time oracle movement)
+ Liquidity Add-on = 1 bps (based on trade size vs pool depth)
+ Inventory Skew = 3 bps (from Active Pool imbalance)
─────────────────────────────────────
Total Spread = 26 bps
Step 5 — Quote & Execution:
The quote response includes the complete fee breakdown. On execution, the total profit (platform fee + spread profit) is split 50/30/20 as normal.
5. Tier Comparison: Same Corridor, Different Sizes
Corridor: USD-IDR | Oracle Rate: 15,800 IDR/USD
| Swap Size | Tier | Fixed (USD) | Variable (USD) | Total Fee (USD) | Fee % | Spread (bps) |
|---|---|---|---|---|---|---|
| $100 | Micro | $0.63 | $0.10 | $0.73 | 0.73% | 20 + dynamic |
| $5,000 | Small | $0.63 | $2.50 | $3.13 | 0.06% | 20 + dynamic |
| $25,000 | Medium | $0.63 | $5.00 | $5.63 | 0.02% | 20 + dynamic |
| $100,000 | Large | $0.63 | $10.00 | $10.63 | 0.01% | 15 + dynamic |
| $500,000 | Institutional | $0.00 | $50.00 | $50.00 | 0.01% | 10 + dynamic |
The fee as a percentage of transaction size decreases sharply with volume. Micro transactions pay the highest percentage (dominated by the fixed fee), while institutional transactions pay a near-zero percentage.
6. Minimum Transaction Size
Each corridor's smallest tier defines the minimum transaction size. Transactions below this minimum are rejected with error code BELOW_MIN_TRANSACTION_SIZE.
| Corridor | Minimum | Currency | Rationale |
|---|---|---|---|
| USD-IDR | $10 | USD | Below $10, the fixed fee ($0.63) dominates and the swap is uneconomical |
| USD-SGD | $10 | USD | Same rationale as USD-IDR |
| MYR-IDR | 50 MYR | MYR | ~$10.60 USD equivalent; aligned with USD corridors |
These minimums are configurable per corridor via the fee_tiers table. Adjusting the smallest tier's min_amount changes the minimum transaction size.
7. Partner Fee Tier Overrides
Strategic partners can receive custom rates per corridor per tier. This is a separate layer on top of the standard fee schedule — the tier resolution logic is the same, but the final rates may differ.
| Partner | Corridor | Tier | Custom Variable | Custom Spread | Use Case |
|---|---|---|---|---|---|
| IDRX Issuer | USD-IDR | All tiers | 1 bip | 5 bps | Deep IDR liquidity provider; lowest possible cost |
| Enterprise PSP | USD-IDR | Medium+ | 1 bip | 10 bps | High-volume remittance operator |
| Strategic Bank | USD-SGD | All tiers | 0 bips | 3 bps | Anchor liquidity for SGD corridor |
Partner overrides are stored in partner_fee_tier_overrides. NULL values mean "use the standard tier default". Overrides are set by admin during Partner Onboarding.
8. Interaction with Other Fee Components
Spread Construction
The tier's spread_override_bps replaces only the Base component of the four-part spread formula:
Total Spread = Tier Base (or corridor default if override = 0)
+ Volatility Add-on (dynamic, from oracle movement)
+ Liquidity Add-on (dynamic, from trade size vs pool depth)
+ Inventory Skew (dynamic, from Active Pool imbalance)
See FX Engine — Pricing Engine for the full spread construction logic and Inventory Skew for the skew calculation.
50/30/20 Revenue Split
The tiered fee structure does not change how revenue is distributed. The total profit from any swap (platform fee + spread profit) is still split:
- 50% → Protocol Treasury (KF)
- 30% → Transaction LP Reward (corridor pools)
- 20% → Global Fee Pool (non-corridor pools)
See Profit Distribution for the full distribution logic.
Per-Partner LP Multiplier
The ClassA_fee_tier_multiplier from Liquidity Onboarding is a separate concept. It controls how LP rewards are distributed among Class A and Class B LPs — it does not affect the user-facing fee. A stablecoin issuer with a 0.3× LP multiplier still pays the same swap fees as any other user; they just earn less from the LP reward share.
9. Adding Fee Tiers for a New Corridor
When a new corridor (e.g., USD-JPY) is added, fee tiers are configured via a single SQL insert:
INSERT INTO fee_tiers (corridor_id, tier_name, tier_order, min_amount, max_amount,
fixed_fee_in_to_token, variable_fee_bips, spread_override_bps) VALUES
('USD-JPY', 'MICRO', 1, 10, 1000, 150, 10, 12),
('USD-JPY', 'SMALL', 2, 1000, 10000, 150, 5, 12),
('USD-JPY', 'MEDIUM', 3, 10000, 50000, 150, 2, 8),
('USD-JPY', 'LARGE', 4, 50000, 200000, 0, 1, 5),
('USD-JPY', 'INSTITUTIONAL', 5, 200000, 0, 0, 1, 3);
No code changes required. The CorridorRegistry loads the new tiers at next reload.
10. Quote Response — Fee Breakdown
Every quote response (indicative and firm) includes a fee_breakdown object showing the resolved tier and all fee components:
{
"quote_id": "QT-8821-USD-IDR",
"pair": "USD-IDR",
"amount": 5000,
"fee_breakdown": {
"tier": "SMALL",
"fixed_fee": 0.633,
"fixed_fee_currency": "USD",
"fixed_fee_in_dest": 10000,
"fixed_fee_dest_currency": "IDR",
"variable_fee": 2.50,
"variable_fee_bips": 5,
"base_spread_bps": 20,
"total_spread_bps": 26,
"total_fee_usd": 3.133,
"amount_to_convert": 4996.87,
"is_partner_override": false
},
"bid": 15940.00,
"ask": 16020.00,
"adjusted_mid": 15980.00,
"spread_bps": 26,
"state_flag": "NORMAL"
}
This transparency is critical for institutional partners — they see exactly which tier was applied and every fee component before committing.