Ratio provides a dedicated sandbox environment on Kaia’s Kairos testnet that mirrors production behaviour. Use the sandbox to develop, test, and certify your integration before any real funds flow.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.
Sandbox environment
| Property | Value |
|---|---|
| Base URL | https://api.sandbox.ratiofx.com |
| Blockchain | Kaia Kairos (testnet) |
| Stablecoins | Test tokens (no real value) |
| Oracle feeds | Simulated feeds with configurable scenarios |
| Pool balances | Mock balances matching production structure |
The sandbox exposes the same API endpoints as production with identical request/response formats. Your integration code should work in both environments with only a base URL and API key change.
Getting sandbox access
Sandbox credentials are issued during Stage 3 (Technical integration) of onboarding:- Sandbox API key — Separate from your production key; no rotation required during testing
- Partner ID — The same UUID used in both sandbox and production
- Webhook secret — A separate sandbox secret for testing callback delivery
Test scenarios
The sandbox supports configurable test scenarios for edge case testing.Normal operation
Normal operation
Default state. All corridors active, oracle feeds fresh, pools healthy. Use this for happy-path testing — verifying the full quote → execute → settle → confirm flow for each corridor you intend to support.
State transitions
State transitions
Simulate system state changes to test how your integration handles protective states and trading halts. Verify that your UI degrades gracefully when corridors are paused or the system enters a protective state.
Oracle failures
Oracle failures
Simulate stale oracle data or source divergence. Verify that your error handling correctly processes
ORACLE_STALE and ORACLE_DEVIATION errors and presents appropriate messaging to downstream users.Quote expiry
Quote expiry
Request a firm quote and wait for it to expire before attempting execution. Verify that your flow handles the
QUOTE_EXPIRED error and re-requests a fresh quote without requiring manual intervention.Volume limits
Volume limits
Submit transactions that exceed configured daily or monthly limits. Verify that rejections are handled gracefully and that your system does not retry automatically in a way that could cause duplicate submissions.
Webhook delivery
Webhook delivery
Verify that your webhook endpoint receives all event types, validates HMAC signatures correctly, and handles duplicate delivery idempotently. Ratio may deliver the same event more than once; your handler must be safe to call multiple times with the same payload.
Certification test cases
You must pass all mandatory test cases before production activation. The full set of categories is listed below.| Category | Description | Applicable to |
|---|---|---|
| Happy path | End-to-end: quote → execute → settle → confirm for each enabled corridor | All partners |
| Quote expiry | Attempt execution on expired quote; verify rejection and re-quote flow | All partners |
| State scenarios | Test behaviour under different system states | All partners |
| Volume limits | Exceed daily/monthly limits; verify graceful rejection | All partners |
| Webhook delivery | Verify callbacks received, HMAC signature validated, idempotent handling | All partners |
| Auth failure | Invalid API key, expired token, wrong Partner ID — verify clean error responses | All partners |
| Error and rollback | Simulate settlement failure; verify error handling | All partners |
| Reconciliation | Daily reconciliation of stablecoin-in vs. fiat-out; zero discrepancy target | All partners |
| Deposit routing | Verify stablecoin deposit reaches correct pool | LP and Issuer |
| kToken issuance | Verify kToken received on deposit; verify balance increases with fee accrual | LP and Issuer |
| Withdrawal cooldown | Signal withdrawal intent; verify cooldown enforced before processing | LP and Issuer |
| Quote-response SLA | Respond to automated RFQ requests within the required latency target | RFQ counterparty |
SLA targets
During sandbox testing, demonstrate the following SLA targets before certification is granted.| Metric | Target | Measurement |
|---|---|---|
| API uptime | 99.5% | Monthly uptime |
| Quote response time | < 2 seconds | P95 latency for /v1/quote and /v1/firm-quote |
| Fiat → stablecoin conversion | < 30 minutes | Time from fiat receipt to stablecoin delivery (On-Ramp) |
| Stablecoin → fiat payout | < 60 minutes | Time from stablecoin receipt to fiat credit (Off-Ramp) |