Savvy Rilla FX APIVersion v1Public read-only API

API documentation

Integrate South Sudanese Pound market data, historical rates, structured commentary, and operational metadata into applications, dashboards, reports, and internal tools.

FX dashboard Quick start API explorer

Base URL

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

Status

Operational

Rate limit

120 req/min

Interactive API Explorer

Execute live requests from the OpenAPI specification, configure parameters, and pass an API key from the browser.

Open explorer

Reference Manual

Browse the complete OpenAPI reference with schemas, endpoint groups, authentication, and examples.

Open manual

OpenAPI Source

Download the machine-readable OpenAPI 3.1 document for tooling, SDKs, Postman, and CI validation.

View JSON

Versioned

All public routes live under /api/v1.

Request controls

Request IDs, security headers, and rate limits are enabled.

Consistent

Success and error responses follow one JSON contract.

Integration examples

Copy-ready requests cover common integration stacks.

Quick Start

Make your first request

Public v1 endpoints are read-only and do not require an API key today. Copy the request exactly as shown; add authentication only when you have been issued a real key.

1
Choose an endpoint
Start with latest rates for a complete SSP market snapshot.
2
Send the request
Use the public URL without a placeholder API key.
3
Handle the envelope
Check response.ok, then retain requestId when reporting errors.

Response contract

Every endpoint returns request metadata alongside the business payload, making debugging, logging, and support easier.

success: Boolean request state

requestId: Correlation ID

durationMs: Server processing time

version: API version

Rate convention

Every mid-rate is expressed as base-currency units per one quote-currency unit. With base SSP and quote USD, a mid-rate of 4,824.005 means 1 USD equals 4,824.005 SSP.

Use display_pair for conventional market notation. The legacypair field remains unchanged in v1 for backwards compatibility.

rate_convention: base_units_per_quote_unit

First request

curl --fail-with-body "https://fx.savvyrilla.tech/api/v1/rates/latest?base=SSP" \
  -H "Accept: application/json"

API Keys

Secure access for developer integrations

Public endpoints remain backwards compatible, but Savvy Rilla FX now supports API-key authentication for managed developer access, quotas, analytics, and future commercial plans.

Header authentication

Send your key using X-API-Key. Authorization: Bearer is also supported.

X-API-Key: srfx_live_your_api_key

Key environments

Keys are prefixed by environment so test and production traffic are easy to distinguish.

srfx_test_...

srfx_live_...

srfx_admin_...

Managed access

Keys are issued for managed integrations. Savvy Rilla administrators create, revoke, and monitor them from the internal console.

Admin key console

API Explorer

Build a request

Select an endpoint and language to generate a copy-ready request, or open the interactive explorer to execute it against the live API.

EndpointLanguage

Latest FX Rates

Returns the latest available SSP-per-unit rates for supported quote currencies.

Execute in API explorer

curl request

curl --fail-with-body "https://fx.savvyrilla.tech/api/v1/rates/latest?base=SSP" \
  -H "Accept: application/json"

Endpoint Reference

Public v1 endpoints

These endpoints are designed for dashboards, widgets, internal tools, research workflows, and developer integrations.

GET/rates/latest

Latest FX Rates

Returns the latest available SSP-per-unit rates for supported quote currencies.

Public cache, short TTL120 requests per minute per IP or API key

Parameters and copy-ready examples

Parameter	Required	Example	Description
base	No	SSP	Base currency. Defaults to SSP.

curl request

curl --fail-with-body "https://fx.savvyrilla.tech/api/v1/rates/latest?base=SSP" \
  -H "Accept: application/json"

Example response

{
  "success": true,
  "requestId": "req_...",
  "timestamp": "2026-06-29T12:00:00.000Z",
  "version": "v1",
  "durationMs": 12,
  "rate_convention": "base_units_per_quote_unit",
  "unit": "SSP per 1 quote currency unit",
  "base": "SSP",
  "as_of_date": "2026-07-14",
  "source": "fx_daily_rates",
  "rates": {
    "KES": 37.3235,
    "USD": 4824.005
  }
}

GET/rates/USD/latest

Latest Rate by Quote Currency

Returns the latest rate for one quote currency, such as USD, KES, EUR, or GBP.

Public cache, short TTL120 requests per minute per IP or API key

Parameters and copy-ready examples

Parameter	Required	Example	Description
base	No	SSP	Base currency. Defaults to SSP.

curl request

curl --fail-with-body "https://fx.savvyrilla.tech/api/v1/rates/USD/latest?base=SSP" \
  -H "Accept: application/json"

Example response

