Byoky Docs
Everything you need to integrate Byoky into your app — from quickstart to API reference.
Getting Started
SDK Reference
Overview
Byoky is the MetaMask for API keys. Users keep their AI API keys in an encrypted wallet on their own device. Your app connects to the wallet the way a dapp connects to MetaMask: it asks for access, the user approves, and your app gets a proxied session that routes requests through the wallet. Your app never sees the keys.
How it works
Your App → SDK (createFetch) → Content Script → Extension → LLM API
↑
Keys stay here. Always.Pass the session's fetch and key to the provider SDK you already use; the rest of your code stays the same. Streaming, vision, tool use and inline images and PDFs all work through the wallet. Apps can call inference and model-list endpoints only (see Allowed endpoints). Sessions auto-reconnect if the extension restarts.
No servers. Byoky doesn't run anything between your app, the wallet and the provider. There are no accounts, no cloud sync and no relay service to configure — the wallet talks only to the AI providers the user has added. Keys move between devices only when the user exports and imports a password-protected .byoky backup.
Where Apps Connect
Every integration path ends at a wallet on the user's own device. Each wallet serves the apps on that device — there is no pairing between a phone and a desktop, and no Byoky server in between. Users who want the same keys on several devices move them with a password-protected .byoky backup file.
| App runs in… | Connects through | Keys live in |
|---|---|---|
| Desktop browser (Chrome, Firefox) | Byoky browser extension | the extension |
| Safari on iPhone / iPad | Byoky Safari extension (included with the iOS app) | the Safari extension |
| Byoky's in-wallet browser (iOS, Android) | injected wallet bridge (window.__byoky__) — open any https app by URL | the mobile app |
| CLI tools and desktop apps | @byoky/bridge (localhost) → native messaging | the extension |
| Your backend | @byoky/sdk/server over your own WebSocket → user's browser | the extension |
Web apps
The same SDK code works in all three web environments: the desktop extension, the iOS Safari extension, and the in-wallet browser of the iOS and Android apps. They expose the same page protocol (the in-wallet browser injects the same window.__byoky__ bridge and message protocol as the extension), so byoky.connect() and session.createFetch() need no changes. On a phone without the Safari extension, users can open your app's URL in the Byoky app's built-in browser — the connect modal points them there.
On iOS these are two separate wallets: the Safari extension keeps its own keys (added in its popup), and the iOS app's keys serve its in-wallet browser. They don't share credentials.
Browser apps → SDK (createFetch) → Content Script → Extension → LLM API
Safari (iOS) → SDK (createFetch) → Safari Extension → LLM API
In-wallet apps → SDK (createFetch) → Native bridge → iOS / Android app → LLM APICLI tools and desktop apps
Tools that run outside a browser talk HTTP to @byoky/bridge on localhost, which hands each request to the extension over native messaging. See Bridge, and the OpenClaw, Claude Code and Hermes guides.
Your backend
When your server needs to make the LLM call, the user's browser relays it through the wallet over a WebSocket server you run. See Backend Relay.
Installation
Install the SDK
npm install @byoky/sdkScaffold a new project
npx create-byoky-app my-app
# Choose a template:
# 1. AI Chat (Next.js)
# 2. Multi-Provider (Vite)
# 3. Backend Relay (Express)
# Or skip the prompts (CI, scripts):
npx create-byoky-app my-app --template chat # chat | multi-provider | backend-relayUser wallets
Your users need one of these installed:
- Chrome Extension
- Firefox Extension
- iOS App (wallet + in-wallet browser, plus the Byoky Safari extension)
- Android App (wallet + in-wallet browser)
Each wallet serves the apps on its own device. See Where Apps Connect.
Quickstart
Connect and make your first request in under a minute:
import Anthropic from '@anthropic-ai/sdk';
import { Byoky } from '@byoky/sdk';
const byoky = new Byoky();
const session = await byoky.connect({
providers: [{ id: 'anthropic', required: true }],
modal: true, // built-in connect UI, with install guidance if no wallet is found
});
// Use the native Anthropic SDK — just swap in Byoky's fetch
const client = new Anthropic({
apiKey: session.sessionKey,
fetch: session.createFetch('anthropic'),
dangerouslyAllowBrowser: true, // safe with Byoky: apiKey is a session token, not a key
});
const message = await client.messages.create({
model: 'claude-sonnet-4-6',
max_tokens: 1024,
messages: [{ role: 'user', content: 'Hello!' }],
});That's it. Streaming, vision, tool use and multipart uploads to inference endpoints work unchanged. Storage APIs such as Files and Batches are blocked; see Allowed endpoints.
Why dangerouslyAllowBrowser?
The official Anthropic and OpenAI SDKs refuse to run in a browser unless you pass dangerouslyAllowBrowser: true; without it their constructors throw. The guard exists because a real API key in page code can be read by anyone who opens the page. With Byoky, apiKey is session.sessionKey, a per-app session token that only works through the wallet the user approved. The real key never reaches the page, so the flag is safe here.
Dev Sandbox
For local development and CI, the SDK can run without a wallet at all. Pass your own keys via byoky.connectMock() and the returned session behaves exactly like a real one — same createFetch, same provider IDs — except requests go straight to the upstream provider.
This is a development convenience, not a security boundary. The SDK refuses to construct a mock session when NODE_ENV=production. Never ship code that relies on it.
From an environment variable
Set BYOKY_DEV_KEYS to a comma-separated list of provider:key pairs. Works in Node.js (CI, scripts, server-side tests):
# .env.local or shell
BYOKY_DEV_KEYS=anthropic:sk-ant-...,openai:sk-...import { Byoky } from '@byoky/sdk';
const session = await new Byoky().connectMock();
// Use the session exactly like a real one
import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic({
apiKey: session.sessionKey,
fetch: session.createFetch('anthropic'),
});With explicit keys
For unit tests, browser dev, or cases where the env var isn't available:
const session = await new Byoky().connectMock({
keys: {
anthropic: process.env.ANTHROPIC_API_KEY!,
openai: process.env.OPENAI_API_KEY!,
},
});Local providers (Ollama, LM Studio, Azure)
Providers without a fixed upstream host accept a per-provider baseUrl:
const session = await new Byoky().connectMock({
keys: { ollama: 'ollama' }, // local servers usually accept any value
baseUrls: {
ollama: 'http://localhost:11434',
},
});Caveats
session.createRelay()throws — relays go through a real wallet.session.getUsage()always returns zeros — no metering happens.- Cross-provider routing and group rebinding are not simulated.
- The auth header convention is fixed per provider (
x-api-keyfor Anthropic, query?key=for Gemini,Authorization: Bearerfor everyone else).
Byoky Client
Constructor
import { Byoky } from '@byoky/sdk';
const byoky = new Byoky({
timeout: 60000, // how long connect() waits for the wallet to answer (ms)
requestTimeout: 600000, // how long a proxied request waits for response headers (ms)
});timeoutnumber60000.requestTimeoutnumbercreateFetch waits for the response headers before it is stopped (in the wallet and upstream) and rejects with PROXY_ERROR. A non-streaming response sends its headers only once generation is done, so keep this above your longest generation. Defaults to 600000 (10 minutes); 0 waits forever.byoky.connect(options)
Connect to the user's Byoky wallet: the browser extension, the iOS Safari extension, or the in-wallet browser of the iOS and Android apps (they all expose the same page protocol). Returns a ByokySession.
const session = await byoky.connect({
// Which providers your app needs
providers: [
{ id: 'anthropic', required: true },
{ id: 'openai', required: false },
],
// Show the built-in connect modal (wallet detection + install guidance)
modal: true,
});providersProviderRequirement[]required: true marks one your app can't work without: the wallet points it out in the approval prompt, but the connection still succeeds when the user has no key for it. After connecting, check session.providers[id]?.available.capabilitiesstring[]modalboolean | ModalOptionsModalOptions to customise it.interface ModalOptions {
container?: HTMLElement; // mount point (defaults to document.body)
theme?: {
accentColor?: string; // default '#7C3AED'
backgroundColor?: string; // default '#100D16'
textColor?: string; // default '#ECE8F4'
borderRadius?: string; // default '0px'
};
}By default the modal uses Byoky's dark violet look with square corners. Raised surfaces, borders and secondary text follow your backgroundColor and textColor, so a light theme works as well as a dark one; set both together.
Without modal, connect() throws a ByokyError with code WALLET_NOT_INSTALLED when no wallet is present (and opens the store page for the user's browser, if there is one). USER_REJECTED means the user declined in the wallet or the approval timed out. With modal: true, closing the modal rejects with WALLET_NOT_INSTALLED when no wallet was found, and otherwise with a plain Error('User cancelled').
byoky.tryReconnect()
Silently reconnect to an existing session for the current origin. Checks the wallet's live session first, then the session persisted in sessionStorage. Returns null if nothing is restorable. Good first call on every page load.
const session = await byoky.tryReconnect();
if (session) {
// Restored — ready to make requests
}byoky.reconnect(savedResponse)
Restore a session from a ConnectResponse you stored yourself. Store the whole object (sessionKey, proxyUrl and providers), not just the key. Returns null if the wallet no longer recognises it.
const saved = JSON.parse(localStorage.getItem('byoky-session') ?? 'null');
const session = saved ? await byoky.reconnect(saved) : null;byoky.connectMock(options)
Development only: returns a session that calls providers directly with keys you supply. See Dev Sandbox.
Utilities
import { isExtensionInstalled, getStoreUrl } from '@byoky/sdk';
// True when a Byoky wallet is present on this page
// (extension, iOS Safari extension, or in-wallet browser)
if (isExtensionInstalled()) { ... }
// Get the store URL for the user's browser
const url = getStoreUrl(); // Chrome Web Store, Firefox Add-ons, etc.Session API
A ByokySession is returned by connect(), tryReconnect(), reconnect(), or connectMock(). It provides everything you need to make API calls through the wallet.
Connecting again on the same Byoky instance replaces the session it returned before. The old session still makes requests, but what the wallet reports on its own (a revoked session, changed providers, Byoky reloading) reaches only the new one. The old session's own requests can still fire its callbacks: onDisconnect when a request finds Byoky reloaded or the expired session can't be renewed, and onProvidersUpdated when a request renews it. Register your callbacks on every session you get.
session.createFetch(providerId)
Returns a fetch function that proxies requests through the wallet for the given provider. Use it as a drop-in replacement with any provider SDK.
// Anthropic
const client = new Anthropic({
apiKey: session.sessionKey,
fetch: session.createFetch('anthropic'),
dangerouslyAllowBrowser: true,
});
// OpenAI
const client = new OpenAI({
apiKey: session.sessionKey,
fetch: session.createFetch('openai'),
dangerouslyAllowBrowser: true,
});
// Or raw fetch
const fetch = session.createFetch('anthropic');
const res = await fetch('https://api.anthropic.com/v1/messages', {
method: 'POST',
headers: { 'content-type': 'application/json', 'anthropic-version': '2023-06-01' },
body: JSON.stringify({ model: 'claude-sonnet-4-6', max_tokens: 1024, messages: [...] }),
});It takes an AbortSignal like the real fetch: aborting before the response headers rejects with the signal's reason, aborting later errors the body, and either way the wallet stops the upstream call. Cancelling the response body (res.body.cancel(), reader.cancel(), or leaving a for await loop early) also stops the wallet's upstream call, as with fetch. An abort also ends the wait while an expired session is renewed. Request bodies can be strings, bytes, Blobs, FormData, URLSearchParams or streams, and binary responses such as audio arrive byte for byte.
session.listModels(providerId)
List the models the user's credential can access for a provider. See Model Discovery.
session.createRelay(wsUrl)
Open a WebSocket relay channel to your own server so your backend can make LLM calls through this session. Requires wss:// (or ws:// on localhost). See Backend Relay.
session.disconnect()
Disconnect the session. The wallet revokes all access, and the session's relays close. The session is done afterwards: its fetches reject with NO_SESSION and createRelay() throws, so call connect() for a new one. A second disconnect() does nothing.
session.isConnected()
Returns true if the session is still valid.
session.getUsage()
Get token usage stats for this session.
interface SessionUsage {
requests: number;
inputTokens: number;
outputTokens: number;
byProvider: Record<string, {
requests: number;
inputTokens: number;
outputTokens: number;
}>;
}
const usage = await session.getUsage();
// { requests: 42, inputTokens: 15000, outputTokens: 8000,
// byProvider: { anthropic: { requests: 42, inputTokens: 15000, outputTokens: 8000 } } }session.onDisconnect(callback)
Register a callback for when the user revokes this session from the wallet.
session.onProvidersUpdated(callback)
Register a callback for when provider availability changes — e.g. the user adds a credential, revokes one, or swaps the provider group bound to your app (cross-provider routing). The callback receives the new session.providers record.
Session properties
session.sessionKey // string — use as apiKey in provider SDKs
session.proxyUrl // deprecated — internal transport marker, don't rely on it
session.providers // Record<ProviderId, ProviderStatus>
interface ProviderStatus {
// true: the wallet can serve this provider, with a credential of its
// own or by routing it to another provider the user set up.
// false: it can't right now; createFetch(id) requests will fail.
available: boolean;
// How the credential authenticates upstream.
authMethod: 'api_key' | 'oauth';
}Check session.providers[id]?.available before calling a provider, and use ?.: a provider the wallet can't serve may be missing from the record. available: true doesn't mean a direct key: the user may route your app to another provider (see Cross-Provider Routing). When the user adds a credential or changes routing, onProvidersUpdated fires with the new record.
Providers
All providers work with createFetch(providerId):
anthropicAnthropic (Claude)openaiOpenAI (GPT)geminiGoogle GeminimistralMistralcohereCoherexaixAI (Grok)deepseekDeepSeekperplexityPerplexitygroqGroqtogetherTogether AIfireworksFireworks AIopenrouterOpenRouterazure_openaiAzure OpenAIollamaOllama (local)lm_studioLM Studio (local)Wire-format families
Providers fall into one of four wire-format families. Two providers in the same family speak the same API surface and are byte-for-byte interchangeable; crossing families requires the wallet's translation layer (see Cross-Provider Routing).
anthropicanthropicopenaiopenai, mistral, xai, deepseek, perplexity, groq, together, fireworks, openrouter, azure_openai, ollama, lm_studiogeminigeminicoherecohereCapability matrix
What each family supports natively at the wire-format level. Capabilities below this baseline depend on the specific model — e.g. Cohere's Command A drops vision. Always check the provider's docs for the exact model you target.
| Family | Streaming | Tool use | Vision | JSON mode | Reasoning |
|---|---|---|---|---|---|
anthropic | ✓ | ✓ | ✓ | ✓ (output_config.format) | ✓ |
openai | ✓ | ✓ | ✓ | ✓ (json_schema, json_object) | ✓ |
gemini | ✓ | ✓ | ✓ | ✓ (responseMimeType) | ✓ |
cohere | ✓ | ✓ | — | ✓ (json_object, json_schema) | ✓ |
Local providers
ollama and lm_studio point at a user-run loopback server (default http://localhost:11434 for Ollama, http://localhost:1234 for LM Studio). The wallet stores the per-credential base URL alongside the API key — your app code doesn't need to know which port. Both expose an OpenAI-compatible chat surface, so they belong to the openai wire-format family.
Your app can call these providers, and azure_openai, on the registry's placeholder host: https://YOUR_RESOURCE.openai.azure.com/... for Azure, or the default localhost port for Ollama and LM Studio. Every wallet sends such a request to the credential's own endpoint, so listModels() works for Azure and for local servers on another port or on 127.0.0.1.
Streaming
Every provider's streaming format works unchanged through createFetch. The proxy forwards response chunks over a persistent port — no buffering, no polling, no special flags on your end.
With a provider SDK
The easiest path — the SDK handles SSE parsing for you:
import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic({
apiKey: session.sessionKey,
fetch: session.createFetch('anthropic'),
dangerouslyAllowBrowser: true,
});
const stream = client.messages.stream({
model: 'claude-sonnet-4-6',
max_tokens: 1024,
messages: [{ role: 'user', content: 'Write a haiku.' }],
});
const output = document.querySelector('#output')!;
for await (const event of stream) {
if (event.type === 'content_block_delta'
&& event.delta.type === 'text_delta') {
output.textContent += event.delta.text;
}
}With raw fetch
If you prefer to call the HTTP API directly, parse SSE from the returned response.body:
const fetch = session.createFetch('anthropic');
const res = await fetch('https://api.anthropic.com/v1/messages', {
method: 'POST',
headers: {
'content-type': 'application/json',
'anthropic-version': '2023-06-01',
},
body: JSON.stringify({
model: 'claude-sonnet-4-6',
max_tokens: 1024,
stream: true,
messages: [{ role: 'user', content: 'Hello!' }],
}),
});
const output = document.querySelector('#output')!;
const reader = res.body!.getReader();
const decoder = new TextDecoder();
let buf = '';
read: while (true) {
const { done, value } = await reader.read();
if (done) break;
buf += decoder.decode(value, { stream: true });
const lines = buf.split('\n');
buf = lines.pop() || '';
for (const line of lines) {
if (!line.startsWith('data: ')) continue;
const event = JSON.parse(line.slice(6));
if (event.type === 'message_stop') break read;
if (event.type === 'content_block_delta'
&& event.delta.type === 'text_delta') {
output.textContent += event.delta.text;
}
}
}OpenAI-compatible providers (OpenAI, Groq, DeepSeek, xAI, Mistral, Together, Fireworks, Perplexity, OpenRouter) stream choices[0].delta.content in the same SSE envelope. Gemini uses streamGenerateContent.
Tool Use
Tool use (a.k.a. function calling) works unchanged through the proxy. Define tools, let the model call them, execute locally, feed results back — loop until the model stops asking for tools.
Anthropic format
const fetch = session.createFetch('anthropic');
const tools = [{
name: 'get_weather',
description: 'Get current weather for a city',
input_schema: {
type: 'object',
properties: { city: { type: 'string' } },
required: ['city'],
},
}];
const messages: Array<Record<string, unknown>> = [
{ role: 'user', content: "What's the weather in Tokyo?" },
];
for (let round = 0; round < 5; round++) {
const res = await fetch('https://api.anthropic.com/v1/messages', {
method: 'POST',
headers: {
'content-type': 'application/json',
'anthropic-version': '2023-06-01',
},
body: JSON.stringify({
model: 'claude-sonnet-4-6',
max_tokens: 1024,
tools,
messages,
}),
});
const data = await res.json();
const toolCalls = data.content.filter((b: any) => b.type === 'tool_use');
if (toolCalls.length === 0) {
console.log(data.content.find((b: any) => b.type === 'text')?.text);
break;
}
const results = toolCalls.map((tc: any) => ({
type: 'tool_result',
tool_use_id: tc.id,
content: JSON.stringify(runTool(tc.name, tc.input)),
}));
messages.push({ role: 'assistant', content: data.content });
messages.push({ role: 'user', content: results });
}OpenAI-compatible format
Used by OpenAI, Groq, DeepSeek, xAI, Mistral, Together, Fireworks, Perplexity, and OpenRouter. Tools are wrapped in { type: 'function', function: { ... } }, and the model returns choices[0].message.tool_calls:
const fetch = session.createFetch('openai');
const tools = [{
type: 'function',
function: {
name: 'get_weather',
description: 'Get current weather for a city',
parameters: {
type: 'object',
properties: { city: { type: 'string' } },
required: ['city'],
},
},
}];
const messages: Array<Record<string, unknown>> = [
{ role: 'user', content: "What's the weather in Tokyo?" },
];
for (let round = 0; round < 5; round++) {
const res = await fetch('https://api.openai.com/v1/chat/completions', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ model: 'gpt-5.5', tools, messages }),
});
const data = await res.json();
const msg = data.choices[0].message;
if (!msg.tool_calls?.length) { console.log(msg.content); break; }
messages.push(msg);
for (const tc of msg.tool_calls) {
const args = JSON.parse(tc.function.arguments);
messages.push({
role: 'tool',
tool_call_id: tc.id,
content: JSON.stringify(runTool(tc.function.name, args)),
});
}
}Structured Output
Get typed JSON back from any OpenAI-compatible provider, plus Anthropic. Two modes exist: OpenAI's strict json_schema (enforced by the model), and the looser json_object mode supported by most OpenAI-compatible providers.
OpenAI strict schema
const fetch = session.createFetch('openai');
const res = await fetch('https://api.openai.com/v1/chat/completions', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({
model: 'gpt-5.5',
messages: [{ role: 'user', content: 'Extract: "Jane, jane@acme.co, Acme"' }],
response_format: {
type: 'json_schema',
json_schema: {
name: 'contact',
strict: true,
schema: {
type: 'object',
properties: {
name: { type: 'string' },
email: { type: 'string' },
company: { type: 'string' },
},
required: ['name', 'email', 'company'],
additionalProperties: false,
},
},
},
}),
});
const data = await res.json();
const contact = JSON.parse(data.choices[0].message.content);json_object (Groq, DeepSeek, Mistral, Together, Fireworks, OpenRouter, xAI)
body: JSON.stringify({
model: 'llama-3.3-70b-versatile',
messages: [{ role: 'user', content: 'Return JSON with keys name, email.' }],
response_format: { type: 'json_object' },
});Anthropic
Claude takes a JSON schema in output_config.format (structured outputs, Claude 4.5 and later, and Opus 4.1). A routed request carries it over: an OpenAI json_schema, a Gemini responseSchema or a Cohere json_schema reaches Claude as structured outputs.
const res = await fetch('https://api.anthropic.com/v1/messages', {
method: 'POST',
headers: {
'content-type': 'application/json',
'anthropic-version': '2023-06-01',
},
body: JSON.stringify({
model: 'claude-sonnet-4-6',
max_tokens: 1024,
messages: [{ role: 'user', content: 'Extract: "Jane, jane@acme.co"' }],
output_config: {
format: {
type: 'json_schema',
schema: {
type: 'object',
properties: { name: { type: 'string' }, email: { type: 'string' } },
required: ['name', 'email'],
additionalProperties: false,
},
},
},
}),
});
const data = await res.json();
const contact = JSON.parse(data.content[0].text);Vision
Image inputs work through the proxy just like text. Anthropic, OpenAI, and Gemini each take a different wire format — the payload pattern below matches what ships in the demo.
Convert a File to base64
async function fileToBase64(file: File): Promise<string> {
const buffer = await file.arrayBuffer();
const bytes = new Uint8Array(buffer);
let binary = '';
for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
return btoa(binary);
}Anthropic
body: JSON.stringify({
model: 'claude-sonnet-4-6',
max_tokens: 1024,
messages: [{
role: 'user',
content: [
{
type: 'image',
source: { type: 'base64', media_type: file.type, data: base64 },
},
{ type: 'text', text: 'What is in this image?' },
],
}],
});OpenAI
body: JSON.stringify({
model: 'gpt-5.5',
messages: [{
role: 'user',
content: [
{
type: 'image_url',
image_url: { url: `data:${file.type};base64,${base64}` },
},
{ type: 'text', text: 'What is in this image?' },
],
}],
});Gemini
body: JSON.stringify({
contents: [{
role: 'user',
parts: [
{ inline_data: { mime_type: file.type, data: base64 } },
{ text: 'What is in this image?' },
],
}],
});Model Discovery
Build a model picker that reflects what the user actually has access to. Calling session.listModels(providerId) hits each provider's discovery endpoint through the proxy and returns a normalized list. For local providers (Ollama, LM Studio) this is the only way to know what the user has installed.
const models = await session.listModels('anthropic');
// → [
// { id: 'claude-sonnet-4-6', displayName: 'Claude Sonnet 4.6',
// contextWindow: 1_000_000, capabilities: { vision: true, reasoning: true }, raw: {...} },
// { id: 'claude-haiku-4-5', ... },
// ]
// Build a <select> from it
const options = models.map(m => ({
value: m.id,
label: m.displayName ?? m.id,
}));Returned shape
idstringproviderIdstringdisplayNamestring?contextWindownumber?capabilitiesPartial<ModelCapabilities>?rawunknownPer-provider behaviour
| Provider | Endpoint hit | Notes |
|---|---|---|
openai, mistral, xai, lm_studio | /v1/models | OpenAI-compatible {data:[...]} shape |
openrouter | /api/v1/models | OpenAI-compatible shape |
groq | /openai/v1/models | OpenAI-compatible shape |
deepseek | /models | OpenAI-compatible shape |
fireworks | /inference/v1/models | OpenAI-compatible shape |
anthropic | /v1/models | Includes capabilities (vision, thinking, structured_outputs) |
gemini | /v1beta/models | Filters out embedding-only models; strips the models/ prefix from IDs |
cohere | /v1/models | Filters to chat-capable models; reads features for capabilities |
together | /v1/models | Returns a plain array (no data wrapper) — handled transparently |
azure_openai | /openai/models?api-version=... | Returns deployments rather than upstream model IDs |
ollama | /api/tags | Lists what the user has ollama pull'd locally |
perplexity | — | No public endpoint; returns a hardcoded Sonar list |
Failure modes
listModels can throw a ByokyError with one of these codes:
PROVIDER_UNAVAILABLE— the provider id is unknown, the wallet has no credential that can serve it, or its models endpoint returned 404/405.INVALID_KEY— the provider itself rejected the credential (401/403).RATE_LIMITED— the provider returned 429.- The wallet's own code when the wallet answered rather than the provider, e.g.
SESSION_EXPIRED,WALLET_LOCKEDorQUOTA_EXCEEDED. PROXY_ERROR— anything else (transport failure, malformed response).
Defensive callers should fall back to a hardcoded list. The demo shows the pattern.
Error Handling
Errors from upstream providers surface with their original HTTP status and body — so response.status and the usual { error: { message } } body shape work the same as hitting the provider directly. A provider's own 401 or 429 carries no Byoky code: check res.status (and the provider's Retry-After header) as you would without Byoky.
The wallet adds its own errors on top. On a createFetch request they arrive as an HTTP status with { error: { code, message } } in the JSON body; connect() and listModels() throw a ByokyError with the same code. The table lists the codes apps can receive and what to do about each. The mobile wallets send a few codes of their own; handle a code you don't recognise by its HTTP status.
| Code | Meaning | What to do |
|---|---|---|
WALLET_NOT_INSTALLED | No Byoky wallet (extension, iOS Safari extension, or in-wallet browser) was detected when connect() ran. With modal: true, it is also what connect() rejects with when the user closes the “wallet not found” dialog. | Show an install prompt — getStoreUrl() returns the right link per browser. Or pass modal: true and let the SDK do it. |
USER_REJECTED | The user denied the connect request in the wallet, or the approval timed out. | Do not auto-retry. Wait for an explicit user action before calling connect() again. With modal: true the modal shows the failure with a Try Again button; if the user closes it, connect() rejects with a plain Error('User cancelled') that has no code. |
PROVIDER_UNAVAILABLE | The wallet has no credential (and no routing group) that can serve this provider (HTTP 403). From listModels(): the provider has no model-list endpoint, or it answered 404/405. | Tell the user which provider you need; deep-link them into the wallet to add a credential. |
SESSION_EXPIRED | The session key is unknown or past its expiry (HTTP 401): the user revoked the app, the wallet locked, or 24 hours passed. | createFetch first renews the session (a silent check, then a full connect: the wallet asks to unlock or approve, and a trusted site is approved silently) and retries, also for sessions restored with tryReconnect() or reconnect(). The 401 reaches your app only when that fails, and onDisconnect fires; call byoky.connect() again. |
NO_SESSION | A silent reconnect found no live session for this origin, or a call went through a session after session.disconnect(). | Expected on first visit. Fall back to connect() when the user is ready. |
RATE_LIMITED | Byoky's own connect throttle: this origin asked for a new session more than 10 times in 60 seconds. err.details.retryAfter gives the seconds to wait. listModels() also throws it when the provider answers 429. | Wait retryAfter seconds before calling connect() again. A provider's 429 on a createFetch request is not this code (see above). |
QUOTA_EXCEEDED | A spending cap the user set for your app in the wallet ran out (HTTP 429). | Do not retry. Surface a "budget exhausted" UI — the user can raise the cap in their wallet. |
ENDPOINT_NOT_ALLOWED | The request went to an endpoint outside the inference allowlist, such as the Files, Batches or Assistants APIs (HTTP 403). See Allowed endpoints. | Not retryable. Send the content inline in the inference request instead. |
WALLET_LOCKED | The wallet is locked (HTTP 423). | Ask the user to unlock their wallet, then retry. |
INVALID_URL | The request URL isn't on the provider's registered host, e.g. api.mistral.ai for mistral (HTTP 403). | Fix the URL: use the provider's official API host with createFetch(id). |
ROUTING_UNSUPPORTED | The user routed your app to another provider, and only chat requests can be routed; a model list or token count can't (HTTP 400). | Fall back, e.g. to a hardcoded model list. |
TRANSLATION_NOT_SUPPORTED | A request routed to another provider family had a binary or multipart body, which translation can't convert (HTTP 400). | Send a JSON body, or ask the user to route your app to the provider you call. |
TRANSLATION_FAILED | The wallet couldn't translate a routed request or response between provider formats (HTTP 502). | Surface the message; the request may use a feature the destination provider lacks. |
SWAP_FAILED | The wallet couldn't point a routed request at the provider the user chose (HTTP 502). | Surface the message and ask the user to check the routing group in their wallet. |
BRIDGE_UNAVAILABLE | The credential is a Claude setup token, which needs the Byoky Bridge, and the bridge isn't installed (or the browser is Safari) (HTTP 503). | Tell the user: they can install the bridge or add an Anthropic API key instead. |
BRIDGE_ERROR | The Byoky Bridge failed while carrying a setup-token request (HTTP 502), or the request is over the 20 MB the bridge takes (HTTP 413). | A 502 is safe to retry once. A 413 is not: send less (smaller files), or ask the user for an Anthropic API key, which has no such limit. |
ORIGIN_MISMATCH | A request came from a different origin than the page that connected (HTTP 403). Sessions belong to one origin. | Connect from the page that makes the requests. |
ORIGIN_UNSUPPORTED | connect() ran in a sandboxed frame or a page with an opaque origin (a data: URL, for example), which can't hold a session. | Connect from a normal https page (or localhost). |
INVALID_REQUEST | The wallet rejected malformed connect() options, e.g. a provider entry without a string id, or more than 32 providers. | Fix the options: providers is a list of { id, required? }. |
WALLET_RELOADED | Byoky was updated or reloaded while this page was open, so the page lost its line to the wallet. Requests get HTTP 503 and connect() rejects with it; the session's onDisconnect fires. | Ask the user to reload the page. Retrying without a reload fails the same way. |
EXTENSION_ERROR | The wallet's line closed in the middle of a request, before it answered: Byoky was reloaded or updated, or its background stopped, while connect() or session.getUsage() waited. Both reject with it. A page already cut off when it asks gets WALLET_RELOADED instead. | Safe to retry once. If Byoky was reloaded, the retry fails with WALLET_RELOADED: ask the user to reload the page. |
INVALID_KEY | Only from listModels(): the models endpoint answered 401 or 403. Proxied requests never carry it; a provider's 401 reaches you as the provider sent it. | Prompt the user to check the credential in their wallet. |
TOKEN_EXPIRED | Reserved; no wallet sends it. An expired Claude setup token comes back as Anthropic's own 401 response. | Nothing to handle. On a 401 from the provider, ask the user to replace the credential in their wallet. |
PROXY_ERROR | Generic proxy-layer failure: the provider couldn't be reached, the extension crashed, a native message was dropped (HTTP 502), or a request got no response headers within requestTimeout. | Safe to retry once. Surface a generic error if it repeats. |
RELAY_CONNECTION_FAILED | Server side, from handleConnection(): the browser's relay socket closed, or sent no relay:hello within helloTimeout. | Catch it in your connection listener (an unhandled rejection ends the Node process) and drop that socket. Check the relay URL the page passes to session.createRelay(). |
RELAY_DISCONNECTED | Server side: the browser went away mid-request (user closed the tab, network drop). Relay fetches and their response bodies reject with it. | Catch it like any failed fetch. The page reopens the relay with session.createRelay(url). |
UNKNOWN | Anything that doesn't map to a specific code (last-resort fallback). | Log the original message and surface a generic error. Treat as transient. |
Handling quota errors
When the user has set a spending cap for your app in their wallet and it runs out, requests fail with HTTP 429 and code: 'QUOTA_EXCEEDED'. Surface this to the user rather than retrying:
const fetch = session.createFetch('anthropic');
const res = await fetch(url, { method: 'POST', headers, body });
if (!res.ok) {
const body = await res.json().catch(() => null);
const code = body?.error?.code;
if (res.status === 429 && code === 'QUOTA_EXCEEDED') {
showQuotaExhaustedUI();
return;
}
if (code === 'SESSION_EXPIRED') {
await byoky.connect({ providers: [...], modal: true });
return;
}
throw new Error(body?.error?.message ?? `HTTP ${res.status}`);
}Listening for session lifecycle
session.onDisconnect(() => {
// The user revoked access from the wallet, or the session expired.
// Prompt them to reconnect before the next request.
showReconnectBanner();
});
session.onProvidersUpdated((providers) => {
// A credential was added/removed, or the user changed routing.
// Refresh your UI's model picker.
setAvailable(Object.entries(providers)
.filter(([, v]) => v.available)
.map(([id]) => id));
});Limits & Quotas
Byoky enforces a small set of guardrails at the wallet and bridge layers. Most apps will never hit them — but knowing the numbers up front saves a debugging round-trip.
Connection rate limits
The wallet rate-limits how often a single origin can ask for a new session, per the table below. Over the limit, connect() throws a ByokyError with code RATE_LIMITED and details.retryAfter in seconds. The cap resets on a sliding 60-second window; reconnecting to a live session doesn't count.
| Operation | Limit | Window |
|---|---|---|
| Connect requests per origin | 10 | 60 seconds |
Provider-side rate limits are separate from this cap. A provider's HTTP 429 reaches your app as the provider sent it, with its own body and Retry-After header and no Byoky code, so check res.status.
Allowed endpoints
An app that connects with the SDK, in the page or through a backend relay, can only make inference calls through the wallet. This keeps one app from reading what another app stored under the same key. Every wallet (extension, iOS, Android) applies the same rule:
- POST to inference endpoints: chat completions, completions, responses, messages (and token counting), embeddings, moderations, audio speech, transcription and translation, image generation, edits and variations, Gemini's
generateContent,streamGenerateContent,countTokensand embedding actions, Cohere's chat, embed and rerank, and Ollama's generate, chat and show. - GET for model lists only (
/modelsand/models/{id}), plus Ollama's/api/tagsand/api/version.
Everything else gets HTTP 403 with code: 'ENDPOINT_NOT_ALLOWED': the Files and Uploads APIs, Batches, fine-tuning, Assistants, Threads, Vector stores, Gemini's cachedContents, Realtime, and organization, project and key management, as well as any DELETE, PUT or PATCH. Send images, PDFs and other content inline (base64) in the inference request instead of uploading them first. The bridge for CLI tools doesn't apply this rule.
Session lifetime
- Session expiry is set by the wallet on approval. Treat it as opaque — listen for
session.onDisconnect()rather than tracking time yourself. byoky.tryReconnect()silently restores a previous session within the same tab. Useful as the first call on every page load.- A backend relay (
session.createRelay()) lives as long as the user's tab keeps its WebSocket open. Listen withrelay.onClose()and reopen when needed.
Request body size
- Backend relay: a request your server sends through
@byoky/sdk/servermay be at most 1 MB once serialized (URL, headers and body together). Above that,client.createFetch()throws aByokyErrorwith codePROXY_ERRORand the message “Request too large for the relay”. Inline images count at their base64 size (a third larger than the file), so an image over about 750 KB doesn't fit. Responses aren't capped: they stream back in pieces. - Bridge (CLI / desktop):
@byoky/bridgecaps a single request body at 10 MB. Larger bodies fail with a413 Payload Too Largeat the proxy. - In-page
createFetch: no cap of its own; the provider's request limit applies. Very large bodies still add some latency.
What is not capped
- Token usage — billed and metered by the upstream provider, not Byoky (unless the user sets a spending cap for your app).
- Concurrent requests per session — bounded only by the user's connection.
- Number of providers per session — request as many as the app actually needs.
- Number of connected apps per wallet.
Backend Relay
Need LLM calls from your server? The user's browser relays them through the wallet over a WebSocket you host. Your backend never sees the API key, and no Byoky server is involved.
Your backend ←WebSocket (your server)→ User's browser ←→ Byoky extension → LLM APIFrontend
import { Byoky } from '@byoky/sdk';
const session = await new Byoky().connect({
providers: [{ id: 'anthropic', required: true }],
modal: true,
});
// Open relay so your backend can make calls through this session
const relay = session.createRelay('wss://your-app.com/ws/relay');Each request your backend sends over the relay may be at most 1 MB serialized; larger ones throw PROXY_ERROR before they are sent. See Limits & Quotas.
Backend (Node.js)
import { ByokyServer } from '@byoky/sdk/server';
const byoky = new ByokyServer();
wss.on('connection', async (ws) => {
try {
const client = await byoky.handleConnection(ws);
const fetch = client.createFetch('anthropic');
const res = await fetch('https://api.anthropic.com/v1/messages', {
method: 'POST',
headers: {
'content-type': 'application/json',
'anthropic-version': '2023-06-01',
},
body: JSON.stringify({
model: 'claude-sonnet-4-6',
max_tokens: 1024,
messages: [{ role: 'user', content: 'Hello!' }],
}),
});
} catch (err) {
// The browser never said hello, or the tab closed mid-request.
console.error('[relay]', err);
}
});Keep the try/catch. handleConnection() rejects with RELAY_CONNECTION_FAILED when the browser closes the socket or stays silent instead of sending its relay:hello (after at most helloTimeout, 10 seconds by default). Relay fetches, and their response bodies, reject with RELAY_DISCONNECTED when the browser goes away mid-request, and with the wallet's error when the wallet refuses. An unhandled rejection in an async connection listener ends the Node process, so one closed tab would take your backend down.
Bridge (CLI / Desktop)
CLI tools and desktop apps route API calls through the bridge — a local HTTP proxy that relays requests to the extension via native messaging.
CLI App → HTTP → Bridge (localhost:19280) → Native Messaging → Extension → LLM APISetup
npm install -g @byoky/bridge
byoky-bridge install # register native messaging host (macOS, Linux)
byoky-bridge connect # approve a session, start the proxy on 127.0.0.1:19280
# more than one provider:
byoky-bridge connect --providers anthropic,openaiUsage
Installing registers the bridge but doesn't start the proxy. byoky-bridge connect opens a browser tab, you approve the session in the wallet, and the extension starts the proxy on 127.0.0.1:19280. CLI tools then make HTTP requests to http://127.0.0.1:19280/{provider}/, which the bridge forwards to the extension. The OpenClaw plugin runs this connect step itself when you log in, for a bridge of its own on 127.0.0.1:19283: each port is a separate bridge with its own session, so OpenClaw and a tool on 19280 run side by side, each with its own spending cap and routing group.
The proxy comes back on its own when the browser recycles the extension's service worker, as long as the session is valid and the wallet is unlocked. Run byoky-bridge connect again after a browser restart, after the wallet locks, or when the session expires (24 hours). A client that gets ECONNREFUSED 127.0.0.1:19280 is the sign that the proxy isn't running: run byoky-bridge connect.
Every request must carry the bridge token, so other programs on the machine can't spend the user's keys. byoky-bridge token prints it; send it wherever your client puts an API key (x-api-key, Authorization: Bearer, x-goog-api-key or api-key). Without it the bridge answers 401.
export ANTHROPIC_BASE_URL=http://127.0.0.1:19280/anthropic
export ANTHROPIC_API_KEY=$(byoky-bridge token)Cross-Provider Routing
Users can route your app's requests through a different provider than what your code targets. For example, your app calls anthropic but the user routes it through openai — the wallet transparently translates request/response bodies and SSE streams.
Your App (Anthropic SDK) → Wallet (translates) → OpenAI API
↕
Anthropic ↔ OpenAI ↔ Gemini ↔ CohereHow it works
- User creates groups in their wallet (e.g. "Claude", "GPT")
- Each group is pinned to a specific credential and provider
- Dragging an app between groups reroutes its traffic
- Request bodies, response bodies, and SSE streams are translated on the fly
No code changes required. Your app keeps calling its preferred SDK; the wallet handles the translation. Live sessions reroute automatically.