Documentation

Byoky Docs

Star—

Everything you need to integrate Byoky into your app — from quickstart to API reference.

Building with an AI assistant?
Copy the setup prompt, paste into Claude, ChatGPT, or Cursor, and start building with a Byoky-aware model.

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 throughKeys live in
Desktop browser (Chrome, Firefox)Byoky browser extensionthe extension
Safari on iPhone / iPadByoky 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 URLthe mobile app
CLI tools and desktop apps@byoky/bridge (localhost) → native messagingthe extension
Your backend@byoky/sdk/server over your own WebSocket → user's browserthe 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 API

CLI 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

bash
npm install @byoky/sdk

Scaffold a new project

bash
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-relay

User wallets

Your users need one of these installed:

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):

bash
# .env.local or shell
BYOKY_DEV_KEYS=anthropic:sk-ant-...,openai:sk-...
typescript
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:

typescript
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:

typescript
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-key for Anthropic, query ?key= for Gemini, Authorization: Bearer for everyone else).

Byoky Client

Constructor

typescript
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)
});
timeoutnumber
Milliseconds to wait for the wallet to respond to a connect request. Defaults to 60000.
requestTimeoutnumber
Milliseconds a request made with createFetch 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[]
List of providers your app needs. 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[]
Optional list of capabilities your app intends to use, passed through to the wallet with the connect request.
modalboolean | ModalOptions
Show the built-in connect modal. While the wallet asks the user for approval, the modal shows a waiting state. If no wallet is installed, it shows “Byoky wallet not found” with an install link for the user's browser, an “I've installed it” button that re-checks, and a hint that on a phone the page can be opened in the Byoky app's built-in browser. Pass ModalOptions to customise it.
typescript
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.

typescript
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

typescript
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

typescript
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 Gemini
mistralMistral
cohereCohere
xaixAI (Grok)
deepseekDeepSeek
perplexityPerplexity
groqGroq
togetherTogether AI
fireworksFireworks AI
openrouterOpenRouter
azure_openaiAzure OpenAI
ollamaOllama (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).

anthropicanthropic
openaiopenai, mistral, xai, deepseek, perplexity, groq, together, fireworks, openrouter, azure_openai, ollama, lm_studio
geminigemini
coherecohere

Capability 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.

FamilyStreamingTool useVisionJSON modeReasoning
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:

typescript
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:

typescript
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

typescript
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:

typescript
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

typescript
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)

typescript
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.

typescript
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

typescript
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

typescript
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

typescript
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

typescript
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.

typescript
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

idstring
Exact model ID to pass in chat requests.
providerIdstring
Provider this model is hosted on.
displayNamestring?
Human-readable label, when the provider supplies one.
contextWindownumber?
Max input context in tokens, when known.
capabilitiesPartial<ModelCapabilities>?
Best-effort flags (vision, tools, reasoning, structuredOutput). Some providers omit these — undefined means unknown, not unsupported.
rawunknown
Full provider payload for advanced consumers.

Per-provider behaviour

ProviderEndpoint hitNotes
openai, mistral, xai, lm_studio/v1/modelsOpenAI-compatible {data:[...]} shape
openrouter/api/v1/modelsOpenAI-compatible shape
groq/openai/v1/modelsOpenAI-compatible shape
deepseek/modelsOpenAI-compatible shape
fireworks/inference/v1/modelsOpenAI-compatible shape
anthropic/v1/modelsIncludes capabilities (vision, thinking, structured_outputs)
gemini/v1beta/modelsFilters out embedding-only models; strips the models/ prefix from IDs
cohere/v1/modelsFilters to chat-capable models; reads features for capabilities
together/v1/modelsReturns a plain array (no data wrapper) — handled transparently
azure_openai/openai/models?api-version=...Returns deployments rather than upstream model IDs
ollama/api/tagsLists 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_LOCKED or QUOTA_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.

CodeMeaningWhat to do
WALLET_NOT_INSTALLEDNo 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_REJECTEDThe 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_UNAVAILABLEThe 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_EXPIREDThe 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_SESSIONA 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_LIMITEDByoky'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_EXCEEDEDA 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_ALLOWEDThe 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_LOCKEDThe wallet is locked (HTTP 423).Ask the user to unlock their wallet, then retry.
INVALID_URLThe 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_UNSUPPORTEDThe 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_SUPPORTEDA 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_FAILEDThe 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_FAILEDThe 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_UNAVAILABLEThe 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_ERRORThe 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_MISMATCHA 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_UNSUPPORTEDconnect() 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_REQUESTThe 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_RELOADEDByoky 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_ERRORThe 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_KEYOnly 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_EXPIREDReserved; 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_ERRORGeneric 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_FAILEDServer 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_DISCONNECTEDServer 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).
UNKNOWNAnything 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:

typescript
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

typescript
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.

OperationLimitWindow
Connect requests per origin1060 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, countTokens and embedding actions, Cohere's chat, embed and rerank, and Ollama's generate, chat and show.
  • GET for model lists only (/models and /models/{id}), plus Ollama's /api/tags and /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 with relay.onClose() and reopen when needed.

Request body size

  • Backend relay: a request your server sends through @byoky/sdk/server may be at most 1 MB once serialized (URL, headers and body together). Above that, client.createFetch() throws a ByokyError with code PROXY_ERROR and 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/bridge caps a single request body at 10 MB. Larger bodies fail with a 413 Payload Too Large at 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 API

Frontend

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)

typescript
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 API

Setup

bash
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,openai

Usage

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.

bash
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 ↔ Cohere

How it works

  1. User creates groups in their wallet (e.g. "Claude", "GPT")
  2. Each group is pinned to a specific credential and provider
  3. Dragging an app between groups reroutes its traffic
  4. 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.

Developer Docs — Byoky