Knowledge base / Developers

API overview

The models, generators and balance you use in the app, from your own code. The API speaks the OpenAI and Anthropic formats, so most tools and SDKs work by changing a base URL and a key.

What the API is

An HTTP API on nymbot.ai that answers the same requests an OpenAI or Anthropic client already sends. You get:

• Chat Completions, the Responses API and Anthropic Messages, with streaming, tools, pictures, reasoning and web search, for every model in the catalog and for Nymbot's own auto-routing.
• Images, video, speech, transcription and embeddings.
• Your balance, Lightning top-ups, automatic top-ups from your wallet and a history of what each request cost.

It is paid from the same two balances as the app, at the same prices. There is no subscription and no free allowance on the API: every request is paid for from credits you bought.

What the API does not do is add anything of Nymbot's own. Your messages go to the model as you sent them: no Nymbot system prompt, no memory, no date or language hints. What comes back is the model's answer and a note of what it cost.

Base URLs

Every endpoint lives under /api/v1/. An unknown path returns 404 and a known path called with the wrong method returns 405, both as JSON.

The API answers cross-origin requests from any site, so a browser page can call it. Anything you ship to a browser can be read by whoever opens it, though, so only do that with a key that has a small cap. The endpoints signed with your nym (keys, the account summary, NWC auto-top-up and refund redemption) are the exception: in a browser they answer only Nymbot's own sites. See signing account requests.

Send every JSON body with Content-Type: application/json. Any other type is refused with 415, so a plain HTML form or a text/plain request from another site cannot reach the API. With cURL, pass -H "Content-Type: application/json" along with -d.

API keys

Keys are made in the app. Open API in the sidebar of the web app, or in the menu on Android and iOS, and tap Create key. Give it a name and, if you like, a cap and an expiry date.

The key is shown once. Copy it somewhere safe before you close the sheet: Nymbot keeps only a fingerprint of it, so it cannot show it to you again. A lost key cannot be recovered; revoke it and make another.

A key looks like sk-nymbot- followed by 43 letters, digits, dashes and underscores. The app lists each key by its name and a short hint such as sk-nymbot-Qm7x…c2Lw.

• A key belongs to your nym. It spends your balance, and only your nym can make, change or revoke it. Anyone holding the key can spend with it, so treat it like a password.
• Caps are in sats. A key can have a spending cap, and the cap can reset every day, every week (Monday) or every month (the first), at 00:00 UTC. It counts both balances, a standard credit as 10 sats and a Pro credit as 100, so it means the same whichever balance a request spends. Before a request runs, the most it could cost (rounded up to whole credits) is set against what is left of the cap. If it does not fit, the request is refused with 403 key_limit_reached, even if the answer would have come in under the cap; the error says how much is left and when the cap resets. Lowering max_tokens lowers that worst case. A request is charged what it actually cost and that counts against the cap, so if the provider reports more tokens than were set aside, the last request that fit can take the key a little past its cap; the next one is then refused.
• A spent cap only stops spending. A key at its cap can still check the balance, read its history, list models, count tokens, top up and check on a video it already started.
• Expiry is optional. After the date you set, the key stops working.
• Revoking is immediate and final. A revoked key fails its next request. It stays in the list, marked revoked, so its spending history still makes sense.
• You can have up to 25 active keys, each with its own name. Changing a key's reset period starts a new period at zero.

The same sheet shows each key's spending this period and in total, when it was last used, both of your balances, and your recent API requests. The endpoints behind it are documented under managing keys.

Authenticating a request

Send the key in any one of these headers. They are equivalent, so use whichever your client sends by default:

A missing, unknown, revoked or expired key returns 401, with the code missing_api_key, invalid_api_key, revoked_api_key or expired_api_key. Listing models, audio models and voices, and payment methods needs no key.

Pictures, video, speech, transcription and embeddings can also be paid for one request at a time over Lightning with no key at all: send the request without one and pay the invoice in the 402 answer. See paying per request without a key.

Key management, the account summary and automatic top-ups are the exception: they take a signature from your nym instead of a key, so a leaked key cannot make more keys. See signing account requests.

Your first request

