davidkk/exchange-rate

Exchange Rate API – Rates & conversion (agent-ready)

When to use

• User wants latest FX rates for a base currency, or convert an amount between two currencies.
• Trigger phrasings include: “USD to CNY”, “how much is 100 EUR in JPY”, “exchange rate”, “convert currency”, base=EUR style queries.
• Do not call for unrelated topics (weather, stocks, generic chat).
• Do not overuse: unrelated intent → do not call this API.

Hard boundaries (must check before call)

• Use this module only for FX rates/conversion; do not use it for stock, crypto order-book, or payment settlement semantics.
• For conversion, from/to/amount are all required; if one is missing, ask once instead of guessing.

Pre-check (before tool call)

• Confirm intent is FX rate lookup or currency conversion.
• Normalize and validate currency codes and numeric amount before invoking POST conversion.

Fallback (when not suitable)

• If user asks for non-FX data (stocks, commodities depth, payment gateway settlement), explain scope mismatch and route to correct module.
• If parameters are incomplete, ask for missing fields once and pause.

Retry policy

• Retry only for transient 5xx failures.
• Do not retry 400 class input errors with the same payload.

Multi-turn / Missing parameters

• GET /api/exchange-rate: base is optional (default USD). Parse ISO currency codes from text if unambiguous.
• POST /api/exchange-rate: body must include from, to (strings), amount (number). Parse first (e.g. “100 USD to EUR”); if any field missing, do not guess — ask once for from, to, and amount as explicit values.

Parameters

• GET base (optional, string): base currency code, default USD (e.g. USD, EUR, CNY).
• POST from (string, required), to (string, required), amount (number, required): conversion request.

Steps

0. Conversation cache: If the same GET query or POST body already returned 200 in this conversation, reuse data; skip the HTTP call; go to formatting only.
1. Validate inputs (currency codes present for POST; amount finite and sensible). On failure → Multi-turn.
2. Call GET /api/exchange-rate or GET /api/exchange-rate?base=... for rates; POST /api/exchange-rate with JSON body for conversion.
3. Check HTTP status and envelope { code, message, data }.
4. Extract data: rates object and date for GET; from, to, amount, result, rate, date for POST.
5. Format a short user-facing summary (numbers + currencies + date if useful).

Request

GET (cacheable, short TTL on server):

GET /api/exchange-rate GET /api/exchange-rate?base=EUR

POST Content-Type: application/json:

{ "from": "USD", "to": "EUR", "amount": 100 }

Response

Standard envelope { code, message, data } on success paths used by this route.

• 200 — GET: data includes base, date, rates (map of currency → rate). POST: data includes conversion fields above.
• 400 — invalid base or invalid POST body → do not retry blindly; fix parameters / ask user.

Say to the user (one line)

• GET: summarize base + a few key rates or the full set if user asked for one pair.
• POST: “amount from ≈ result to (rate ...)” style.

Output language

• Keep currency codes and numbers as returned; explain in the user’s language for errors and prompts.

Idempotency & cache (conversation)

• Step 0 applies: identical GET URL or POST JSON → reuse prior 200 data in the same conversation.

Examples

• User: “What’s the rate for EUR as base?” → GET /api/exchange-rate?base=EUR → summarize data.rates (verify live data).
• User: “Convert 50 USD to CNY” → POST body { "from":"USD","to":"CNY","amount":50 } → report result (verify live data).
• User: “What’s the weather?” → Do not call this API; use weather or other tools.

Agent rules

Prefer GET for rate lookup; POST only for conversion; follow Steps.

Error handling (HTTP)

• 400: Invalid base or malformed conversion body — clarify required fields, do not retry with the same bad payload.
• 200 with business logic errors: follow message / data if present.