{
  "success": true,
  "requestId": "req_...",
  "timestamp": "2026-06-29T12:00:00.000Z",
  "version": "v1",
  "durationMs": 9,
  "rate_convention": "base_units_per_quote_unit",
  "display_pair": "USD/SSP",
  "unit": "SSP per 1 USD",
  "pair": "SSP/USD",
  "base": "SSP",
  "quote": "USD",
  "as_of_date": "2026-07-14",
  "mid_rate": 4824.005,
  "change_pct_vs_previous": 0.3533,
  "is_official": true,
  "is_manual_override": false,
  "source_id": 1
}

GET/rates/history

Historical Rates

Returns historical FX observations for a currency pair over a date range.

Public cache, medium TTL120 requests per minute per IP or API key

Parameters and copy-ready examples

Parameter	Required	Example	Description
base	No	SSP	Base currency. Defaults to SSP.
quote	No	USD	Quote currency. Defaults to USD.
from	No	2026-01-01	Start date in YYYY-MM-DD format.
to	No	2026-06-29	End date in YYYY-MM-DD format.

curl request

curl --fail-with-body "https://fx.savvyrilla.tech/api/v1/rates/history?base=SSP&quote=USD&from=2026-01-01&to=2026-06-29" \
  -H "Accept: application/json"

Example response

{
  "success": true,
  "requestId": "req_...",
  "timestamp": "2026-06-29T12:00:00.000Z",
  "version": "v1",
  "durationMs": 18,
  "rate_convention": "base_units_per_quote_unit",
  "display_pair": "USD/SSP",
  "unit": "SSP per 1 USD",
  "pair": "SSP/USD",
  "base": "SSP",
  "quote": "USD",
  "points": [
    { "date": "2026-07-14", "mid": 4824.005 }
  ],
  "meta": {
    "from": "2026-01-01",
    "to": "2026-07-14",
    "count": 1
  }
}

GET/rates/recent

Recent Rates

Returns recent observations, or a complete snapshot from the newest available date.

Public cache, short TTL120 requests per minute per IP or API key

Parameters and copy-ready examples

Parameter	Required	Example	Description
base	No	SSP	Base currency. Defaults to SSP.
quote	No	USD	Optional quote-currency filter.
limit	No	20	Number of recent records to return. Defaults to 20.
latest_only	No	true	Set to true to return every rate from the newest available date.

curl request

curl --fail-with-body "https://fx.savvyrilla.tech/api/v1/rates/recent?base=SSP&quote=USD&limit=20&latest_only=true" \
  -H "Accept: application/json"

Example response

{
  "success": true,
  "requestId": "req_...",
  "timestamp": "2026-06-29T12:00:00.000Z",
  "version": "v1",
  "durationMs": 10,
  "rate_convention": "base_units_per_quote_unit",
  "display_pair": "USD/SSP",
  "unit": "SSP per 1 USD",
  "data": [
    {
      "id": 101,
      "as_of_date": "2026-07-14",
      "base_currency": "SSP",
      "quote_currency": "USD",
      "rate_mid": 4824.005,
      "is_official": true,
      "is_manual_override": false,
      "source_id": 1
    }
  ],
  "meta": {
    "limit": null,
    "base": "SSP",
    "quote": "USD",
    "latest_only": true,
    "as_of_date": "2026-07-14"
  }
}

GET/summary/market

Market Summary

Returns market movement, volatility, health score, and structured commentary for a currency pair.

Public cache, short TTL120 requests per minute per IP or API key

Parameters and copy-ready examples

Parameter	Required	Example	Description
base	No	SSP	Base currency. Defaults to SSP.
quote	No	USD	Quote currency. Defaults to USD.

curl request

curl --fail-with-body "https://fx.savvyrilla.tech/api/v1/summary/market?base=SSP&quote=USD" \
  -H "Accept: application/json"

Example response

{
  "success": true,
  "requestId": "req_...",
  "timestamp": "2026-06-29T12:00:00.000Z",
  "version": "v1",
  "durationMs": 16,
  "rate_convention": "base_units_per_quote_unit",
  "display_pair": "USD/SSP",
  "unit": "SSP per 1 USD",
  "pair": "USD/SSP",
  "base": "SSP",
  "quote": "USD",
  "as_of_date": "2026-07-14",
  "mid_rate": 4824.005,
  "change_pct_vs_previous": 0.3533,
  "trend": {
    "window_days": 7,
    "label": "Uptrend",
    "change_pct": 0.8983
  },
  "marketHealth": {
    "score": 78,
    "status": "Stable",
    "color": "emerald"
  }
}

GET/summary/insights