Put the key in an environment variable, then ask a model something. The examples throughout these pages read it from NYMBOT_API_KEY.

cURL

export NYMBOT_API_KEY="sk-nymbot-..."

curl https://nymbot.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $NYMBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nymbot/auto",
    "messages": [{"role": "user", "content": "What is a Lightning invoice?"}]
  }'

Python

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://nymbot.ai/api/v1",
    api_key=os.environ["NYMBOT_API_KEY"],
)

reply = client.chat.completions.create(
    model="nymbot/auto",
    messages=[{"role": "user", "content": "What is a Lightning invoice?"}],
)
print(reply.choices[0].message.content)

JavaScript

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://nymbot.ai/api/v1",
  apiKey: process.env.NYMBOT_API_KEY,
});

const reply = await client.chat.completions.create({
  model: "nymbot/auto",
  messages: [{ role: "user", content: "What is a Lightning invoice?" }],
});
console.log(reply.choices[0].message.content);

nymbot/auto is Nymbot's own routing, paid from the standard balance. Put a catalog model's id there instead, such as anthropic/claude-sonnet-5, to use that model from the Pro balance. Listing models gives every id.

What a request costs

The API bills exactly the way the app does.

• Which balance. nymbot/auto spends the standard balance (10 sats a credit). Every other chat model spends the Pro balance (100 sats a credit). The standard image generator and the standard voice spend standard credits; every other generator spends Pro. Embeddings spend standard credits. Transcription spends standard credits when the standard balance can cover it, and Pro credits otherwise. The models list says which balance each model spends.
• How much. A chat request is metered on the tokens the model actually read and wrote, at the provider's published rates. That price has a 5% fee added and is then multiplied by 1.5, so you pay 1.575 times the provider's list price. It is converted to sats at the live Bitcoin price and charged in thousandths of a credit. Pro pictures, video and speech are priced per generation, per second or per character, and transcription per second of audio, with the same fee and margin. The standard picture is a flat 5 standard credits and the standard voice a flat 3.
• The minimum. Every metered request that runs costs at least 0.05 credit: half a sat on the standard balance, 5 sats on Pro. Fractions of a credit are carried over, not rounded up each time.
• Hold, then settle. Before a request runs, the most it could cost is held from your balance, based on what you sent and the most tokens it may write. Text outside plain ASCII is sized from its UTF-8 bytes, and ASCII digits and punctuation count as a token each, so text in any script, code and numbers are held for in full. The hold is in whole credits, at least one, so any request needs at least 10 sats free on the standard balance or 100 sats on Pro to start. Only the actual cost is charged; the rest is released when it finishes. A long request keeps its hold for as long as it runs; if the held credits stop being available anyway, a stream stops with a 402 insufficient_balance error event, and what was generated is charged. If the actual cost is more than the balance can pay, the whole balance is taken, the rest is owed (owed_sats in the nymbot object, and a negative balance). What is owed is paid first out of the next credits that reach that balance. Until it is paid, nothing on that balance can be spent: not by the API, replies in the app, a transfer or a gift.
• Not enough credit. If the balance cannot cover the hold, the request is refused with 402 before anything runs. The error says which balance is short, how many sats the request needs and how many are free. A smaller max_tokens means a smaller hold.
• Failures. A request that fails costs nothing, unless the provider billed for the work it did before failing, or a web search or the nymbot/auto task check had already run; then that is what you pay, at least 0.05 credit. A stream you cut off is charged for the tokens the provider reports: Nymbot keeps reading the provider's stream for up to 25 seconds after you leave to get that count. If it does not arrive, the charge is estimated from what you sent and what was written, and for a model that reasons it includes the whole output allowance of the hold. A request whose connection drops still finishes and is charged.
• Web search costs $0.008 a search, converted to sats, whenever a search ran, whether the model then answers or fails. The pages it reads are also sent to the model as input, so they add their tokens.

Every response says what it cost. JSON responses carry a nymbot object with the balance it was paid from, the charge in credits and sats, and what is left:

The cost object

"nymbot": {
  "balance": "pro",
  "charged_credits": 0.162,
  "charged_sats": 16.2,
  "balance_credits": 412.425,
  "balance_sats": 41242.5
}

