Bring Your Own Keys (BYOK)

Bring Your Own Keys (BYOK) lets your organization run the /ai endpoint on your own AI provider and model instead of CurrencyCore’s. You add a provider key in the dashboard, pick the exact model, and /ai routes its language-model calls through your account. BYOK is a Growth plan and higher feature.

The currency intelligence is unchanged: the same tool-calling engine, live rates, PPP, and historical analysis. BYOK only swaps out which language model reads the question and writes the answer.

Why use it

• Use a model you already trust / pay for. Your existing OpenAI, Anthropic, Azure, or self-hosted endpoint.
• Different metering. A BYOK answer counts as a normal API request against your monthly quota. It does not consume an AI credit. AI credits are spent only when CurrencyCore’s own models answer.
• Data residency / compliance. The model call goes from our Worker straight to the provider you configured.

Supported providers

Any OpenAI-compatible endpoint (a gateway, proxy, or self-hosted server that speaks /chat/completions with tool calls) works through the Custom option; just give it the base URL.

The model must support tool / function calling. CurrencyCore drives the conversation by calling tools (convert, rates, history analysis, …); a model that can’t call tools won’t be able to answer multi-step questions.

Set it up (owner / admin)

In the dashboard, open AI Providers and:

1. Choose a provider and (optionally) a label.
2. Enter the model id. You must specify it exactly; CurrencyCore never picks a default.
3. For Azure or a Custom endpoint, also enter the base URL (and, for Azure, the API version).
4. Paste your API key. It’s encrypted at rest and never shown again.
5. Click Test connection to run a one-shot call, then Add provider.

Finally, turn on Use my providers for /ai at the top of the page. From then on, /ai requests route to your active providers in priority order.

Metering: requests vs. AI credits

This is the core of BYOK. Which pool a /ai call draws from depends on who answered:

When your own provider answers, each request bills one API request per tool call the engine ran (convert, rates, analysis — the currency-resolution step isn’t counted). A two-conversion answer is two requests; an answer that called no data tool is free. The exact count is returned as toolCalls in the response. This mirrors a direct MCP integration, where each tool call is already one request. On a native answer (BYOK off, or a fallback) the whole request is one AI credit regardless of how many tools it ran.

Because BYOK calls count toward your API request quota, they obey the same limits and over-usage rules as /convert and the other endpoints, including your hard cap, if set.

Tool-call limit & token budget

On the AI Providers page you can set Max tool calls per request (default 10; clear it for unlimited, still bounded by the request timeout). It caps how many tool calls — and therefore how many billed requests — a single /ai call can run on your provider. Because you bring your own model and tokens, BYOK requests also get a doubled input/output token budget automatically, so longer questions and fuller answers go through without extra configuration.

Provider order & failover

Your active providers are tried top to bottom, in the order shown on the AI Providers page (drag with the ▲▼ controls to re-prioritize; the top one is the primary). Index 0 is tried first.

Failover is about whether a provider succeeds, not whether you like the answer:

• A provider that returns a successful response is final: its answer is the result, whatever it says. We never skip a provider over the content of a successful response. (So make sure your chosen model can do tool calling; a model that can’t won’t answer multi-step questions, and we won’t silently route around it.)
• A provider that fails (unreachable, times out, or returns an error status like a bad key, rate limit, or 5xx) is skipped; CurrencyCore tries your next provider.

Fallback to CurrencyCore

Each org has a fallback toggle (default on), applied only after all your providers have failed:

• On: if none of your active providers succeed, for any reason (unreachable, timeout, or an error response), CurrencyCore answers with its own model so your request still succeeds. That answer consumes 1 AI credit. Fallback is skipped only if you’re out of AI credits.
• Off: the request returns an error instead. Use this when you require that no request ever leaves your providers.

Security

• Keys are encrypted at rest (AES-GCM) with a key that lives only in the Worker runtime, and are decrypted only at call time.
• The dashboard and API only ever return a masked view. Your key is never sent back to the browser after you save it.
• Removing a provider deletes its stored key immediately.

Notes & limits

• BYOK applies to the /ai endpoint’s language model only. Rates, PPP, and historical data still come from CurrencyCore’s engine. Your provider never sees your raw data beyond the question and tool results needed to answer it.
• Historical/PPP questions still require the Growth+ entitlement on the /ai endpoint itself, BYOK or not.
• Provider configuration is Growth-gated; existing providers stop routing if a plan lapses below Growth.
• See AI Credits for how the credit pool works and Billing & Limits for the request quota BYOK calls count against.