Structured Market Insights

Returns richer market narrative and insight blocks derived from the latest FX summary.

Public cache, short TTL120 requests per minute per IP or API key

Parameters and copy-ready examples

Parameter	Required	Example	Description
base	No	SSP	Base currency. Defaults to SSP.
quote	No	USD	Quote currency. Defaults to USD.

curl request

curl --fail-with-body "https://fx.savvyrilla.tech/api/v1/summary/insights?base=SSP&quote=USD" \
  -H "Accept: application/json"

Example response

{
  "success": true,
  "requestId": "req_...",
  "timestamp": "2026-06-29T12:00:00.000Z",
  "version": "v1",
  "durationMs": 20,
  "rate_convention": "base_units_per_quote_unit",
  "display_pair": "USD/SSP",
  "unit": "SSP per 1 USD",
  "pair": "USD/SSP",
  "base": "SSP",
  "quote": "USD",
  "as_of_date": "2026-07-14",
  "insights": [
    "USD/SSP has moved moderately vs the previous fixing (+0.35%)."
  ],
  "commentary": {
    "headline": "USD/SSP remains broadly stable",
    "confidence": "high"
  },
  "marketHealth": {
    "score": 78,
    "status": "Stable"
  }
}

GET/currencies

Supported Currencies

Returns the supported currency universe exposed by the FX API.

Public cache, long TTL120 requests per minute per IP or API key

Parameters and copy-ready examples

This endpoint does not require query parameters.

curl request

curl --fail-with-body "https://fx.savvyrilla.tech/api/v1/currencies" \
  -H "Accept: application/json"

Example response

{
  "success": true,
  "requestId": "req_...",
  "timestamp": "2026-06-29T12:00:00.000Z",
  "version": "v1",
  "durationMs": 5,
  "data": [
    {
      "code": "USD",
      "name": "US Dollar",
      "symbol": "$",
      "decimals": 2
    }
  ],
  "meta": {
    "count": 11,
    "activeOnly": true,
    "search": ""
  }
}

GET/export/rates

Export Rates

Exports rate data for research, reporting, dashboards, and external workflows.

No store120 requests per minute per IP or API key

Parameters and copy-ready examples

Parameter	Required	Example	Description
base	No	SSP	Base currency. Defaults to SSP.
quote	No	USD	Optional quote-currency filter.
from	Yes	2026-07-01	Start date in YYYY-MM-DD format.
to	Yes	2026-07-14	End date in YYYY-MM-DD format.
format	No	json	Export format: csv or json. Defaults to csv.

curl request

curl --fail-with-body "https://fx.savvyrilla.tech/api/v1/export/rates?base=SSP&quote=USD&from=2026-07-01&to=2026-07-14&format=json" \
  -H "Accept: application/json"

Example response

{
  "success": true,
  "requestId": "req_...",
  "timestamp": "2026-06-29T12:00:00.000Z",
  "version": "v1",
  "durationMs": 25,
  "rate_convention": "base_units_per_quote_unit",
  "display_pair": "USD/SSP",
  "unit": "SSP per 1 USD",
  "data": [
    {
      "as_of_date": "2026-07-14",
      "base_currency": "SSP",
      "quote_currency": "USD",
      "rate_mid": 4824.005
    }
  ],
  "meta": {
    "base": "SSP",
    "quote": "USD",
    "from": "2026-07-01",
    "to": "2026-07-14"
  }
}

Errors

Standard error responses

Errors use stable machine-readable codes and human-readable messages. The requestId should be included in support/debugging reports.

Code	HTTP	Description	What to do
BAD_REQUEST	400	The request could not be processed.	Check the query string and required parameters.
INVALID_CURRENCY	400	A currency code was missing or malformed.	Use a supported three-letter ISO currency code.
INVALID_PARAMETER	400	A query parameter was invalid.	Compare the value with the endpoint parameter table.
MISSING_PARAMETER	400	A required query parameter was not provided.	Add the named parameter and retry the request.
API_KEY_REQUIRED	401	The deployment requires an API key.	Send a valid X-API-Key or Bearer token.
INVALID_API_KEY	401	The supplied API key was invalid or unknown.	Remove placeholder keys or replace them with an active key.
API_KEY_REVOKED / API_KEY_EXPIRED	403	The supplied key can no longer be used.	Create or request a replacement key.
NO_DATA	404	No FX data exists for the requested resource.	Check the currency pair and requested date range.
RATE_LIMITED	429	The rate limit was exceeded.	Wait until X-RateLimit-Reset and use caching or backoff.
DB_ERROR	500	The API could not complete a database operation.	Retry with backoff and retain the requestId for support.

