AllRatesToday × DeepSeek — allratestoday-deepseek
Give DeepSeek chat and agents real-time access to currency exchange rates and historical data, via function calling. Ships ready-to-use OpenAI-format tool schemas, a thin agent wrapper, and a CLI — for anyone building a DeepSeek app that must not hallucinate a rate.
English | 简体中文
DeepSeek's Chat Completions API is OpenAI-compatible, so the standard tools= mechanism works unchanged. This package wires four currency tools into that mechanism so DeepSeek can answer questions like:
- "What's USD to EUR right now?"
- "Convert 1000 GBP to JPY."
- "How has USD/INR moved over the last 30 days?"
- "List every supported currency."
Rates come from the AllRatesToday API — 160+ currencies, mid-market rates with no retail spread.
🚀 Features
- 🧰 Four tool schemas —
get_exchange_rate,convert_currency,get_historical_rates,list_currencies, in OpenAI/DeepSeek function-calling format (TOOLS) - 🤖 Agent wrapper —
DeepSeekCurrencyAgentruns the full tool-call loop for you (up tomax_tool_rounds, default 6) - 💻 CLI —
allratestoday-deepseekfor an interactive REPL or a one-shot--ask - 🔧 Bring your own loop — import
TOOLSanddispatch_tooland drive the OpenAI SDK yourself - 🌍 160+ currencies — mid-market rates plus
1d/7d/30d/1yhistory - 🪶 Two dependencies —
openaiandhttpx, nothing else - 🚫 No hallucinated rates — the system prompt instructs the model to call a tool rather than guess
🔑 Get your API key
Two keys are involved:
| Variable | Required? | Purpose |
|---|---|---|
DEEPSEEK_API_KEY |
Yes | Your DeepSeek key, from platform.deepseek.com/api_keys. Without it DeepSeekCurrencyAgent() raises RuntimeError. |
ALLRATES_API_KEY |
Yes for rate lookups | Your AllRatesToday key. Get a free one at allratestoday.com/register. |
ALLRATES_BASE_URL |
No | Override the API base URL (default https://allratestoday.com/api). |
Only list_currencies (GET /api/v1/symbols) answers without an AllRatesToday key. Rate, conversion and historical lookups all return 401 unauthenticated, so set ALLRATES_API_KEY for any real use. Historical lookups (get_historical_rates, and get_rates with time) need a paid plan; free and trial keys get 403 historical_requires_paid_plan.
📦 Installation
pip install allratestoday-deepseek
Python 3.9+. From a checkout, pip install -e ".[dev]" also installs pytest and ruff.
🏁 Quick start
One-shot question:
export DEEPSEEK_API_KEY=sk-...
export ALLRATES_API_KEY=art_live_...
allratestoday-deepseek --ask "What is 2500 USD in EUR right now?"
Interactive chat (type :q, exit, quit or a blank line to leave):
allratestoday-deepseek
allratestoday-deepseek --model deepseek-reasoner
As a library:
from allratestoday_deepseek import DeepSeekCurrencyAgent
with DeepSeekCurrencyAgent() as agent:
print(agent.ask("How many Japanese Yen is 500 Swiss Francs?"))
Multi-turn, keeping your own history:
from allratestoday_deepseek import DeepSeekCurrencyAgent
history = []
with DeepSeekCurrencyAgent(model="deepseek-chat") as agent:
answer = agent.ask("What is USD to EUR?", history=history)
history += [
{"role": "user", "content": "What is USD to EUR?"},
{"role": "assistant", "content": answer},
]
print(agent.ask("And to GBP?", history=history))
Runnable examples live in examples/:
python examples/ask_once.py "What's USD to EUR right now?" # one question, then exit
python examples/chat.py # interactive REPL
python examples/raw_tool_call.py # drive the tool loop yourself
📚 API reference
Tools exposed to the model
| Tool | AllRatesToday key | Parameters | Description |
|---|---|---|---|
get_exchange_rate |
Yes | source, target |
Current mid-market rate for a pair. |
convert_currency |
Yes | source, target, amount |
Fetches the pair rate and multiplies — not a separate endpoint. |
get_historical_rates |
Yes (paid plan) | source, target, period (1d/7d/30d/1y, default 7d) |
Time series: 1d hourly, 7d/30d daily, 1y weekly. |
list_currencies |
No | — | Every supported currency with code, name and symbol. |
DeepSeekCurrencyAgent
DeepSeekCurrencyAgent(
deepseek_api_key=None, # falls back to $DEEPSEEK_API_KEY
allrates_api_key=None, # falls back to $ALLRATES_API_KEY
model="deepseek-chat",
base_url="https://api.deepseek.com",
system_prompt=SYSTEM_PROMPT,
max_tool_rounds=6,
)
| Member | Description |
|---|---|
ask(question, history=None) |
Runs the tool-call loop and returns the final answer string. |
close() |
Closes the underlying HTTP client. Also available via with. |
run_chat(agent, stream_in) |
Module-level REPL helper over an iterable of user lines. |
AllRatesTodayClient
Thin httpx wrapper over the REST API, usable on its own.
| Method | Endpoint | Auth |
|---|---|---|
get_rate(source, target) |
GET /rate |
Key required by the API |
list_symbols() |
GET /v1/symbols |
None |
get_historical_rates(source, target, period="7d") |
GET /historical-rates |
Bearer key, paid plan |
get_rates(source, target, time=None, group=None) |
GET /v1/rates — comma-separated targets, group of hour/day/week/month |
Bearer key (time needs a paid plan) |
convert(source, target, amount) |
Convenience — get_rate × amount, rounded to 4 dp |
Key required by the API |
Tool plumbing
from allratestoday_deepseek import TOOLS, dispatch_tool, AllRatesTodayClient
client = AllRatesTodayClient() # reads $ALLRATES_API_KEY
result = dispatch_tool(client, "get_exchange_rate", '{"source":"USD","target":"EUR"}')
TOOLS is the list you pass as tools= to chat.completions.create. dispatch_tool accepts DeepSeek's raw JSON-string arguments or an already-parsed dict, and always returns a JSON string suitable for a role: "tool" message.
🗺️ Currencies covered
160+ currencies as returned by list_currencies, including
🇺🇸 USD · 🇪🇺 EUR · 🇬🇧 GBP · 🇯🇵 JPY · 🇨🇭 CHF · 🇨🇦 CAD · 🇦🇺 AUD · 🇳🇿 NZD · 🇮🇳 INR · 🇨🇳 CNY · 🇧🇷 BRL · 🇲🇽 MXN · 🇹🇷 TRY · 🇿🇦 ZAR · 🇸🇬 SGD · 🇭🇰 HKD · 🇰🇷 KRW · 🇦🇪 AED · 🇱🇰 LKR · 🇳🇬 NGN.
🛡️ Error handling
Tool failures are never raised into the model's face — dispatch_tool catches them and returns {"error": "..."} as the tool result, so DeepSeek can explain or retry.
from allratestoday_deepseek import AllRatesTodayClient, AllRatesTodayError
try:
AllRatesTodayClient().get_historical_rates("USD", "EUR", "30d")
except AllRatesTodayError as err:
print(err.status, err.body)
| Raised | When |
|---|---|
RuntimeError |
No DeepSeek key found when constructing the agent. |
RuntimeError |
The model kept calling tools past max_tool_rounds — raise the limit. |
AllRatesTodayError |
Any non-2xx from the API; carries .status and .body. |
AllRatesTodayError |
An authenticated endpoint was called with no AllRatesToday key. |
Common API statuses: 401 missing or invalid key · 429 rate limit or plan quota exceeded (the free tier is 300 requests in total, not per month) · 5xx upstream error.
💡 Notes
How a question is answered
- You send DeepSeek a question through
agent.ask(). - The agent calls
chat.completions.create(..., tools=TOOLS, tool_choice="auto")— DeepSeek receives all four tool schemas. - If it needs data, it emits a
tool_callsuch asget_exchange_rate(source="USD", target="EUR"). - The agent runs that tool against the AllRatesToday API and appends the JSON result as a
role: "tool"message. - Steps 2–4 repeat until DeepSeek answers in natural language, citing the live rate — or
max_tool_roundsis hit.
Compatibility — any DeepSeek model that supports function calling; deepseek-chat is the default and deepseek-reasoner is selectable with --model. CI exercises Python 3.9, 3.11 and 3.12 on Ubuntu.
Rate caching — every get_exchange_rate or convert_currency tool call is one API request, and each request counts toward your plan quota (the free tier is 300 lifetime requests that never reset). Cache aggressively if the same pair is asked for repeatedly.
🔗 Links
- Website: allratestoday.com
- API docs: allratestoday.com/docs
- Free API key: allratestoday.com/register
- Developer guide: allratestoday.com/developers
- Status: allratestoday.com/status
- Support: allratestoday.com/contact
- MCP server:
@allratestoday/mcp-server— for Claude Code, Cursor and Claude Desktop - JavaScript SDK:
@allratestoday/sdk - AI agents: Claude Code plugin
/plugin marketplace add AllRates-Today/claude-code-plugin· hosted MCP endpointhttps://allratestoday.com/api/mcp(keyless) - New in Oct 2026: agents can self-issue a trial key —
POST https://allratestoday.com/api/agent/keys(JSON) → 100 calls / 7 days — and read the keyless Daily Reference Rate (16:00 London fix) athttps://allratestoday.com/api/open/reference-rate - Dashboard: allratestoday.com/profile
- GitHub: github.com/AllRates-Today/allratestoday-deepseek
📜 License
MIT — see LICENSE.
Metadata
Release files for allratestoday-deepseek 0.2.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| allratestoday_deepseek-0.2.4.tar.gz | 13.2 kB | Without provenance | Details for allratestoday_deepseek-0.2.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| allratestoday_deepseek-0.2.4-py3-none-any.whl | Python 3 | none | any | Details for allratestoday_deepseek-0.2.4-py3-none-any.whl |
Total release size: 26.3 kB
Release files / allratestoday_deepseek-0.2.4.tar.gz
| Download URL | allratestoday_deepseek-0.2.4.tar.gz |
|---|---|
| Size | 13.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fd6033ac71615450ea5fcd4468fcfdd9a09b9b1b459b1f11ec464fbba3d2027a
|
|
BLAKE2b-256 checksum How to use checksums |
884ed1f3c3be8aaf379ef35de7669ebf2ddf11b8aa9b99bc74fcdd4ef80ca3d3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.4
|
Release files / allratestoday_deepseek-0.2.4-py3-none-any.whl
| Download URL | allratestoday_deepseek-0.2.4-py3-none-any.whl |
|---|---|
| Size | 13.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
852d05fad77b89d51c60cfb35f1c3dd20245977d79c7ad6eb8ceee68526fd26c
|
|
BLAKE2b-256 checksum How to use checksums |
6ba565c24f67fc5d8914bb7d91b80f52fba214a789f0f0b013b9674429122c31
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.4
|
Security for allratestoday-deepseek 0.2.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.