How to Get Real-Time South Sudanese Pound (SSP) - N/A Prices with Metals-API using JavaScript (Fetch API)
If you price products, analyze exposure, or build dashboards for markets where the South Sudanese Pound (SSP) is your operating currency, you likely need real-time SSP-denominated metal quotes and currency conversions that are reliable, timestamped, and easy to integrate. This guide shows how to get real-time South Sudanese Pound (SSP) prices using Metals-API with JavaScript (Fetch API), then turn those results into actionable pricing and analytics. We will focus on practical steps—how to call the API, interpret the JSON, and convert the returned units—so you can plug SSP prices directly into trading tools, e‑commerce pricing, ERP flows, or research notebooks. Along the way we’ll cover details a beginner might miss: troy ounces vs grams, base currency handling, timestamps and timezones, caching strategies, and weekend/holiday behavior. For complete API capabilities, visit the Metals-API Website and the Metals-API Documentation.
What “SSP Prices” Means in Practice
When teams say “SSP prices,” they often mean at least one of the following:
- Currency conversion: How many SSP per USD (or vice versa) in real time, for reconciliation, quoting, or checkout.
- SSP-denominated metal pricing: How much one troy ounce costs in SSP (e.g., gold in SSP, silver in SSP) for quotes, hedging, or mark-to-market.
- SSP across time: Intraday, latest, or daily historical time series to track SSP performance or metal costs in SSP.
Metals-API returns exchange rates relative to a base currency (default USD). You can request a base of SSP to receive rates quoted “per SSP,” or request the default and convert to SSP afterward. We will focus on two to three high-impact endpoints for real-time SSP workflows:
- Latest rates: the current exchange rates, including SSP as a currency.
- Time-series: daily historical rates between dates, used for backtesting and analytics.
- Convert: compute amounts between SSP and other symbols (currencies or metals).
For a complete symbol inventory, confirm SSP support and any applicable metals at the Metals-API Supported Symbols page before coding your integration.
Endpoint Overview for SSP Workflows
We will use a minimal set of endpoints aligned to SSP scenarios:
- Latest Rates Endpoint: Retrieves current rates with a chosen base. Useful for real-time SSP pricing and dashboards.
- Time-Series Endpoint: Retrieves daily data across a date range. Useful for charts, P&L, and volatility analysis.
- Convert Endpoint: Converts an amount from one symbol to another (e.g., SSP to USD, or SSP to a metal). Useful for checkout calculations, quotes, and conversions in-line.
Note: By default, Metals-API responses are quoted relative to USD and expressed per troy ounce when the rate is a precious/industrial metal. For currencies, the rate indicates a standard exchange rate relationship against the base currency. Always check the base and the unit fields, as applicable.
Before You Start: API Key, Symbols, and Units
- API Key: Sign up and get your key at the Metals-API Website. You will pass it via the
access_keyquery parameter. If you don’t have one, get a free API key now. - Symbols: Confirm that SSP is available in your current plan and verify the exact symbol code at the Metals-API Supported Symbols page. Symbols are case-sensitive.
- Units: Metals are typically returned “per troy ounce.” The
unitfield will state “per troy ounce” or “troy ounces” as applicable. If you price or inventory in grams, you must convert between ounces and grams (1 troy ounce = 31.1034768 grams). - Timezone and Timestamps: Timestamps are epoch seconds, and dates are returned in YYYY-MM-DD format. Treat times as UTC unless otherwise specified.
Real-Time SSP: Latest Rates Endpoint
The Latest Rates endpoint returns current rates relative to a base currency. If you set base=SSP, rates are quoted “per 1 SSP.” If you keep the default base (USD), rates are quoted “per 1 USD,” and you can use either a second call or the Convert endpoint to compute SSP-denominated prices.
Use Case: Display SSP Exchange Rate on a Dashboard
Suppose you need to show the current SSP exchange rate as part of a cross-currency summary panel or pre-trade validation. You can request the Latest endpoint with base=SSP to get other supported symbols relative to SSP.
cURL Example: Latest with SSP as Base
The following cURL demonstrates how to request latest rates with SSP as your base currency. Replace YOUR_ACCESS_KEY with your real key.
curl -s "https://metals-api.com/api/latest?access_key=YOUR_ACCESS_KEY&base=SSP"
Example JSON Response (Latest with base=SSP)
Below is a representative JSON response schema showing how fields are organized. The rates object will include supported symbols quoted per 1 SSP. Always validate fields programmatically before use.
{
"success": true,
"timestamp": 1790295883,
"base": "SSP",
"date": "2026-09-25",
"rates": {
"USD": 0.00765,
"EUR": 0.00701
}
}
Field notes you will actually use:
- success: Boolean. Check before reading other fields.
- timestamp: Epoch seconds of the last update. Use for staleness checks and caching TTL.
- base: The base currency for all returned rates. Here it’s SSP.
- date: The calendar date associated with the data snapshot.
- rates: Object of symbol-to-rate mappings. In this example, USD and EUR reflect “per 1 SSP.”
Interpreting SSP as Base
- If
rates.USDis the value of USD per 1 SSP, then SSP per 1 USD is1 / rates.USD. Choose a consistent convention in your code and stick to it everywhere (docs, UI, tests). - If you need metal prices in SSP per troy ounce, you can either:
- Request metals with base=SSP (if your plan and endpoint support returning metals with SSP base).
- Or request metals with base=USD and combine with a USD↔SSP conversion using the Convert endpoint.
JavaScript (Fetch API) Example: Reading SSP Rates
The following JavaScript uses the Fetch API to retrieve SSP-based latest rates and then compute SSP per 1 USD. This snippet is framework-agnostic and can run in Node.js (with fetch enabled) or modern browsers.
async function getSspLatestRates() {
const url = "https://metals-api.com/api/latest?access_key=YOUR_ACCESS_KEY&base=SSP";
const res = await fetch(url, { method: "GET" });
if (!res.ok) {
throw new Error("Network error: " + res.status);
}
const json = await res.json();
if (!json.success) {
const code = json.error && json.error.code ? json.error.code : "UNKNOWN_ERROR";
throw new Error("API error: " + code);
}
// Example: derive SSP per 1 USD from USD per 1 SSP
const usdPerOneSsp = json.rates && json.rates.USD;
if (typeof usdPerOneSsp !== "number" || usdPerOneSsp <= 0) {
throw new Error("Missing or invalid USD rate in response");
}
const sspPerOneUsd = 1 / usdPerOneSsp;
return {
base: json.base,
date: json.date,
timestamp: json.timestamp,
usdPerOneSsp,
sspPerOneUsd
};
}
getSspLatestRates()
.then((data) => {
console.log("Latest SSP data:", data);
})
.catch((err) => {
console.error("Failed to fetch SSP latest rates:", err);
});
Using Latest SSP Rates in Applications
- Trading tools: Display SSP conversions next to other funding currencies; run sanity checks against internal pricing sources.
- E-commerce: Show localized prices to shoppers in SSP and refresh them per cache policy (e.g., every 10 minutes).
- ERP: Feed SSP into purchase order normalization workflows for cross-border invoices.
For more endpoint options and parameters, browse the Metals-API Documentation.
Historical and Backtesting: Time-Series Endpoint (SSP Focus)
For research, risk, and BI dashboards, you’ll likely need historical SSP-based data. The Time-Series endpoint returns daily rates across a start and end date range. Use it to build SSP trend charts or compute market-on-close valuations of SSP relative to other symbols.
cURL Example: SSP Time-Series Window
This example requests a date range with SSP as the base. Replace YOUR_ACCESS_KEY and adjust the dates as needed.
curl -s "https://metals-api.com/api/timeseries?access_key=YOUR_ACCESS_KEY&base=SSP&start_date=2026-09-18&end_date=2026-09-25"
Example JSON Response (Time-Series with base=SSP)
{
"success": true,
"timeseries": true,
"start_date": "2026-09-18",
"end_date": "2026-09-25",
"base": "SSP",
"rates": {
"2026-09-18": {
"USD": 0.00768
},
"2026-09-19": {
"USD": 0.00767
},
"2026-09-20": {
"USD": 0.00766
},
"2026-09-23": {
"USD": 0.00765
},
"2026-09-25": {
"USD": 0.00765
}
}
}
Important details:
- timeseries: Boolean indicating the type of response.
- rates: Nested object keyed by ISO dates. Each date maps to a set of symbol rates.
- Weekend/holiday behavior: Expect fewer entries when markets are closed or if data is not updated for non-business days. The example shows gaps (no 2026-09-21 or 2026-09-22) to illustrate real-world non-linear calendars; always write code that tolerates missing dates.
Practical Uses of SSP Time-Series
- Backtesting and P&L: Convert historical USD amounts to SSP on specific days for accounting snapshots.
- Volatility and risk: Compute standard deviations or drawdowns of SSP rates over time windows.
- Charts: Render SSP-per-USD or USD-per-SSP charts using your plotting library of choice.
JavaScript: Fetch Time-Series and Normalize for Charting
This snippet queries time-series, normalizes SSP per USD for missing dates, and emits rows for visualization tooling.
async function fetchSspTimeSeries(startDate, endDate) {
const params = new URLSearchParams({
access_key: "YOUR_ACCESS_KEY",
base: "SSP",
start_date: startDate,
end_date: endDate
});
const url = "https://metals-api.com/api/timeseries?" + params.toString();
const res = await fetch(url);
if (!res.ok) throw new Error("HTTP " + res.status);
const json = await res.json();
if (!json.success || !json.timeseries) {
throw new Error("API returned non-timeseries payload");
}
// Transform dates into ascending order and calculate SSP per 1 USD
const series = [];
const dates = Object.keys(json.rates).sort();
for (const d of dates) {
const day = json.rates[d];
const usdPerSsp = day && typeof day.USD === "number" ? day.USD : null;
if (usdPerSsp && usdPerSsp > 0) {
const sspPerUsd = 1 / usdPerSsp;
series.push({ date: d, sspPerUsd, usdPerSsp });
}
}
return { base: json.base, start: json.start_date, end: json.end_date, series };
}
fetchSspTimeSeries("2026-09-18", "2026-09-25")
.then((out) => console.log("Normalized SSP time-series:", out))
.catch((err) => console.error("Failed to fetch SSP timeseries:", err));
On-Demand Calculation: Convert Endpoint with SSP
The Convert endpoint is your Swiss Army knife for pricing at checkout or real-time quoting. Pass a from symbol, a to symbol, and an amount, and the API returns a converted result with a timestamp and the effective rate used. This is especially convenient when you need SSP pricing without manually chaining multiple steps.
Common Convert Patterns with SSP
- SSP → USD: Normalize sales or P&L from SSP into USD for consolidation.
- USD → SSP: Localize foreign currency costs into SSP for purchase orders or POS.
- SSP ↔ Other supported symbols: Combine SSP with any supported symbol directly.
cURL Example: Convert 10,000 SSP to USD
curl -s "https://metals-api.com/api/convert?access_key=YOUR_ACCESS_KEY&from=SSP&to=USD&amount=10000"
Example JSON Response (Convert SSP→USD)
{
"success": true,
"query": {
"from": "SSP",
"to": "USD",
"amount": 10000
},
"info": {
"timestamp": 1790295883,
"rate": 0.00765
},
"result": 76.5
}
How to use it:
- query.from / query.to: Confirm you used the intended direction.
- amount: Ensure it matches your order size or notional.
- info.rate: The effective rate used for this conversion.
- result: The computed target amount. In this example, 10,000 SSP becomes 76.5 USD.
- timestamp: Store with your transaction to reconcile later.
JavaScript: Convert SSP to USD with Fetch API
async function convertSspToUsd(amount) {
const params = new URLSearchParams({
access_key: "YOUR_ACCESS_KEY",
from: "SSP",
to: "USD",
amount: String(amount)
});
const res = await fetch("https://metals-api.com/api/convert?" + params.toString());
if (!res.ok) throw new Error("HTTP " + res.status);
const json = await res.json();
if (!json.success) {
const code = json.error && json.error.code ? json.error.code : "UNKNOWN_ERROR";
throw new Error("API error: " + code);
}
return {
from: json.query.from,
to: json.query.to,
amount: json.query.amount,
rate: json.info.rate,
timestamp: json.info.timestamp,
result: json.result
};
}
convertSspToUsd(10000)
.then((out) => console.log("Converted SSP to USD:", out))
.catch((err) => console.error("Conversion failed:", err));
Bringing It Together: SSP-Denominated Metals Pricing
Many applications need to express a metal price—quoted per troy ounce—in SSP. Here’s a robust pattern to achieve that:
- Fetch metal rates with base=USD (default). The rate will be “ounces per 1 USD.”
- Invert the metal rate to get USD per ounce:
usdPerOunce = 1 / rate. - Convert USD to SSP via Convert endpoint (USD → SSP). Then compute
sspPerOunce = usdPerOunce * sspPerUsd.
Why this pattern is robust: It decouples metal pricing from currency conversion and reduces ambiguity about units. You always read the unit field to confirm “per troy ounce.” Then you convert USD to SSP once (and cache it).
Tip: If your subscription plan allows base=SSP directly on metals in Latest or Time-Series, you can simplify your pipeline to one step and skip the conversion. Confirm via the Metals-API Documentation and your plan’s specifics.
Example: Combined SSP Metal Pricing Flow (Two Calls)
We’ll outline a typical two-call flow with pseudocode approach using the existing patterns shown above:
- Call 1: Latest metals with base=USD (read “per troy ounce”).
- Call 2: Convert 1 USD → SSP to find SSP per 1 USD.
- Compute: SSP per ounce = (USD per ounce) × (SSP per 1 USD).
In implementation, you would parse the first response to extract a metal’s rate field (ounces per USD), invert it, then multiply by sspPerUsd from the Convert step.
Interpreting Units: Troy Ounces and Grams
Metals-API expresses metals in troy ounces by default. If you store inventory or quote in grams or kilograms, convert explicitly:
- 1 troy ounce = 31.1034768 grams
- grams per ounce: multiply ounces by 31.1034768
- ounces per gram: divide grams by 31.1034768
When you request a metal price, always check the unit field in the response, which typically states “per troy ounce” for rates or “troy ounces” for conversion results. Do not assume SI units.
Timestamps, Timezones, and Market Calendars
Metals-API responses include a UNIX timestamp and a date string:
- timestamp: epoch seconds; useful for TTLs and staleness metrics.
- date: ISO date (YYYY-MM-DD) aligned to the API’s data clock in UTC.
Market closures and weekends impact data availability. Your code should:
- Tolerate missing dates in Time-Series.
- Recognize that “latest” could reflect the last available tick, not an intra-minute update during closures.
- Cache intelligently (see below) to avoid unnecessary calls when markets are shut.
Caching, Throttling, and Cost Control
To minimize latency and request volume:
- Cache conversion multipliers like SSP per 1 USD for 5–15 minutes, depending on your plan’s update granularity.
- Separate metal rate caching and currency rate caching, so you can refresh each at optimal cadences.
- In microservices, centralize an internal “rates” service to fanout cached responses to downstream apps.
- Propagate timestamps to UIs (e.g., “last updated 14:32 UTC”) for transparency.
Use exponential backoff on 429 (rate limit) responses, and degrade gracefully by falling back to your last valid cached snapshot. For all error handling patterns, consult the Metals-API Documentation.
Data Validation and Sanitization
Production code should defensively validate every response:
- Check
success === truebefore using fields. - Verify presence and type of
timestamp,date, andbase. - Ensure desired symbols exist in
ratesand are positive numbers. - Log unexpected shapes or missing fields and add alerts for persistent anomalies.
Security Considerations
- Never embed your raw API key in a public client. Proxy requests through your backend when building browser apps, or inject the key server-side and store secrets securely (e.g., environment variables, vaults).
- Implement request signing or origin restrictions if you expose a proxy endpoint.
- Rate-limit external endpoints to prevent abuse; consider per-IP throttles.
- Audit logs for unusual traffic bursts that could indicate key leakage.
Error Handling and Recovery Strategies
Plan for transient failures and malformed inputs:
- HTTP errors (e.g., 500, 503): retry with backoff and jitter; failover to cached data.
- 429 rate limit: honor retry-after headers if provided, slow down, or switch to cached data.
- Invalid symbol: confirm SSP’s presence via Metals-API Supported Symbols, correct casing, and re-deploy.
- Empty or partial results: skip missing dates, interpolate only if your modeling allows, or flag to users.
Example: Error JSON Scenarios
Invalid Access Key
{
"success": false,
"error": {
"code": "invalid_access_key",
"type": "You have not supplied a valid API Access Key."
}
}
Unsupported Symbol or Typo
{
"success": false,
"error": {
"code": "invalid_symbols",
"type": "One or more symbols are not supported."
}
}
Exceeded Rate Limit
{
"success": false,
"error": {
"code": "rate_limit_reached",
"type": "You have reached your API request rate limit."
}
}
Handle each error with user-friendly messaging and fallbacks. Log error.code and error.type for operational insights and alerts.
Performance Tips for SSP Pricing at Scale
- Batching: Prefer time-series requests for chart loads instead of many single-day calls.
- Denormalization: Store SSP per 1 USD alongside metal snapshots to avoid frequent Convert calls during renders.
- Client hints: Send minimal updates to UIs when the underlying rate has not changed meaningfully (e.g., below a configured threshold).
- CDN and Edge: Cache public dashboards for a few minutes at the edge; private dashboards can still pull from your internal cache layer.
Testing and Observability
- Fixture-based tests: Mock Latest, Time-Series, and Convert responses to validate pricing math (inversion, unit conversion).
- Contract tests: Check that required fields appear for SSP requests, and reject if shapes change.
- Metrics: Track cache hit rate, median latency, and per-endpoint error rates.
- Tracing: Tag requests by endpoint and symbol (e.g., SSP) to spot hot paths and tune TTLs.
Designing Robust SSP Pipelines
A typical architecture for SSP-denominated pricing and analytics might include:
- Ingest Layer: A service that calls Latest and Time-Series at fixed intervals, with resilient backoff and snapshot storage.
- Cache Layer: A TTL-based cache (e.g., Redis) keyed by endpoint, symbol set, and base (SSP vs USD).
- Pricing API: Internal microservice that combines metals and currency conversions into SSP; includes validation and monitoring.
- UI/BI Clients: Dashboards and tools that read normalized SSP prices with clear “last updated” stamps.
Neodymium (ND) and the Digital Transformation of Metals Data
While this article focuses on SSP pricing mechanics, it’s worth reflecting on how modern APIs are reshaping access to less-liquid metals such as neodymium (often cited in advanced magnet and green-tech supply chains). Digital transformation in metal markets increasingly depends on:
- Technological innovation: Low-latency APIs and standardized JSON enable rapid prototyping of trading and procurement tools, including frontier materials.
- Data analytics: Time-series endpoints unlock quantitative insights about procurement cycles, seasonality, and hedging efficacy.
- Smart integration: Edge caching, serverless triggers, and alerting pipelines (e.g., when currency moves breach thresholds) power timely decisions.
- Future trends: As industrial metals pricing becomes more data-driven, expect tighter integrations between procurement ERPs, trade finance platforms, and real-time market data—especially in emerging markets where local currencies like SSP matter for on-the-ground execution.
To explore the full set of available symbols and verify whether specific industrial metals (including neodymium variants if supported) are accessible in your plan, review the Metals-API Supported Symbols.
Additional Example JSONs for SSP Workflows
Latest Endpoint (base=SSP) Including Multiple Currencies
{
"success": true,
"timestamp": 1790295883,
"base": "SSP",
"date": "2026-09-25",
"rates": {
"USD": 0.00765,
"GBP": 0.00602,
"EUR": 0.00701
}
}
Time-Series Endpoint (base=SSP) with Weekend Gaps
{
"success": true,
"timeseries": true,
"start_date": "2026-09-18",
"end_date": "2026-09-25",
"base": "SSP",
"rates": {
"2026-09-18": { "USD": 0.00768 },
"2026-09-19": { "USD": 0.00767 },
"2026-09-20": { "USD": 0.00766 },
"2026-09-23": { "USD": 0.00765 },
"2026-09-25": { "USD": 0.00765 }
}
}
Convert Endpoint (USD→SSP) for Checkout Localization
{
"success": true,
"query": {
"from": "USD",
"to": "SSP",
"amount": 99.99
},
"info": {
"timestamp": 1790295883,
"rate": 130.72
},
"result": 1306.0
}
Interpretation:
- rate: SSP per 1 USD
- result: SSP cost for a USD-denominated item priced at 99.99
Error Example: Missing Base Parameter
{
"success": false,
"error": {
"code": "missing_base",
"type": "You must specify a valid base currency."
}
}
Partial Success Pattern (Handle Gracefully)
{
"success": true,
"timestamp": 1790295883,
"base": "SSP",
"date": "2026-09-25",
"rates": {
"USD": 0.00765
},
"warnings": [
{ "code": "symbol_ignored", "symbol": "FOO", "reason": "Unsupported symbol" }
]
}
In this scenario, your app should process the valid USD rate and log or display a non-blocking notice that the unsupported “FOO” symbol was ignored.
Practical Gotchas and How to Avoid Them
- Assuming grams: Always check
unit. Metals are per troy ounce unless stated otherwise. - Forgetting base: Read
basein every response; “per 1 SSP” is different from “per 1 USD.” - Ignoring timestamp: Stale data can sneak into UIs; include “last updated” and TTL guards.
- Inverting at the wrong step: Clearly document whether you store “SSP per USD” or “USD per SSP.” Mixing these will produce subtle pricing errors.
- Weekend gaps: Time-series charts can appear jagged if you assume daily continuity; manually handle non-business days.
Advanced Techniques
- Threshold Alerts: Poll Latest in a serverless function and send alerts when SSP per USD crosses a threshold (Slack, email, webhook).
- Portfolio Simulation: Use Time-Series to model SSP-denominated portfolio value across historical windows.
- Multi-Region Pricing: Keep a small pool of currency conversions (e.g., SSP, KES, UGX) in cache, rotate updates based on traffic demand.
- API Gateway Integration: Route Metals-API calls through your API gateway; add caching, auth enforcement, and observability uniformly.
SSP Data Governance and Auditing
- Versioning: Tag snapshots with endpoint, base, symbols, and timestamp to reproduce historical statements.
- Data Lineage: Log exact query URLs. If auditors ask how a price was computed, you can reconstruct the call and the math.
- Retention: Store minimal yet sufficient data (timestamp, base, rate, symbol) to rebuild valuations when needed.
Frequently Asked Questions (FAQ)
1) How do I get an API key?
Visit the Metals-API Website and sign up. Your key will be passed via the access_key parameter.
2) Is SSP supported as a currency symbol?
Check the current list at Metals-API Supported Symbols. Availability can vary by plan and update cadence.
3) What’s the difference between “base=SSP” and default base?
With base=SSP, rates are quoted per 1 SSP. With the default base (USD), rates are per 1 USD. Use whichever reduces confusion in your downstream math. Be consistent across your services.
4) How often do rates update?
Update intervals depend on your subscription plan (e.g., every 60 minutes or 10 minutes). Always read the timestamp and employ a cache TTL tuned to your plan. Consult the Metals-API Documentation for details.
5) How do I get SSP-denominated metal prices per troy ounce?
Either set base=SSP when querying metals (if supported for your plan) or fetch metals with base=USD, invert to get USD/oz, then Convert USD to SSP and multiply. Always verify unit is “per troy ounce.”
6) How should I handle weekends and holidays?
Expect no updates during closures. Use last-known-good from cache for UIs, clearly label the “last updated” time, and handle gaps in Time-Series data when charting.
7) Can I use the API directly from the browser?
Technically yes via the Fetch API, but for security it’s safer to proxy through your backend to avoid exposing your API key. Consider setting up a thin server that injects the key securely and applies rate limiting.
8) How do I convert grams to troy ounces?
1 troy ounce = 31.1034768 grams. For SSP per gram, compute SSP per ounce and divide by 31.1034768.
9) What if my SSP calls fail intermittently?
Implement retries with backoff for 5xx errors, respect 429 rate-limits with cooldowns, and fall back to your cached snapshot. Log error codes and alert on spikes.
10) Where can I learn more?
Explore the Metals-API Documentation for endpoint details and the Supported Symbols to verify SSP and related symbols. For broad context and to register, visit the Metals-API Website.
Conclusion
Real-time SSP pricing is straightforward with Metals-API: choose a consistent base (SSP vs USD), leverage Latest for live snapshots, Time-Series for historical analytics, and Convert for on-demand quoting. Validate timestamps, standardize unit conversions (troy ounces vs grams), and deploy resilient caching and error handling. Whether you are localizing e‑commerce prices into SSP, normalizing P&L across regions, or powering dashboards for procurement and trading, this approach ensures clarity and auditability end-to-end. To implement today, get your key at the Metals-API Website, confirm symbols at Metals-API Supported Symbols, and dive into the Metals-API Documentation for advanced options.