API Documentation

The RateSurge public API provides programmatic access to Sudan foreign currency exchange rates for NGOs, corporates, and financial institutions.

🔑 API Key Required. Request access by contacting api@ratesurge.info

Overview

The RateSurge API provides read-only access to current and historical exchange rates for USD, EUR, and XAF against the Sudanese Pound (SDG). Rates are available per market zone (North Sudan, West Sudan) alongside the official Central Bank of Sudan reference rate.

Authentication Required

All API requests require a valid API key passed either as a request header or query parameter.

http

# Option 1: Header (recommended)
X-API-Key: rs_your_api_key_here

# Option 2: Query parameter
GET /api/v1/rates?api_key=rs_your_api_key_here

Base URL

http

https://ratesurge.info/api/v1

Endpoints

GET/ratesAll current rates — all currencies, all zones

Parameter	Type	Description
zone	string	Filter by zone e.g. `north` or `west` optional

json — sample response

{
  "success": true,
  "source": "RateSurge - Sudan Exchange Rate Platform",
  "as_of": "2024-01-15T08:30:00+00:00",
  "data": [{
    "currency": { "code": "USD", "name_en": "US Dollar" },
    "official": { "rate": 3100.00, "change_direction": "up" },
    "market_zones": {
      "North Sudan": { "rate": 3870.00, "spread_percent": 24.84 },
      "West Sudan":  { "rate": 2500.00, "spread_percent": -19.35 }
    }
  }]
}

GET/rates/{code}Single currency, all zones

Returns current rates for a single currency (USD, EUR, or XAF) across all zones.

GET/history/{code}Historical rates, up to 90 days

Parameter	Description
days	Number of days (max 90, default 30) optional
zone	Filter to specific zone optional

GET/zonesList all active market zones

Returns all active market zones with English and Arabic names.

GET/currenciesList all supported currencies

Returns all active currencies with metadata.

Code Examples

JavaScript / Fetch

javascript

const response = await fetch('https://ratesurge.info/api/v1/rates', {
  headers: { 'X-API-Key': 'rs_your_key_here' }
});
const data = await response.json();
console.log(data.data[0].market_zones['North Sudan'].rate);

Python

python

import requests
headers = {'X-API-Key': 'rs_your_key_here'}
r = requests.get('https://ratesurge.info/api/v1/rates', headers=headers)
data = r.json()
for currency in data['data']:
    print(currency['currency']['code'], currency['market_zones'].get('North Sudan', {}).get('rate'))

PHP / cURL

php

$ch = curl_init('https://ratesurge.info/api/v1/rates');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: rs_your_key_here']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);

Error Codes

Code	Meaning
200	Success
401	Missing API key
403	Invalid or inactive API key
404	Currency not found
429	Rate limit exceeded
500	Server error — contact support

Rate Limits

Default: 100 requests/hour per API key. Higher limits available for enterprise NGOs — contact api@ratesurge.info.

Disclaimer

⚠ All rates provided via the RateSurge API are indicative only and sourced from market observations and the Central Bank of Sudan. They do not constitute binding rates for financial transactions. RateSurge accepts no liability for decisions made based on this data.