Technical Integration
Purpose: Connect the partner's systems to Ratio's SOL infrastructure, configure partner-specific parameters, and establish secure communication channels.
1. Credential Issuance
Upon compliance clearance, the Ratio admin provisions the partner in the system:
| Credential | Format | Scope | Rotation Policy |
|---|---|---|---|
| Partner ID (X-Partner-ID) | UUID | All API requests; fee routing and audit trail | Permanent (revoke on offboarding) |
| API Key (Bearer Token) | 256-bit random | Authentication for all API endpoints | 90-day rotation; emergency revoke capability |
| Sandbox API Key | 256-bit random | Testnet access only; no real funds | No rotation required |
| Webhook Secret | HMAC-SHA256 key | Partner verifies callback authenticity | 90-day rotation aligned with API key |
| Wallet Whitelist | Kaia address(es) | LP deposits and withdrawal destinations | Add/remove via admin; requires 24h cooling |
2. Partner Configuration (Admin-Set)
All partner-specific parameters are stored off-chain in the Admin Config Store and are readable by the routing engine and FX engine. These are configured by Ratio admin during onboarding, not by the partner directly.
| Parameter | Applies To | Example | Set By |
|---|---|---|---|
| Corridors Enabled | All | [USD-IDR, USD-SGD] | Admin (per licence map) |
| Volume Limit (Daily) | All | $500K per corridor | Admin (compliance-derived) |
| Volume Limit (Monthly) | All | $10M aggregate | Admin (commercial terms) |
| Fee Tier Multiplier | LP | 0.3× (issuer), 1.0× (retail) | Admin (per Liquidity Onboarding config) |
| Liquidity Intent Class | LP | Class A (FX-Only) | Admin (per partner choice) |
| Deposit Acceptance | LP | Enabled / Disabled | Admin |
| Webhook URL | On/Off-Ramp | https://partner.com/ratio/callback | Partner (verified by Ratio) |
| Settlement Currency | Off-Ramp | IDRX, MYRC | Admin (per corridor) |
| Fee Tier Override | LP, On/Off-Ramp | Custom variable bips and spread bps per corridor per size tier. NULL values use standard tier defaults. | Admin (per Fee Tiers) |
| RFQ Access Tier | RFQ | Tier 1 (auto-eligible) | Admin |
3. Integration Tracks by Partner Type
On-Ramp / Off-Ramp Partners
- SOL Communication Layer integration — implement standardised messaging templates (SWIFT-style) for deposit confirmations, beneficiary validation, transaction status, and rollback signals.
- FX Engine API integration — implement GET /v1/quote (indicative pricing), POST /v1/quote (firm quote), and POST /v1/execute (trade execution) endpoints.
- Webhook receiver setup — implement callback endpoint for trade confirmations, settlement status, and error notifications.
- KYC/KYB data relay — if the partner handles end-user KYC, configure data-sharing templates for Travel Rule compliance.
- Fiat rail mapping — map local fiat rails (bank transfer, e-wallet, card) to standardised Ratio data templates (bank info, SWIFT/IBAN, beneficiary details).
Stablecoin Issuer Partners
- Mint/Redeem API integration — configure mint and redeem endpoints for on-demand liquidity provisioning (used by Smart Rebalancing escalation for issuer-heavy pools).
- Reserve Pool deposit flow — as Class A LP, verify deposit routing is 100% Reserve Pool with kXXX-fx token issuance.
- Proof of Reserve (POR) integration — if issuer publishes POR data, configure feed for Ratio's internal validation checks.
- Emergency minting protocol — establish on-demand minting path for deficit recovery scenarios (Smart Rebalancing escalation).
LP Partners (Institutional / Retail Aggregators)
- Wallet whitelisting — register Kaia wallet address(es) for deposits and withdrawals.
- LP class and fee tier configuration — admin sets Class A or B, fee multiplier, per Liquidity Onboarding architecture.
- Deposit routing verification — test deposit flow through routing engine to confirm correct pool allocation.
- kToken receipt verification — confirm correct kXXX-fx or kXXX-full tokens are received in partner wallet.
RFQ Counterparties
- RFQ API integration — implement quote request/response endpoints for Liquidity Hub's rebalancing flow.
- Settlement flow — configure on-chain settlement paths for successful RFQ executions.
- Latency & reliability SLA — agree on maximum quote response time and uptime requirements.
- Credit/netting terms configuration — if bilateral netting applies, configure netting window and settlement schedule.
Distribution Partners
- SOL API / SDK integration — full API access for quote, execute, and status endpoints; or SDK wrapper for simplified integration.
- White-label configuration (if applicable) — custom branding, fee passthrough rules, and end-user facing components.
- Webhook and notification setup — real-time transaction status callbacks for their end-user experience.
4. Communication Layer Setup
- Message format alignment: partner's data mapped to Ratio's ISO 20022-inspired templates for bank info, SWIFT details, beneficiary data, and transaction confirmations.
- Event subscription: partner subscribes to relevant event streams (transaction status, settlement confirmations, balance notifications).
- Encryption: all API communications over TLS 1.3; webhook payloads signed with partner-specific HMAC keys.
Estimated Duration: 2–6 weeks (depending on partner technical maturity)