Paid responses also carry these headers, which is where to look for the cost of a response that is not JSON, such as speech:

Rates per million tokens, already including the fee and margin, are in the models list in dollars and sats, and on the price sheet. If the Bitcoin price cannot be read, paid requests return 503 price_unavailable with Retry-After: 60 rather than guessing.

Errors

Every error has the same shape, the one OpenAI clients already understand. code is a stable name you can match on; message is for people and may change.

Error body

{
  "error": {
    "message": "This request needs up to 200 sats (2 credits) on your Pro balance, and 40 sats are free. Catalog models spend the Pro balance. Top up in the Nymbot app or with POST /api/v1/topup/create/btc-lightning.",
    "type": "insufficient_quota",
    "code": "insufficient_balance",
    "param": null,
    "balance": "pro",
    "required_sats": 200,
    "balance_sats": 40
  }
}

Two exceptions:

• /api/v1/messages answers in Anthropic's error format, since that is what Anthropic clients parse: {"type": "error", "error": {"type": "authentication_error", "message": "…"}}. The type follows the status: invalid_request_error, authentication_error, billing_error (402), permission_error, not_found_error, request_too_large, rate_limit_error, api_error or overloaded_error (503).
• A streaming request that fails before its first byte gets an ordinary JSON error with the status above, not an event stream. A failure after the stream has started is sent as the stream's last event, in that endpoint's own format.

Error messages never contain another service's internal details. A provider's own error is reworded before it reaches you.

Limits

A link to a picture must point to a public host: an address on a private or local network, or on Nymbot's own sites, is refused. Provider pacing that applies in the app applies here too, so a burst of requests to one provider can be slowed down rather than failed.

What the API can see

The API is not private in the way the apps are, and it is worth being exact about how.

• It is not end-to-end encrypted. In the apps, a message is sealed on your device to keys only Nymbot holds and travels as a gift wrap. An API request is ordinary HTTPS: it is encrypted on the way to Nymbot, and Nymbot's server reads it in the clear to handle it.
• Prompts and replies are not stored. They pass through to the model and the answer passes back. What is kept is the bill: for each request the time, model, kind, token counts, cost, balance, key and whether it succeeded, for 90 days, which is what query history shows you. A usage record of the same request (time, kind, model, token counts, cost, duration and whether it used web search or succeeded) is also kept for 90 days, alongside the app's own.
• Everything else held for a nym is small and listed here. API keys are stored as a hash, never the key, with their name, a short hint, spending cap, reset period, expiry and when they were made and last used; only the newest 50 revoked keys are kept. An automatic top-up wallet connection is stored encrypted, with its threshold, amount and the result of the last top-up. Video jobs are kept for 24 hours. Requests paid per call leave only a Lightning payment hash for 7 days and a hashed refund token for 30 days, linked to no nym. Charges a balance could not cover are kept as owed until a top-up pays them.
• Wiping the app deletes it. A device wipe revokes and deletes every API key, and deletes the query history, usage records, wallet connection and video jobs. The balance and any charges still owed remain on the nym.
• The model's provider sees your request, as it does from the app. Catalog models run at their makers; standard routes and embeddings run on Cloudflare.
• Generated media is public. Pictures and video delivered as links are uploaded to public Blossom file hosts, where a file's address is its hash. Anyone with the link can open it, and Nymbot cannot take it down again. Ask for b64_json and a generated picture comes back in the response and is never uploaded.
• So are the pictures you give a generator. A picture you upload to edit, or send as a data: URL in a generator's image_url, is uploaded to a public Blossom host first so the generator can fetch it, and the same applies to it. A picture sent by https:// link is passed on as that link. Pictures in a chat request go to the model's provider, not to Blossom.
• A key is linked to your nym. Everything a key spends comes off your nym's balance, so API use is not anonymous. If you want API use kept apart from your everyday nym, make the keys from a separate nym with its own balance.

If you need the protection of the apps, use the apps. The API is for when you need the models in your own tools.

Every endpoint

“Nym” means a request signed by your Nostr key, described in signing account requests. For tools that already speak these formats, see tools and SDKs, and for coding agents such as Claude Code, Codex and Cline, see coding tools.