exchange-rate
Query real-time exchange rates for any base currency via ExchangeRate-API. Use this skill whenever the user needs currency conversion rates, forex data, or wants to know how much one currency is worth
SKILL.mdresources/migrated/v1-skills/exchange-rate/SKILL.md
GitHubExchangeRate — Real-time Exchange Rate Query
Overview
Query real-time exchange rates for all supported currencies against a specified base currency via ExchangeRate-API.
| Property | Value |
|---|---|
| Endpoint | GET https://app-dohnbj5by5mp-api-w9Rbo8E7p2b9.gateway.appmedo.com/v6/latest/{base_currency} |
| Auth | Platform-managed gateway (X-Gateway-Authorization: Bearer <INTEGRATIONS_API_KEY>) |
| Supported Currencies | 161 (ISO 4217 three-letter codes) |
| Data Freshness | Daily updates (not tick-level) |
| Billing | Billed per call |
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
base_currency |
string |
Yes | Base currency code in ISO 4217 three-letter format, e.g. USD, EUR, CNY |
Response Example (Success)
{
"result": "success",
"documentation": "https://www.exchangerate-api.com/docs",
"terms_of_use": "https://www.exchangerate-api.com/terms",
"time_last_update_unix": 1234567890,
"time_last_update_utc": "Wed, 01 Jan 2020 00:00:00 +0000",
"time_next_update_unix": 1234567890,
"time_next_update_utc": "Thu, 02 Jan 2020 00:00:00 +0000",
"base_code": "USD",
"conversion_rates": {
"EUR": 0.85,
"GBP": 0.75,
"JPY": 110.5
}
}
Response Example (Error)
{
"result": "error",
"error-type": "invalid-key"
}
Error types: unsupported-code (unsupported currency code), malformed-request (malformed request format), invalid-key (invalid key), inactive-account (account not activated), quota-reached (quota exhausted), unknown-code (unknown currency code).
Usage at Generation Time (Direct Agent Call)
The platform manages the API key via process.env["INTEGRATIONS_API_KEY"]. Pass it as the X-Gateway-Authorization header — do not embed it in the URL path.
interface ExchangeRateResponse {
result: "success" | "error";
"error-type"?: string;
documentation?: string;
terms_of_use?: string;
time_last_update_unix?: number;
time_last_update_utc?: string;
time_next_update_unix?: number;
time_next_update_utc?: string;
base_code?: string;
conversion_rates?: Record<string, number>;
}
async function getExchangeRates(baseCurrency: string): Promise<ExchangeRateResponse> {
const apiKey = process.env["INTEGRATIONS_API_KEY"]; // platform-managed key
const url = `https://app-dohnbj5by5mp-api-w9Rbo8E7p2b9.gateway.appmedo.com/v6/latest/${baseCurrency.toUpperCase()}`;
const response = await fetch(url, {
method: "GET",
headers: {
"Accept": "application/json",
"X-Gateway-Authorization": `Bearer ${apiKey}`,
},
});
if (!response.ok) throw new Error(`HTTP error: ${response.status}`);
const json: ExchangeRateResponse = await response.json();
if (json.result === "error") {
throw new Error(`API error: ${json["error-type"]}`);
}
return json;
}
// Example: query exchange rates with USD as the base currency
const rates = await getExchangeRates("USD");
console.log(`1 USD = ${rates.conversion_rates?.EUR} EUR`);
Usage at Runtime (Application Call via Edge Function)
When calling from within an application, proxy the request through an Edge Function to keep the API key off the client.
Edge Function Code
// edge-functions/exchange-rate.ts
import { serve } from "https://deno.land/std/http/server.ts";
serve(async (req: Request): Promise<Response> => {
if (req.method !== "POST") {
return new Response("Method Not Allowed", { status: 405 });
}
// Parse client request
let baseCurrency: string;
try {
const body = await req.json();
baseCurrency = body.base_currency;
if (!baseCurrency) throw new Error("Missing base_currency");
} catch {
return new Response(JSON.stringify({ error: "Invalid request body" }), {
status: 400,
headers: { "Content-Type": "application/json" },
});
}
// Read platform-managed key — never expose to the client
const apiKey = Deno.env.get("INTEGRATIONS_API_KEY");
if (!apiKey) {
return new Response(JSON.stringify({ error: "Server configuration error" }), {
status: 500,
headers: { "Content-Type": "application/json" },
});
}
// Call upstream via platform gateway
const upstream = await fetch(
`https://app-dohnbj5by5mp-api-w9Rbo8E7p2b9.gateway.appmedo.com/v6/latest/${baseCurrency.toUpperCase()}`,
{
method: "GET",
headers: {
"Accept": "application/json",
"X-Gateway-Authorization": `Bearer ${apiKey}`,
},
}
);
// Forward quota/balance errors verbatim
if (upstream.status === 429 || upstream.status === 402) {
const errText = await upstream.text();
return new Response(errText, {
status: upstream.status,
headers: { "Content-Type": "application/json" },
});
}
if (!upstream.ok) {
return new Response(
JSON.stringify({ error: `Upstream error: ${upstream.status}` }),
{ status: 502, headers: { "Content-Type": "application/json" } }
);
}
const data = await upstream.json();
return new Response(JSON.stringify(data), {
status: 200,
headers: { "Content-Type": "application/json" },
});
});
Frontend Call to Edge Function
Recommended (when supabase client is available):
async function fetchExchangeRates(baseCurrency: string) {
const { data, error } = await supabase.functions.invoke("exchange-rate", {
body: { base_currency: baseCurrency },
});
if (error) throw error;
if (data.result === "error") throw new Error(`API error: ${data["error-type"]}`);
return data;
}
Fallback (when supabase client is unavailable):
async function fetchExchangeRates(baseCurrency: string) {
const res = await fetch(`${import.meta.env.VITE_SUPABASE_URL}/functions/v1/exchange-rate`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ base_currency: baseCurrency }),
});
if (res.status === 429) {
const err = await res.json();
throw new Error(`Quota exhausted: ${err.message ?? res.statusText}`);
}
if (res.status === 402) {
const err = await res.json();
throw new Error(`Insufficient balance: ${err.message ?? res.statusText}`);
}
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
const json = await res.json();
if (json.result === "error") throw new Error(`API error: ${json["error-type"]}`);
return json;
}
Parameter Reference
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
base_currency |
string |
Yes | ISO 4217 three-letter currency code, e.g. USD, EUR, CNY, JPY |
Response Fields
| Field | Type | Description |
|---|---|---|
result |
string |
Request result: "success" or "error" |
error-type? |
string |
Error type; only present when result === "error" |
documentation |
string |
URL to API documentation |
terms_of_use |
string |
URL to terms of use |
time_last_update_unix |
number |
Timestamp of last rate update (Unix epoch) |
time_last_update_utc |
string |
Timestamp of last rate update (UTC string) |
time_next_update_unix |
number |
Timestamp of next scheduled rate update (Unix epoch) |
time_next_update_utc |
string |
Timestamp of next scheduled rate update (UTC string) |
base_code |
string |
Base currency code, matches the request |
conversion_rates |
Record<string, number> |
Map of target currency codes (ISO 4217) to exchange rates from the base currency |
Notes
- Key security: The API key is injected into the Edge Function via
INTEGRATIONS_API_KEY. Never expose it in frontend code or version control. - Error handling: Always check the
resultfield in the response body. When"error", handle accordingly based onerror-type, especiallyquota-reached. - Billing: This endpoint is billed per call. Avoid redundant calls in loops or polling — cache exchange rate data at the application layer (rates update once per day; use
time_next_update_utcto know when to refresh). - Currency codes: Only ISO 4217 standard three-letter codes are supported. Unsupported codes return
unsupported-codeorunknown-codeerrors. - Data freshness: Rates are updated daily, not tick-level. Not suitable for high-frequency trading use cases.
- Single base currency per request: Each request specifies one base currency and returns rates against all 161 supported currencies.