Savvy Rilla FX API

Public API Documentation (v1)

Read-only FX rates API for SSP and key global currencies. All endpoints are versioned under /api/v1.

Base URL & Versioning

Production base URL

https://fx.savvyrilla.tech/api/v1

Version

v1 (path-based)

All endpoints start with /api/v1. Breaking changes will go to /api/v2.

Response headers

Every response includes X-FX-API-Version: v1.

Authentication

Read-only endpoints documented on this page are currently public and do not require authentication.

Write/admin endpoints (used by internal dashboards) are protected separately and are not part of the public v1 surface yet.

Endpoint Overview

MethodPathDescription
GET/currenciesList supported currencies.
GET/rates/latestLatest mid rate for all quote currencies vs base (SSP default).
GET/rates/<quote>/latestLatest snapshot for a single pair (e.g. SSP/USD).
GET/rates/historyTime series history for a given pair.
GET/rates/recentRecent FX records (latest rows).
GET/summary/marketCompact summary for “Market Snapshot” (rate + change + range).
GET/export/ratesExport historical rates as JSON or CSV.

GET /currencies

Returns the list of supported currencies (code, name, symbol, decimals).

Request

GET https://fx.savvyrilla.tech/api/v1/currencies

Query params

  • search (optional) — filter by code or name.
  • active (optional) — reserved for future use (e.g. true / false).

Example curl

curl "https://fx.savvyrilla.tech/api/v1/currencies"

Example response

{
  "data": [
    { "code": "SSP", "name": "South Sudanese Pound", "symbol": "£", "decimals": 2 },
    { "code": "USD", "name": "US Dollar", "symbol": "$", "decimals": 2 }
  ],
  "meta": {
    "count": 2,
    "activeOnly": true
  }
}

GET /rates/latest

Returns the latest mid rate for all quote currencies against a base (default SSP). Falls back to fx_daily_rates_default if there are no live rates.

Request

GET https://fx.savvyrilla.tech/api/v1/rates/latest?base=SSP

Query params

  • base (optional) — base currency code, defaults to SSP.

Example curl

curl "https://fx.savvyrilla.tech/api/v1/rates/latest?base=SSP"

Example response

{
  "base": "SSP",
  "as_of_date": "2025-11-20",
  "source": "fx_daily_rates",
  "rates": {
    "USD": 4571.0054,
    "EUR": 5020.11,
    "KES": 29.12
  }
}

GET /rates/<quote>/latest

Returns a snapshot for a single FX pair, e.g. SSP/USD, including latest mid rate and % change vs previous fixing.

Request

GET https://fx.savvyrilla.tech/api/v1/rates/USD/latest?base=SSP

Query params

  • base (optional) — base currency, defaults to SSP.

Example curl

curl "https://fx.savvyrilla.tech/api/v1/rates/USD/latest?base=SSP"

Example response

{
  "pair": "SSP/USD",
  "base": "SSP",
  "quote": "USD",
  "as_of_date": "2025-11-20",
  "mid_rate": 4571.0054,
  "change_pct_vs_previous": 0.2,
  "is_official": true,
  "is_manual_override": false,
  "source_id": 1
}

GET /rates/history

Returns time series data for a given pair. You can request a rolling window using days or pass explicit from/to dates.

Request

GET https://fx.savvyrilla.tech/api/v1/rates/history?base=SSP&quote=USD&days=30

Query params

  • base (optional) — defaults to SSP.
  • quote (optional) — defaults to USD.
  • days (optional) — mutually exclusive with from/to. Positive integer (e.g. 30, 90, 365).
  • from, to (optional) — ISO datesYYYY-MM-DD.

Example curl

curl "https://fx.savvyrilla.tech/api/v1/rates/history?base=SSP&quote=USD&days=30"

Example response

{
  "pair": "SSP/USD",
  "base": "SSP",
  "quote": "USD",
  "points": [
    { "date": "2025-10-22", "mid": 4560.22 },
    { "date": "2025-10-23", "mid": 4563.80 }
  ],
  "meta": {
    "from": "2025-10-22",
    "to": "2025-11-20",
    "count": 30
  }
}

GET /rates/recent

Returns a list of the most recent FX rows, optionally filtered by quote currency.

Request

GET https://fx.savvyrilla.tech/api/v1/rates/recent?base=SSP&quote=USD&limit=10

Query params

  • base (optional) — defaults to SSP.
  • quote (optional) — filter by quote currency code.
  • limit (optional) — max rows (1–100, default 20).

Example curl

curl "https://fx.savvyrilla.tech/api/v1/rates/recent?base=SSP&quote=USD&limit=10"

GET /summary/market

Returns a compact snapshot for a single pair, suitable for “Market Snapshot” UI cards.

Request

GET https://fx.savvyrilla.tech/api/v1/summary/market?base=SSP&quote=USD

Query params

  • base (optional) — defaults to SSP.
  • quote (optional) — defaults to USD.

Example response

{
  "base": "SSP",
  "quote": "USD",
  "as_of_date": "2025-11-20",
  "mid_rate": 4571.0054,
  "change_pct_vs_previous": 0.2,
  "range": {
    "window_days": 7,
    "high": 4583.58,
    "low": 4562.03
  },
  "trend": {
    "window_days": 3,
    "label": "Range-Bound"
  },
  "volatility": {
    "window_days": 30,
    "avg_daily_move_pct": null
  }
}

GET /export/rates

Exports historical FX data for a time period as JSON or CSV. CSV is ideal for spreadsheets and external analysis.

Request

GET https://fx.savvyrilla.tech/api/v1/export/rates?base=SSP&quote=USD&from=2025-01-01&to=2025-11-20&format=csv

Query params

  • base (optional) — defaults to SSP.
  • quote (optional) — filter by quote currency.
  • from, to (required) — ISO dates YYYY-MM-DD.
  • format (optional) — csv (default) or json.

Example curl

curl "https://fx.savvyrilla.tech/api/v1/export/rates?base=SSP&quote=USD&from=2025-01-01&to=2025-11-20&format=csv" -o fx_rates_usd_ssp.csv

Error format

Errors are returned with a consistent JSON structure:

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "days must be a positive integer."
  }
}

Common codes include INVALID_PARAMETER, MISSING_PARAMETER, NO_DATA, and DB_ERROR.