# Docs

bitcoinrouter.ai sells pay-as-you-go keys for AI models, paid in sats from your Lightning wallet. This page explains everything the app doesn't.

## Getting started

1.  **Get Lexe.** Install the [Lexe wallet](https://lexe.app/) on iOS or Android and add some sats. Or use a wallet you have that supports Nostr Wallet Connect. See [Wallets](https://bitcoinrouter.ai/docs#wallets). Or skip the wallet and [top up manually](https://bitcoinrouter.ai/docs#top-up) by paying an invoice from any Lightning wallet. Manual top-ups are non-refundable.
2.  **Create an account.** Choose a password, and a username if you like. We don't ask for an email. Without a username you log in with your account number, so note it down. There's no password reset: see [Lost password](https://bitcoinrouter.ai/docs#lost-password).
3.  **Connect your wallet.** Scan the code on the Connect page with Lexe, or open the link on your phone, and approve **bitcoinrouter.ai**. For another wallet, choose Nostr Wallet Connect instead.
4.  **Create a key.** Pick a provider. A new account makes one payment first: $1 for Tinfoil, $5 for TrustedRouter. Your wallet pays it when you press the button, and the key is created once it lands. See [Your first payment](https://bitcoinrouter.ai/docs#first-payment).
5.  **Use it.** Copy the key (we show it once) and point any OpenAI-compatible app at the provider's base URL. See [Using your key](https://bitcoinrouter.ai/docs#using-your-key).

From then on, your wallet pays automatically as you use your keys.

## How billing works

You pay the provider's price plus our premium ([Fees](https://bitcoinrouter.ai/docs#fees)). We read each key's usage from the provider, charge it to your account, and send invoices to your connected wallet, which pays them automatically.

Your dashboard shows **Available**, your **balance** and your **pay-later limit**.

### Available

What your keys can still spend right now. All your keys share it. Each key is capped at the provider, so your keys stop at this amount even if we're offline.

Available = your balance + your pay-later limit

### Balance

What you've paid minus what you've used.

-   **Prepaid** (above $0): paid but not used yet.
-   **Owed** (below $0): used but not paid yet. Your wallet pays it automatically.

### Pay-later limit

How far below $0 your balance can go: how much you can use before paying. It starts at $0 and grows by 5% of everything you use, up to a cap:

| Your keys | Cap | Reached after using |
| --- | --- | --- |
| Tinfoil only | $1 | $20 |
| TrustedRouter (or both) | $20 | $400 |

-   It only applies while one of your wallets is connected and working. If none is, it drops to $0 until fixed. What you've used is never forgotten.
-   With no keys, it's $0: there's nothing to pay later for.

### Your first payment

Before a key is created, Available must reach your [buffer](https://bitcoinrouter.ai/docs#buffer). So a new account pays it up front: $1 for Tinfoil, $5 for TrustedRouter.

-   It isn't a fee. It's spent on your usage like any other payment.
-   If you later add a key at a provider with a larger buffer, you pay the difference first.

### Automatic payments

When Available drops below half your buffer, we send your wallet an invoice that brings Available back up to it. Your wallet pays it automatically. It shows in Lexe with the note "bitcoinrouter.ai", which only you can see.

-   That's about one payment per half buffer of use: every 50¢ or so on Tinfoil, every $2.50 or so on TrustedRouter.
-   When your keys have been idle for an hour, we collect anything you owe (10¢ or more), so you don't carry a balance.
-   With no keys we never ask you to prepay. We only collect what you owe.
-   **Pay now** on your dashboard makes the same payment on demand. It shows when Available is below your buffer, or when your wallet needs attention.

### Manual top-ups

Any account can also top up manually by paying an invoice from any Lightning wallet, under Manual top-up in your dashboard's Billing card. A new account's first key is paid for the same way. Top up any amount from 10¢ to $1,000, and hold up to $1,000 prepaid.

-   **Non-refundable.** A manual top-up is a prepayment you chose yourself, so it stays until it's spent. Pausing refunds only what we pulled from a wallet.
-   **Spent first,** before anything we pulled, so it never sits behind refundable money.
-   **Automatic payments never take your balance past $100.** They only bring it up to your buffer, so with a manual top-up above that none are made until it's used. With a wallet connected you rarely need a top-up at all.

### Refunds

Everything we pull from a connected wallet is a prepayment for inference, and the unspent part can come back. Pause your account and we refund it to the wallet it came from: one payment per wallet, in sats at that day's rate, less a 0.5% network fee (what our Lightning node pays to send). Your keys stop while paused; resume and they pick up where they left off, with a new payment if your buffer needs one.

Two charts. With prepaid credits, on a $20 scale, you buy $20 up front, spend it down, and $6 is left unused. With bitcoinrouter.ai, on a $2 scale, your wallet pays $1 at a time, pausing sends the unspent $0.60 back to it, and after you resume, you use first and pay after, each payment bringing you back to $0.

Your balance is a prepayment, not a wallet. These rules keep it that way:

-   **It buys one thing.** A prepayment is spent on inference through your keys and on nothing else. It can't be moved to another account, spent anywhere else, or paid out in dollars.
-   **We set every amount we pull.** Each payment is sized to your usage: one turn to start, then refills as you use it. The buffer is a number of turns for parallel requests, not a sum you pick. The one amount you choose yourself, a [manual top-up](https://bitcoinrouter.ai/docs#top-up), is non-refundable. What we pull never takes your balance past $100.
-   **Refunds go back where the payment came from.** Each refund is paid to the wallet that made the payment: a Lexe wallet by its identity, an NWC wallet over the very connection that paid. Never to a different wallet, a different person, or in dollars. Remove that wallet and its share becomes non-refundable; reconnect the same Lexe wallet and it's refundable again. An NWC wallet without `make_invoice` can't receive.
-   **A refund is a settle-out, not a withdrawal.** It happens only while your account is paused, and it returns everything unspent at once. There is no partial refund and no way to take out a sum of your choosing. Resume, and prepayment starts again from your buffer.
-   **Sats at the day's rate, both ways.** We price in dollars and collect in bitcoin. A payment turns sats into dollars of prepayment at that moment's rate, and a refund turns the unspent dollars back into sats at the rate on the day of the refund. If bitcoin rose in between you get fewer sats back; if it fell, more. Neither of us picks the rate.
-   **Only what that wallet paid.** Nothing refundable is ever granted: no free credit, referral credit or bonus. What you paid by invoice, including the $1 try-it, is non-refundable and is spent first, so it never sits behind refundable money.
-   **Paying later costs nothing.** Using before you pay carries no interest and no fee. The next payment collects what you owe, with only Lexe's 0.5% on the payment itself.

### Pausing

Pause stops every key: each is capped at what it has used, no automatic payment is made, and your pay-later limit is $0 until you resume. Anything you still owe is collected as usual. Resume lifts all of that.

### When you stop prepaying

Each automatic payment refills Available to your buffer. Because Available is balance plus pay-later limit, your balance right after a payment is your buffer minus your pay-later limit.

-   **While your pay-later limit is below your buffer,** you hold the difference prepaid. It shrinks as you use more.
-   **Once your pay-later limit reaches your buffer,** each payment only covers what you've already used. Your balance stays at $0 or below.

At the default buffer, that happens after:

| Your keys | Buffer | Reached after using |
| --- | --- | --- |
| Tinfoil only | $1 | $20 |
| TrustedRouter (or both) | $5 | $100 |

Your balance can still go above $0 if:

-   **You raise your buffer above your pay-later limit.** Each payment then leaves the difference prepaid.
-   **You press Pay now when almost nothing is due.** Payments are at least 10¢, so a few cents may stay prepaid.

### Buffer

The level each automatic payment refills Available to.

-   **Default:** one turn, the largest single request we expect at your provider. That's $1 for Tinfoil and $5 for TrustedRouter, or the larger if you hold keys at both.
-   **Raise it on your dashboard,** under Pay as you go, up to $100, for parallel requests.
-   **Above your pay-later limit,** the difference is prepaid. See [When you stop prepaying](https://bitcoinrouter.ai/docs#no-prepay).

### Fees and exchange rate

| What | Cost |
| --- | --- |
| Tinfoil usage | Tinfoil's price + 7% |
| TrustedRouter usage | TrustedRouter's price + 10% |
| Each payment | 0.5%, Lexe's Lightning fee. No base fee. |
| Refunds | 0.5%, our node's Lightning fee. Deducted from the refund. |
| Exchange rate | Market rate when the invoice is made |
| Subscription | None |
| Automatic payments | Never past $100 of balance |
| Manual top-ups | 10¢ to $1,000 each, up to $1,000 prepaid |

-   TrustedRouter's published prices already include its own 5.5% fee. Our premium is higher there because TrustedRouter passes card processing fees on to us.
-   Lexe's fee is a flat percentage, so payment size doesn't change what you pay.
-   The exchange rate is the median of Coinbase, Kraken and Bitstamp spot prices, rounded up to the millisat.
-   Amounts on your dashboard and in Activity include our premium.

### Activity and exports

Activity lists every payment and refund (USD, sats, status), your usage per key per day (UTC), and your account events. Download payments and usage as CSV.

## Privacy: who sees what

**Only the model's maker can read your prompts and replies. Not us, not the router in between. In a secure enclave, not even them.** Your key calls the provider directly, so nothing passes through bitcoinrouter.ai. We only integrate providers that keep it that way. The one exception is [web search](https://bitcoinrouter.ai/docs#web-search), which Chat turns on for new chats and you can turn off. The [privacy policy](https://bitcoinrouter.ai/privacy) is the formal version of this section.

|  | Your prompts | Your IP address | Your payments | Who you are |
| --- | --- | --- | --- | --- |
| bitcoinrouter.ai | Never | When you visit this site | Yes | Only a username, if you pick one |
| Tinfoil | No: secure enclave | Yes | No | No |
| TrustedRouter | No: enclave gateway, nothing stored | Yes | No | No |
| The model's maker | Yes, except in Tinfoil's enclaves | No: TrustedRouter calls it, not you | No | No |
| Exa (web search) | Only the searches the model writes, when search is on | No: the provider's enclave calls it | No | No |
| Lexe | No | Lexe's own policy | Payments between your wallet and ours | Lexe's own policy |

### What we see

-   **Your account:** your username, if you chose one, and a hash of your password. No email, name, card or ID.
-   **Your payments:** amount in USD and sats, time, status.
-   **Your usage:** the cost of each key, per day. Not your prompts, not which models you used.
-   **Your wallet connection.** It lets us send payments from your wallet, and read its basic info and payments. We only use it to check the connection and pay our own invoices. We keep a one-way hash of your wallet's ID to apply [debt follows the wallet](https://bitcoinrouter.ai/docs#debt).
-   **The IP address you reach this site from,** which we use for rate limiting.

### What providers see

-   **Tinfoil** runs models inside secure enclaves (TEEs). Nobody, including Tinfoil or us, can read your prompts.
    -   It sees your IP address and your key's usage.
    -   It never sees your payments or who you are: your key belongs to our company account.
-   **TrustedRouter** runs its gateway in a secure enclave and stores no prompts. The model provider it routes to (Anthropic, OpenAI and others) sees them under its own terms.
    -   TrustedRouter offers confidential routes you can choose per request (see [its docs](https://trustedrouter.com/docs)). We can't enforce that on your key.
    -   It sees your IP address, never your payments or who you are.
-   To hide your IP address from providers, use a VPN or Tor.

### Web search

With web search on, the model writes searches from your conversation and the provider's enclave sends them to Exa, a search engine. Exa sees the searches and the enclave's IP address, not yours and not who you are. It never sees your prompts, but a search can give away what a prompt was about, and a search engine can be legally compelled. Chat turns search on for new chats; turn it off with the globe button when the searches themselves would say too much. On Tinfoil, Exa keeps nothing, under a zero-data-retention agreement, and a filter inside the enclave strips personal details from each search before it leaves; Chat turns that filter on. TrustedRouter has no such agreement, so Exa keeps those searches under its own policy.

### What Lexe sees

Lexe runs the Lightning infrastructure for your wallet and ours, so it sees the payments between them.

### Verify it

-   **Tinfoil:** use [Tinfoil's SDK](https://docs.tinfoil.sh/), which verifies the enclave before sending anything. Our [Chat](https://bitcoinrouter.ai/docs#chat) page uses it and shows "Enclave verified".
-   **Chat:** open your browser's Network tab. No request to bitcoinrouter.ai carries your messages.

### Account security

-   Your password is the only way into your account, and anyone who has it can create keys paid from your wallet. Use a long, unique password from a password manager.
-   Sessions last 30 days.
-   If you think someone has your password, revoke the bitcoinrouter.ai connection in your wallet right away.

## Providers and pricing

|  | Tinfoil | TrustedRouter |
| --- | --- | --- |
| Who can read prompts | Nobody (secure enclave) | Only the model's maker, or nobody on private models |
| Models | Open models: Kimi, DeepSeek, GLM, Llama, Gemma, gpt-oss | Hundreds, including Claude, GPT and Gemini |
| Base URL | `https://inference.tinfoil.sh/v1` | `https://api.trustedrouter.com/v1` |
| Price | Tinfoil's price + 7% | TrustedRouter's price + 10% |
| First payment | $1 | $5 |
| Pay-later limit cap | $1 | $20 |
| Chat in the browser | Yes, with enclave verification | Yes |
| Model catalog | [docs.tinfoil.sh](https://docs.tinfoil.sh/) | [trustedrouter.com/models](https://trustedrouter.com/models) |

### Tinfoil

-   **Fully private.** Models run in secure enclaves, and nobody can read your prompts: not us, not Tinfoil, not the model's maker.
-   **Clients:** any OpenAI-compatible client works. To also verify the enclave from your own code, use Tinfoil's SDK ([examples](https://bitcoinrouter.ai/docs#examples)).
-   **Model ids** are short, like `kimi-k3` or `gpt-oss-120b`.

### TrustedRouter

-   **Who can read prompts:** only the model's maker (Anthropic, OpenAI and others), under its own terms. TrustedRouter's gateway runs in a secure enclave and keeps none.
-   **Private routes:** some models also run in enclaves, Tinfoil's among them, where nobody can read prompts. TrustedRouter's catalog lists each model's most private route, but routes a plain request wherever suits it. To hold one to a level, send `"provider": {"min_privacy": "trusted"}` (or `"confidential"`, `"zdr"`, `"no_store"`): a request no route can meet fails at once, unbilled. Chat does this for you.
-   **Model ids** look like `anthropic/claude-sonnet-4.5`.
-   **Some top-priced models** are bring-your-own-key only at TrustedRouter and won't work with our keys.
-   **Large requests:** TrustedRouter refuses a request whose estimated cost is more than Available (HTTP 402). Raise your [buffer](https://bitcoinrouter.ai/docs#buffer) if you need bigger requests.
-   **Streaming:** responses report their cost only if you send `"stream_options": {"include_usage": true}`. Your billing doesn't depend on it.

## Using your key

Every key works with standard OpenAI-compatible clients: set the base URL to your provider's and use your key as the API key. Most apps with a "custom OpenAI endpoint" setting work: see [Apps that work with your key](https://bitcoinrouter.ai/docs#apps).

### Examples

The official OpenAI SDKs read the environment variables in the **Env** tab, so you can leave the base URL and key out of your code.

cURL:

```
curl https://inference.tinfoil.sh/v1/chat/completions \
  -H "Authorization: Bearer tk_..." \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-v4-1-flash", "messages": [{"role": "user", "content": "Hello"}]}'
```

To also verify Tinfoil's enclave from your own code, use Tinfoil's SDK. It has the same interface as the OpenAI client:

JavaScript · Tinfoil SDK:

```
import { TinfoilAI } from "tinfoil";

const client = new TinfoilAI({ apiKey: "tk_..." });
// then client.chat.completions.create(...) as above
```

See [Tinfoil's docs](https://docs.tinfoil.sh/) for Python, Go, Swift and Rust.

**Web search** runs inside each provider's enclave. On Tinfoil, add `"web_search_options": {}` to a chat completion, and `"pii_check_options": {}` to strip personal details from the searches first. On TrustedRouter, add `"tools": [{"type": "web_search"}]`. Citations come back as links in the reply and as `url_citation` annotations. What the search engine sees is under [Privacy: web search](https://bitcoinrouter.ai/docs#web-search).

### Managing keys

-   **Limit:** up to 10 live keys per account, at any mix of providers.
-   **Names:** add a name of up to 40 characters to tell keys apart.
-   **Shared funds:** all your keys share one Available and one balance.
-   **Shown once:** we show a key only when it's created. If you lose it, revoke it and create a new one.
-   **Revoking:** we read the key's final usage, charge it, then delete the key at the provider. Anything using it stops right away.

### Errors

| Status | Meaning |
| --- | --- |
| `401` | The key was revoked or is wrong. |
| `402` | Out of funds: Available has run out, or one request costs more than it (TrustedRouter). It clears after your next payment. |
| `429` | The provider's rate limit. Wait and retry. |

## Apps that work with your key

Any app that lets you add a custom OpenAI-compatible provider works. Give it:

-   **Base URL:** your key's provider's. A key works only at its own provider.
    -   Tinfoil keys (`tk_...`): `https://inference.tinfoil.sh/v1`
    -   TrustedRouter keys (`sk-tr-v1-...`): `https://api.trustedrouter.com/v1`
-   **API key:** your key.
-   **Model id:** like `deepseek-v4-1-flash` on Tinfoil or `anthropic/claude-opus-5.5` on TrustedRouter. Each provider's catalog is linked under [Providers](https://bitcoinrouter.ai/docs#providers). Many apps fetch the list for you.

Coding agents need a model that supports tool calling, and images need one that supports vision. That varies by model, so check the catalog.

Setting names are as each app's docs give them, as of October 2026.

### Coding agents

-   **[VS Code](https://code.visualstudio.com/docs/agent-customization/language-models):** Run Chat: Manage Language Models, then Add Models › Custom Endpoint, API type Chat Completions. In `chatLanguageModels.json`, set each model's `id`, and its `url` to the base URL. No Copilot plan needed.
-   **[Cline](https://docs.cline.bot/provider-config/openai-compatible):** Settings › API Provider: OpenAI Compatible, then Base URL, API Key and Model ID.
-   **[Zed](https://zed.dev/docs/ai/use-api-access):** Run `agent: open settings` › Add Provider, then the API URL, API key and model ID.
-   **[OpenCode](https://opencode.ai/docs/providers/#custom-provider):** Run `/connect` › Other and paste your key. In `opencode.json`, give that provider `"npm": "@ai-sdk/openai-compatible"`, `options.baseURL` and your `models`.
-   **[Kilo Code](https://kilo.ai/docs/providers/openai-compatible):** Settings › Providers › Custom provider, Provider API: OpenAI Compatible, then Base URL, API key and Models.
-   **[goose](https://goose-docs.ai/docs/getting-started/providers):** Settings › Models › Configure providers › Add Custom Provider, Provider Type: OpenAI Compatible, then API URL, API key and Available Models. In the CLI, run `goose configure` › Custom Providers.
-   **[JetBrains AI Assistant](https://www.jetbrains.com/help/ai-assistant/use-custom-models.html):** Settings › Tools › AI Assistant › Providers & API keys, Provider: OpenAI-compatible, then URL and API Key. Turn on Tool calling if the model supports it.
-   **[Aider](https://aider.chat/docs/llms/openai-compat.html):** Set `OPENAI_API_BASE` and `OPENAI_API_KEY`, then run `aider --model openai/<model id>`.
-   **[Qwen Code](https://github.com/QwenLM/qwen-code/blob/main/docs/users/configuration/auth.md):** Set `OPENAI_BASE_URL`, `OPENAI_API_KEY` and `OPENAI_MODEL`.

### Desktop apps

-   **[Jan](https://docs.jan.ai/desktop/remote-models/custom-endpoint):** Settings › Model Providers › Add Provider: OpenAI-compatible, then Base URL and API key. Add models with +.
-   **[Chatbox](https://docs.chatboxai.app/en/guides/providers):** Settings › Model Provider › Add › Add Custom Provider, API mode OpenAI API Compatible, then API Key and API Host (the base URL). Add a model under Models › New.
-   **[Cherry Studio](https://cherryai.com/docs/en/pre-basic/providers/zi-ding-yi-fu-wu-shang):** Settings › Model Provider › + Add Provider, type OpenAI, then API Key and API Host. Sync models, or add a model id with +, and switch the provider on.
-   **[AnythingLLM](https://docs.anythingllm.com/setup/llm-configuration/cloud/openai-generic):** Settings › AI Providers › LLM, provider Generic OpenAI, then Base URL, API Key and the model.
-   **[Msty Studio](https://docs.msty.ai/studio/managing-models/online-providers):** Model Hub › Model Providers › Add Provider, as an OpenAI-compatible endpoint, then the base URL and API key.
-   **[BoltAI](https://help.boltai.com/articles/8306364-add-an-ai-provider-and-api-key):** Paid, macOS. Settings › AI Providers › Add a Provider, then the Base URL and API key.

### Phone apps

-   **[Chatbox](https://docs.chatboxai.app/en/guides/providers):** iOS and Android. Open the sidebar (top left) › Settings, then as on desktop.
-   **[Kelivo](https://github.com/Chevey339/kelivo):** iOS, and Android from GitHub. Settings › Providers › Add Provider (OpenAI), then API Key and API Base URL.
-   **[RikkaHub](https://github.com/rikkahub/rikkahub):** Android. Settings › Providers › Add Provider (OpenAI), then API Key and API Base URL.
-   **[AnythingLLM](https://docs.anythingllm.com/mobile/overview):** Android. Settings › LLM Preference › Generic OpenAI, then Base URL and API Key.

### Self-hosted web apps

-   **[Open WebUI](https://docs.openwebui.com/getting-started/quick-start/connect-a-provider/starting-with-openai-compatible/):** Settings › Admin › Connections › Add Connection, then URL and API Key. List your Model IDs to keep the model picker short.
-   **[LibreChat](https://www.librechat.ai/docs/quick_start/custom_endpoints):** In `librechat.yaml`, add an entry under `endpoints.custom` with `name`, `baseURL`, `apiKey` and `models`.
-   **[LobeHub](https://github.com/lobehub/lobehub):** Settings › AI Providers › Create Custom AI Provider, Request Format OpenAI, then Proxy URL (the base URL) and API Key.
-   **[SillyTavern](https://docs.sillytavern.app/usage/api-connections/openai/):** API: Chat Completion, Chat Completion Source: Custom (OpenAI-compatible), then the endpoint, API key and model ID.

### Other apps and tools

-   **[Raycast](https://manual.raycast.com/ai/custom-providers):** Needs Raycast Pro. Settings › AI › Custom Providers opens `providers.yaml`: set `base_url`, `api_keys` and `models`.
-   **[Copilot for Obsidian](https://github.com/logancyang/obsidian-copilot):** Settings › Copilot › BYOK › Add a provider › Add a custom provider, then Base URL, API key and model.
-   **[Page Assist](https://github.com/n4ze3m/page-assist):** A browser extension. Settings › OpenAI Compatible API › Add Provider, then Base URL and API Key.
-   **[llm](https://llm.datasette.io/en/stable/other-models.html):** Add the model to `extra-openai-models.yaml` with `model_id`, `model_name`, `api_base` and `api_key_name`.
-   **[Shell-GPT](https://github.com/TheR1D/shell_gpt):** Set `API_BASE_URL`, `OPENAI_API_KEY` and `DEFAULT_MODEL` in `~/.config/shell_gpt/.sgptrc`.
-   **[OpenAI SDKs](https://bitcoinrouter.ai/docs#examples):** They read `OPENAI_BASE_URL` and `OPENAI_API_KEY`. See the examples above.

## For agents

Everything here works over plain HTTP with no browser, so an AI agent with a Lightning wallet can buy its own key. This is the whole flow. The API is documented at [/api.md](https://bitcoinrouter.ai/api.md), these docs are at [/docs.md](https://bitcoinrouter.ai/docs.md), and this section alone is [/agents.md](https://bitcoinrouter.ai/agents.md).

### 1\. Create an account

```
curl -s -X POST https://bitcoinrouter.ai/api/signup/code
# {"account_id": 42, "login_code": "k7mq-3xzp-wq2n-7hd4-vt6s", "session": "..."}
```

-   **Save the login code first.** It is the only way back into the account; there is no recovery. An account that never pays is deleted a week after signup.
-   **Authenticate** every later call with `Authorization: Bearer <session>`; the examples below keep the token in `$SESSION`. Sessions last 30 days; a new one comes from logging in with the account id and the code:

```
curl -s -X POST https://bitcoinrouter.ai/api/login \
  -H 'content-type: application/json' \
  -d '{"identifier": "42", "password": "k7mq-3xzp-wq2n-7hd4-vt6s"}'
```

### 2\. Prepay one turn

A key needs its provider's first payment: $1 at Tinfoil, $5 at TrustedRouter (`GET /api/keys/quote?provider=tinfoil` says exactly what). Pay an invoice from any Lightning wallet:

```
curl -s -X POST https://bitcoinrouter.ai/api/invoices \
  -H "authorization: Bearer $SESSION" -H 'content-type: application/json' \
  -d '{"amount_usd": null, "provider": "tinfoil"}'
# {"payment_id": 7, "invoice": "lnbc...", "amount_usd": 1.0, "amount_sats": 893, ...}

curl -s https://bitcoinrouter.ai/api/payments/7 -H "authorization: Bearer $SESSION"
# {"state": "settled", ...}   poll until it leaves "pending"
```

Invoices expire after ten minutes, and what they pay is [non-refundable](https://bitcoinrouter.ai/docs#refunds). Or connect a wallet that supports Nostr Wallet Connect, and we pull payments from it as the key is used. Pause the account and the unspent part of those goes back to it (see [Refunds](https://bitcoinrouter.ai/docs#refunds)):

```
curl -s -X POST https://bitcoinrouter.ai/api/funding/nwc \
  -H "authorization: Bearer $SESSION" -H 'content-type: application/json' \
  -d '{"uri": "nostr+walletconnect://..."}'

curl -s -X POST https://bitcoinrouter.ai/api/topup \
  -H "authorization: Bearer $SESSION" -H 'content-type: application/json' \
  -d '{"provider": "tinfoil"}'
# {"payment_id": 8}   then poll /api/payments/8 as above
```

### 3\. Create the key

```
curl -s -X POST https://bitcoinrouter.ai/api/keys \
  -H "authorization: Bearer $SESSION" -H 'content-type: application/json' \
  -d '{"provider": "tinfoil"}'
# {"key": {"base_url": "https://inference.tinfoil.sh/v1", ...}, "secret": "tk_..."}
```

The secret is returned once. A 409 carries a stable code: `topup_required` (pay first), `key_limit` (one key without a wallet, ten with one), `wallet_has_debt` (another account funded by your wallet owes money), `account_paused`.

### 4\. Use it

The key works at its provider's OpenAI-compatible base URL and nowhere else. `GET /api/providers` lists providers without auth. For web search, see [Examples](https://bitcoinrouter.ai/docs#examples).

```
export OPENAI_BASE_URL="https://inference.tinfoil.sh/v1"
export OPENAI_API_KEY="tk_..."
# model: deepseek-v4-1-flash
# TrustedRouter: https://api.trustedrouter.com/v1, model anthropic/claude-opus-5.5
```

### 5\. Keep it running

-   `GET /api/me` shows `headroom_usd` (what the keys can still spend), each key's `usage_usd` and its `paused_reason`, and the last payments.
-   **Without a wallet,** a key stops when the prepayment runs out (`paused_reason: "exhausted"`). Pay another invoice, up to $1,000 prepaid per account, and it resumes.
-   **With a wallet,** we pull a refill when `headroom_usd` drops below half of `target_usd` (one turn by default), and collect what is owed after an hour idle. `POST /api/topup` does it on demand.
-   Errors are `{"error": "..."}`. 429 is a rate limit: back off. Dollar fields are JSON numbers, times are milliseconds since the epoch.

## Chat in your browser

The Chat page runs entirely in your browser.

-   **Direct to the provider:** prompts and replies go straight from your browser to the provider with your key. bitcoinrouter.ai only serves the page and your balance.
-   **Tinfoil:** the page uses Tinfoil's SDK to verify the enclave ("Enclave verified") and to encrypt each message to it, end to end.
-   **TrustedRouter:** Chat doesn't verify TrustedRouter's gateway. Messages pass through it to the model's provider (Anthropic, OpenAI, …), which sees them, unless the model is private.
-   **Who can read each model:** the model picker says. **Private**: it runs in an enclave, and nobody can read your messages. **ZDR**: its host keeps nothing once it replies. **No-store**: its host doesn't store them. No label: only the model's maker can. On TrustedRouter, Chat holds every message to the level shown, which can cost more than the model's cheapest route, and says so if no route at that level is up. The ⓘ beside a model shows its price as you pay it.
-   **Uncensored models:** TrustedRouter has open models with their refusals removed, marked Uncensored in the picker. They answer almost anything, so weigh what they say.
-   **Images:** models marked with an image icon can read them. Chat shrinks each one in your browser first. Every message resends the chat's earlier images, and TrustedRouter takes about 9 MB per message, so start a new chat if one fills up.
-   **Web search:** the globe button lets the model search the web, on models that can, when it needs to. It's on for new chats; turn it off per chat. Searches go to a search engine from inside the provider's enclave, not from your browser: see [Privacy: web search](https://bitcoinrouter.ai/docs#web-search). A reply that searched costs more: what it read counts as input, and Tinfoil charges about six cents per message that searched.
-   **Voice input:** the microphone button beside Send records a clip, up to three minutes. Start talking once a red dot and a timer appear and the message box says "Listening…": until then, your microphone is still starting. Press the check mark when you're done and the provider turns the clip into text in the message box, for you to edit and send. On a phone, you can instead hold the button while you talk and let go when you're done, which turns it into text the same way. Slide left to cancel, or up to keep recording without holding. It's never sent by itself. A clip costs about 1¢. It goes from your browser to the provider like a message: on Tinfoil, encrypted end to end to its enclave; on TrustedRouter, through its gateway to the same Whisper model in Tinfoil's enclave. It never reaches us, and Chat doesn't save it.
-   **Read aloud:** the speaker under a reply reads it aloud, skipping code and tables. Its text goes from your browser to the provider with your key, like a message, in parts on a long reply. The default voices run in Tinfoil's enclave (on TrustedRouter, through its gateway to the same enclave), so nobody can read the text; they cost about 1¢ a part. On TrustedRouter you can pick an ElevenLabs voice instead, under **Voice** in Chat's ⋯ menu: ElevenLabs reads the text, for about 5¢ per 1,000 characters. The audio never reaches us, and Chat doesn't save it.
-   **Regenerate:** the circular arrow under the last reply asks again, with the model you've picked now, and replaces the reply. Branch first to keep it.
-   **Saved in this browser:** chats are kept here only, images included, separately for each account, and aren't encrypted. On a shared computer, anyone using this browser profile can read them.
-   **Deleting them:** delete a chat from the chat list. Clearing this site's data in your browser deletes them all.

### How your key is stored

-   **Where:** this browser's local storage for bitcoinrouter.ai keeps one key per provider for each account: the last one you created here or pasted in Chat.
-   **Never sent to us:** it's only sent to the provider, when you chat.
-   **Removing it:** **Forget key in this browser**, in Chat's ⋯ menu, removes it. So does revoking that key on the dashboard, unless you pasted it.
-   **Shared computers:** anyone who can use this browser profile can read it. Don't save keys on shared computers.
-   **Other devices:** paste any of your keys for that provider on the Chat page.

## Wallets

### Lexe

[Lexe](https://lexe.app/) is a self-custodial Lightning wallet for iOS and Android, and the one we recommend. Other wallets can connect with [NWC](https://bitcoinrouter.ai/docs#nwc).

-   **Connecting:** approve "bitcoinrouter.ai" in the Lexe app. The connection lasts up to a year (Settings shows when it ends). Reconnect when it expires: connecting the same wallet again renews it.
-   **What the connection allows:** sending payments from your wallet, and reading its basic info and payments.
    -   Lexe doesn't support spending limits on connections yet, so the limits are ours.
    -   We only pay our own invoices, sized by your [buffer](https://bitcoinrouter.ai/docs#buffer), and never more than $100 at a time.
-   **Revoking:** revoke the connection in Lexe at any time. Your keys keep running on any prepaid balance, then stop.
-   **Refunds** go to your wallet's Bitcoin address, fetched over the connection, so reconnect first if it has expired or been revoked.
-   **Fees:** Lexe charges 0.5% per payment.

### Connect with NWC

Nostr Wallet Connect (NWC) lets other Lightning wallets pay. At the top of the Connect page, choose "Nostr Wallet Connect", then pick your wallet and follow its steps.

-   **Coinos or Alby Hub:** approve "bitcoinrouter.ai" in the window that opens.
-   **Alby Go:** open it from the page on your phone, or scan the code with it, then approve "bitcoinrouter.ai".
-   **Zeus, Primal or another wallet:** create a connection in your wallet and paste its connection string, which starts with `nostr+walletconnect://`. Keep that string secret: it can spend from your wallet. If your wallet scans codes, "Or scan a code" under Other wallet works too.
-   **What the connection allows:** sending payments and reading basic wallet info. We don't ask for a spending limit, so set one for bitcoinrouter.ai in your wallet if you want one. Our own limits apply too, as with Lexe.
-   **Requirements:** the wallet must support NIP-44 encryption. Older wallets that only offer NIP-04 can't connect.
-   **Refunds** go back over the same connection, so the wallet must support `make_invoice`. Most do; the wallet's row in Settings says if it doesn't.
-   **Revoking:** delete the connection in your wallet at any time.

Lexe's own NWC can't send payments today, so connect Lexe with the Lexe app as above.

### Several wallets

You can connect up to five wallets, e.g. Lexe and Coinos. Settings lists them in the order we pay from them.

-   **Your default wallet** is the first, and pays whenever it can. A new Lexe wallet goes first; a new NWC wallet goes last.
-   **If it can't pay**, we try the next one, and go back to your default once it works again.
-   **Your pay-later limit** works while any of your wallets does.
-   **In Settings**, change the order, rename a wallet, make a payment from it, or remove it.
-   **Pay now** pays from your first working wallet, else your default, unless you pick another under "From".
-   **Removing a wallet** works unless a payment from it is in progress, or you owe money and it's your only working wallet.

## Limits and failed payments

### Limits

| What | Limit |
| --- | --- |
| Live keys | 10 per account, 1 without a wallet |
| Key name | 40 characters |
| Wallets | 5 per account |
| Wallet name | 40 characters |
| Buffer | your default, up to $100 |
| One automatic payment | 10¢ to $100 |
| Manual top-up | 10¢ to $1,000, up to $1,000 prepaid |
| Wallet connection | up to a year, set by Lexe |
| Connect code | expires after 10 minutes |
| Session | 30 days |

-   Providers set their own rate limits.
-   We read usage from the provider shortly after each request, so Available can briefly dip below $0. Your next payment covers it.

### When a payment fails

-   **Temporary failures** (a route fails, an invoice expires): we retry automatically, waiting longer each time, up to an hour between tries. Your keys keep working while you have Available.
-   **Declined by your wallet** (not enough sats, connection revoked or expired, no permission to pay): we stop retrying and mark your wallet **Needs attention**.
    -   Your pay-later limit pauses too, so your keys stop once your balance reaches $0.
    -   If you were already paying later, that's right away.
-   **To fix it:** add sats to Lexe and press **Pay now**, or reconnect your wallet. Your keys resume as soon as Available is above $0.
-   **Meanwhile,** you can top up manually from any Lightning wallet, under Manual top-up in your dashboard's Billing card.

### Paused keys

| Dashboard says | What to do |
| --- | --- |
| Out of funds | Nothing. It resumes after your next payment. |
| Your wallet needs attention | See [When a payment fails](https://bitcoinrouter.ai/docs#payment-failed). |
| Your wallet isn't responding | Nothing, unless your wallet is offline. It resumes on its own once your wallet answers. |
| Rejected | Revoke it and create a new one. |

### Owing money

-   You can't remove a wallet while a payment from it is in progress, or while you owe money and it's your only working wallet.
-   **Debt follows the wallet.** While a wallet owes money on one account, any other account it's connected to can't create keys and has no pay-later limit. You can pay the debt from any of their dashboards, even if you've lost the login to the account that owes.
-   Using one wallet for several accounts is otherwise fine.

### Lost password

There's no password reset, because we don't have your email. A lost password means a lost account, and any balance on it.

If you lose your password:

-   Revoke the bitcoinrouter.ai connection in your wallet, so we can't take more payments. Your keys stop once Available runs out.
-   Anything you owe on that account stays tied to that wallet. You can pay it from another account the wallet is connected to.

**Lost account code?** The same applies. But while you're still logged in somewhere, Settings shows it, and lets you set a password instead.

## FAQ

**Do I need a Lexe wallet?**

It's the smoothest: a free, self-custodial Lightning wallet for iOS and Android. Wallets with Nostr Wallet Connect (NWC), like Coinos, Alby, Zeus and Primal, work too.Or use none: top up manually by paying an invoice from any Lightning wallet. Manual top-ups are non-refundable.

**What do I pay up front?**

$1 for a Tinfoil key, $5 for TrustedRouter. It isn't a fee: it's spent on your usage.

**Can I get my money back?**

Yes. Pause your account and every unspent dollar we pulled goes back to the wallet it came from, in sats at that day's rate, less a 0.5% network fee. Refunds are all or nothing, only to the wallet that paid, never in dollars. Invoices you paid yourself, including the $1 try-it, are non-refundable.

**What's the pay-later limit?**

How much you can use before paying. It grows with everything you use: after $20 of use on Tinfoil ($100 on TrustedRouter), your wallet only pays for what you've already used.

**Can you see my prompts?**

No, and neither can the router. Only the model's maker can, and in Tinfoil's secure enclaves not even they can.

**What if a payment fails?**

We retry. If your wallet declines, your keys pause until you add sats and press Pay now, or reconnect. Your dashboard shows what to fix.

**What if I forget my password?**

There's no reset, because there's no email. Use a password manager.

**Do you know who I am?**

No. We see payments and usage totals, never your name.

**What does “Try it for $1” get me?**

Chat with Tinfoil's private models, paid from any Lightning wallet, with no signup. $1 covers many prompts, as each is billed at cost; $5 opens Claude, GPT and more at TrustedRouter. Instead of a password you get an account code: save it, as it's the only way back in. The $1 is non-refundable; what we later pull from a connected wallet can be refunded.

**Can I connect more than one wallet?**

Yes, up to five. We pay from your default wallet, and if it can't pay, from the next one. See [Several wallets](https://bitcoinrouter.ai/docs#several-wallets).

**Why did my balance go negative?**

You used your pay-later limit. Your wallet pays it automatically.

**Can I use one key for both providers?**

No. Each key belongs to one provider. Create one of each; they share your Available.

**Which models can I use?**

Any in the provider's catalog: see [Providers](https://bitcoinrouter.ai/docs#providers).

**Is Chat private?**

Your messages go straight from your browser to the provider. On Tinfoil they're encrypted end to end to a verified enclave. On TrustedRouter the model's maker sees them. With web search on, the search engine sees the searches the model writes, not you: see [Web search](https://bitcoinrouter.ai/docs#web-search).

**Why did my key stop working?**

Check your dashboard: it says why. See [Paused keys](https://bitcoinrouter.ai/docs#paused-keys).