Error response

{
  "success": false,
  "requestId": "req_...",
  "timestamp": "2026-06-29T12:00:00.000Z",
  "version": "v1",
  "durationMs": 3,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Please retry after the reset window.",
    "details": {
      "limit": 120,
      "remaining": 0,
      "resetSeconds": 60
    }
  }
}

HTTP Caching

Use conditional requests to reduce bandwidth

Cacheable endpoints return ETag, Last-Modified, Age, Expires, Cache-Control, and X-Cache headers. Clients can revalidate with If-None-Match or If-Modified-Since and receive 304 Not Modified when data has not changed.

ETag

Send If-None-Match with the previous ETag to avoid downloading unchanged JSON.

Last-Modified

Send If-Modified-Since to revalidate based on the latest cached timestamp.

Stale support

Responses include stale-while-revalidate and stale-if-error directives for resilient clients and CDNs.

X-Cache

HIT means the response came from the in-memory cache; MISS means the endpoint refreshed the payload.

Age

Shows how many seconds the cached payload has lived since it was generated.

Admin operations

The /admin/cache console shows live metrics and allows targeted cache clearing.

Conditional request

# First request
curl -i "https://fx.savvyrilla.tech/api/v1/rates/latest"   -H "Accept: application/json"

# Revalidate with the returned ETag
curl -i "https://fx.savvyrilla.tech/api/v1/rates/latest"   -H "Accept: application/json"   -H 'If-None-Match: "paste-etag-here"'

# A fresh cached resource returns 200 OK with JSON
# An unchanged resource can return 304 Not Modified with no body

Recommended client behavior

Store the latest ETag returned by the endpoint.

Send that value back in If-None-Match during polling or refresh operations.

Treat 304 Not Modified as a successful response and reuse your local cached JSON.

For dashboards, respect Cache-Control instead of polling faster than the published TTL.

Endpoint group	Typical TTL	Operational note
Latest rates	30 seconds	Short-lived cache for high-traffic market snapshots.
Recent rates	60 seconds	Useful for dashboards and widgets.
History	5 minutes	Historical ranges change less frequently.
Summary and insights	60 seconds	Balances fresh commentary with reduced database work.
Currencies	24 hours	Reference data with low change frequency.

Cache Observability

Monitor cache behavior from the admin console

The cache dashboard gives operators a live view of hit ratio, entries, memory estimate, pending coalesced requests, namespaces, recent keys, and clear-cache operations.

Dashboard

/admin/cache

Metrics API

/api/admin/cache

Public verification

curl -i /api/v1/rates/latest

Deployment checks

Call a public endpoint twice and confirm X-Cache changes from MISS to HIT.
Send If-None-Match with the returned ETag and confirm 304 Not Modified.
Open /admin/cache and verify hit ratio, entries, and recent keys.
Clear rates cache after manual exchange-rate updates.

Operational limits

The current cache is in-memory and process-local.
Serverless cold starts begin with an empty cache.
Admin and API key routes must remain uncached.
The cache manager interface is ready for a future Redis-backed store.

Headers

Operational headers

The API returns headers that help clients cache responses, identify request traces, respect rate limits, and monitor cache behavior.

X-Request-ID

Unique request correlation identifier.

X-API-Version

Current API version.

X-Response-Time

Server processing duration.

X-RateLimit-Limit

Maximum requests in the active window.

X-RateLimit-Remaining

Requests remaining in the active window.

X-RateLimit-Reset

Unix timestamp for the rate-limit reset.

Cache-Control

Freshness, CDN, stale-while-revalidate, and stale-if-error policy.

ETag

Stable validator for conditional requests.

Last-Modified

Timestamp validator for If-Modified-Since.

X-Cache

HIT or MISS cache outcome.

X-Cache-TTL

Configured cache duration in seconds.

Age

Age of the cached response in seconds.

Interactive API Explorer

Reference Manual

OpenAPI Source

Versioned

Request controls

Consistent

Integration examples

Make your first request

Choose an endpoint

Send the request

Handle the envelope

Response contract

Rate convention

Secure access for developer integrations

Header authentication

Key environments

Managed access

Build a request

Public v1 endpoints

Latest FX Rates

Latest Rate by Quote Currency

Historical Rates

Recent Rates

Market Summary

Structured Market Insights

Supported Currencies

Export Rates

Standard error responses

Use conditional requests to reduce bandwidth

ETag

Last-Modified

Stale support

X-Cache

Age

Admin operations

Recommended client behavior

Monitor cache behavior from the admin console

Deployment checks

Operational limits

Operational headers