Di tin dɛn we pɔsin fɔ no bɔt / Dɛvɛlɔpɔs

Balance, top-up, and ki

Check wetin yu get, put mɔni den Lightning, mek di put mɔni de go na ɔtomatiked fɔm yu ɔn wolɛt, luk wetin ɛch rɪkwɛst kɔst, ɛn mænɛj kīz fɔm kɔd.

Dɛn translet dis pej wit mashin fɔ mek i izi fɔ am. Di Inglish ɔrijinal na di vɛshɔn we de aplay.

Mi de check di balans

Yu balens di tu, an hawan muc fɔ dis ki cap don di yuze.

GET https://nymbot.ai/api/v1/credits/balance — nid an API key. POST e wok tu, fɔ di klayan we de expect am.

balance Di tu balens de togeda na dolas wit di prais we Bitcoin de na de, fɔ tuls we de ekspek wan singul namba (null if di prais nɔ de kɔm di we (if di prais nɔ de kɔm di we). Di rest de in kredit ɛn sats, we na di we dem de kíp di balans fɔ rili. key dis tok di kii we di wan ask. Wan kii we don reach im limit kin stil check di balance.

Ansa

{
  "balance": 49.18,
  "balance_sats": 42037,
  "standard": { "credits": 120.4, "sats": 1204 },
  "pro": { "credits": 408.33, "sats": 40833 },
  "key": {
    "id": "4f0c9a1be27d3856",
    "name": "laptop scripts",
    "limit_sats": 20000,
    "period_used_sats": 3412,
    "total_used_sats": 18230,
    "reset_period": "monthly",
    "reset_at": "2026-10-01T00:00:00Z"
  }
}

cURL

curl https://nymbot.ai/api/v1/credits/balance \
  -H "Authorization: Bearer $NYMBOT_API_KEY"

Python

import os
import requests

res = requests.get(
    "https://nymbot.ai/api/v1/credits/balance",
    headers={"Authorization": "Bearer " + os.environ["NYMBOT_API_KEY"]},
)
balance = res.json()
print(balance["standard"]["sats"], balance["pro"]["sats"])

JavaScript

const res = await fetch("https://nymbot.ai/api/v1/credits/balance", {
  headers: { "Authorization": "Bearer " + process.env.NYMBOT_API_KEY },
});
const balance = await res.json();
console.log(balance.standard.sats, balance.pro.sats);

Di we yu de pey

Aw yu kin top up, ɛn di limit. Lightning na di wan ɛli metod.

GET https://nymbot.ai/api/v1/topup/payment-methods — no ki nid.

Wan top-up de go froom 10 go 1,000,000 sats; fɔ top-up Pro, yu mas bai at lɔs wan Pro kiredit, so e de stat at 100 sats. Di dolla limit de folo di Bitcoin pris. bulk_bonus di lisin di extra kredit we de kam wit bigga top-ups, de sef as in di app: 10%, 15% ɔ 20% mor pan standard top-ups fɔm 500, 1,000 ɔ 5,000 sats, an pan Pro top-ups fɔm 5,000, 10,000 ɔ 50,000 sats.

Ansa

{
  "supported_methods": [
    {
      "method": "btc-lightning",
      "display_name": "Bitcoin Lightning",
      "supported_currencies": ["SATS", "USD", "BTC"],
      "limits": {
        "SATS": { "min": 10, "max": 1000000 },
        "USD": { "min": 0.02, "max": 1170 },
        "BTC": { "min": 1e-7, "max": 0.01 }
      },
      "tiers": ["standard", "pro"],
      "default_tier": "pro",
      "tier_min_sats": { "standard": 10, "pro": 100 },
      "sats_per_credit": { "standard": 10, "pro": 100 },
      "bulk_bonus": [
        { "bonus": 0.1, "standard_sats": 500, "pro_sats": 5000 },
        { "bonus": 0.15, "standard_sats": 1000, "pro_sats": 10000 },
        { "bonus": 0.2, "standard_sats": 5000, "pro_sats": 50000 }
      ]
    }
  ]
}

cURL

curl https://nymbot.ai/api/v1/topup/payment-methods

Python

import requests

methods = requests.get("https://nymbot.ai/api/v1/topup/payment-methods").json()
print(methods["supported_methods"][0]["limits"])

JavaScript

const methods = await (await fetch("https://nymbot.ai/api/v1/topup/payment-methods")).json();
console.log(methods.supported_methods[0].limits);

Topping up di wan Lightning na wan ɔl

Mek wan Lightning invoice we go add kreddit to di nym we di ki belong to. Pay am from eni Lightning wallet, den luk am fɔ mek dɛm add dɛ dɛ kiredit.

POST https://nymbot.ai/api/v1/topup/create/btc-lightning — nid an API key.

Wan stanadad kedit na 10 sats, and wan Pro kedit na 100 sats, plus eni bɔnk bɔnas; credits e de se wetin dis invoice go add.

Ansa

{
  "invoice_id": "b7d41e0c95a2f38e6c1d0e9a4b7f2c61d3e8a05f9b2c4d7e1a6f3b8c0d5e2a9f4",
  "payment_request": "lnbc100u1p5...",
  "amount_sats": 10000,
  "credits": 115,
  "tier": "pro",
  "expires_at": "2026-09-30T09:27:00Z",
  "status": "pending"
}

cURL

curl https://nymbot.ai/api/v1/topup/create/btc-lightning \
  -H "Authorization: Bearer $NYMBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 10000, "currency": "SATS", "tier": "pro"}'

Python

import os
import requests

res = requests.post(
    "https://nymbot.ai/api/v1/topup/create/btc-lightning",
    headers={"Authorization": "Bearer " + os.environ["NYMBOT_API_KEY"]},
    json={"amount": 10000, "currency": "SATS", "tier": "pro"},
)
invoice = res.json()
print(invoice["payment_request"])

JavaScript

const res = await fetch("https://nymbot.ai/api/v1/topup/create/btc-lightning", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.NYMBOT_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ amount: 10000, currency: "SATS", tier: "pro" }),
});
const invoice = await res.json();
console.log(invoice.payment_request);

Checkin wan top-up

I de ask if dem don pay di invoice, and pan di wan we dem don pay, i de add di kredit. Di check na wetin de kredit am, so afta i don pay, de check unti di status de credited. Check am again afta dat, e go safe: di kredit go land wan taim, no matta fɔ how mani taim yu ask.

GET https://nymbot.ai/api/v1/topup/status/{invoice_id} — nid am kuli frɔm di nym we mek di invɔys.

status na pending (dem nɔ pe pa yet), paid (i de pay, bɔt de nɔt in di akt ɛn; ɛkɔr ɛgin), credited (na yu balance) o expired (no pe pay on de tɛm). De balance fild dem na fɔ de tier we de invoice de top ap.

Ansa

{
  "invoice_id": "b7d41e0c95a2f38e6c1d0e9a4b7f2c61d3e8a05f9b2c4d7e1a6f3b8c0d5e2a9f4",
  "status": "credited",
  "amount_sats": 10000,
  "credits": 115,
  "tier": "pro",
  "expires_at": null,
  "balance_credits": 523.33,
  "balance_sats": 52333
}

cURL

curl https://nymbot.ai/api/v1/topup/status/$INVOICE_ID \
  -H "Authorization: Bearer $NYMBOT_API_KEY"

Python

import os, time
import requests

headers = {"Authorization": "Bearer " + os.environ["NYMBOT_API_KEY"]}
url = "https://nymbot.ai/api/v1/topup/status/" + invoice["invoice_id"]

while True:
    status = requests.get(url, headers=headers).json()["status"]
    if status in ("credited", "expired"):
        break
    time.sleep(3)
print(status)

JavaScript

const headers = { "Authorization": "Bearer " + process.env.NYMBOT_API_KEY };
const url = "https://nymbot.ai/api/v1/topup/status/" + invoice.invoice_id;

let status;
do {
  await new Promise((r) => setTimeout(r, 3000));
  status = (await (await fetch(url, { headers })).json()).status;
} while (status !== "credited" && status !== "expired");
console.log(status);

Kuestin histri

Wan row fɔ ɛvri rikwest: wetin i bin, wetin di model bin, ɔs mani token i bin get, ɛn ɔs i bin kos. No wan prompt ɔ ansa de kɛp, so nɔmɔ wan fɔ rɛtɔn. Dɛn de kɛp di row fɔ ninety deys, di nyuist fɔst. Wan ki we don reach in limit, i de klyat rɛd fɔ rɛd in histri.

GET https://nymbot.ai/api/v1/queries/history — nid an API key, wey de si in in de kuestin, ɔ wan Ridest wey don sign frɔm yu nym, we de si evri ki.

Ansa

{
  "data": [
    {
      "id": "q_71c4e9a0",
      "timestamp": "2026-09-30T08:12:00Z",
      "model": "anthropic/claude-sonnet-5",
      "type": "chat",
      "input_tokens": 1240,
      "output_tokens": 380,
      "cached_tokens": 0,
      "cost_sats": 16.2,
      "cost_usd": 0.01895,
      "balance": "pro",
      "key_id": "4f0c9a1be27d3856",
      "web_search": false,
      "status": "ok"
    }
  ],
  "pagination": { "page": 1, "page_count": 20, "total": 311, "total_pages": 16 }
}

cURL

curl "https://nymbot.ai/api/v1/queries/history?page_count=50&type=chat" \
  -H "Authorization: Bearer $NYMBOT_API_KEY"

Python

import os
import requests

res = requests.get(
    "https://nymbot.ai/api/v1/queries/history",
    headers={"Authorization": "Bearer " + os.environ["NYMBOT_API_KEY"]},
    params={"page_count": 50, "type": "chat"},
)
for row in res.json()["data"]:
    print(row["timestamp"], row["model"], row["cost_sats"])

JavaScript

const res = await fetch("https://nymbot.ai/api/v1/queries/history?page_count=50&type=chat", {
  headers: { "Authorization": "Bearer " + process.env.NYMBOT_API_KEY },
});
for (const row of (await res.json()).data) console.log(row.timestamp, row.model, row.cost_sats);

Sinning akount rikwes de kam

Makin, chenjin, and kanyul di ki, di akount samari, and awtomatik top-up nɔ nid API ki. Dem nid wan signa frɔm yu nym, so if wan ki leak, e kin spɛnd up to im kɛp, bɔt e nɔ kin mek ɔda ki ɔ rɛiz in ɔn kɛp.

Di ap di du dis fɔ yu: evritin na in API dis sheet de yuz dis endpoints. Yu no nid dis sekshon fɔ de manage yu oda kodi de kiti.

Di signature na wan Nostr event we de kind 27235 (NIP-98), we dem send as base64-encoded in di Authorization Hed wit di wud Nostr na front:

Di paraday

{
  "kind": 27235,
  "created_at": 1790726400,
  "tags": [
    ["u", "https://nymbot.ai/api/v1/keys"],
    ["method", "POST"],
    ["nonce", "9c4e21f07a3b...16 random bytes in hex"],
    ["payload", "3f1a0d7c8e2b...sha256 of the exact request body in hex"]
  ],
  "content": "",
  "pubkey": "your public key in hex",
  "id": "...",
  "sig": "..."
}

• u na di ful URL di rekwest, inklud di query string, de eksakt we i sen.
• method na di HTTP metod.
• payload na di SHA-256 of di raw request body, in hex. Dɛn nid am pon POST ɛn PATCH, an di bodi we yu sen de hafe de bodi we yu bin hash, byte for byte.
• created_at e bin fɔ bi wit 60 sekon dɛn sɔv mɛn de klɔk.
• Evri ivɛnt wok wan taem, a GET inklod, so wan header wey dem katch no go bin kon di de rey-ple. Sign wan nyu wan fɔ ɛvri rɪkwest. Ad a nonce put wan ran-dom valyu na di tag so di tu ridist sekin de sign na di sem sekun go stil difren.
• Di bodi di wan sign rikwest ken bi mos 64 KB, an wan bodi nid Content-Type: application/json.

Wan event wek bin de miss don kam bak 401 missing_nostr_auth; wan we no gudly form, we no sign am gudly, we too ol, o fɔ difrɛn URL, metɔd o bodi rɛtɔn invalid_nostr_auth, wit di oson in di mesij; wan wey dem us de bifo de kam bak nostr_auth_replayed. API ki we di wan sen na di endpoints de rifyus. Dɛn de check di signature bifo dɛn rɛd di body, an ɛch adres kin fɛl am 30 tɛm in wan minit (an IPv6 adres kɔnt as in ful /64); ɛftā dat, ɛt gɛt 429 wit Retry-After.

Browsers kin kɔl dɛn endpoint ɔnli frɔm Nymbot in ɔn de sites (https://nymbot.ai, https://nymchat.app (an de na in subdomains). Wan pepja na enri oda site nɔ get CORS headers bak, so e nɔ de kin apɔt wetin de kin sen bak. Skrip ɛn nativ ap, we nɔ de sen nɔ Origin, dem no get am.

Dis helpa de bil wan hed. Di afta eksampul na dis peji de yuz dem. Dem de rid di sikret ki na hex frɔm NOSTR_SECRET_HEX; di cURL wan de yuz di nɔk komand-lain tul, we de tek an nsec or hex ki, an sha256sum (pon macOS, shasum -a 256).

cURL

nostr_auth() {
  method="$1"; url="$2"; body="$3"
  nonce=$(openssl rand -hex 16)
  if [ -n "$body" ]; then
    hash=$(printf '%s' "$body" | sha256sum | cut -d' ' -f1)
    event=$(nak event --sec "$NOSTR_SECRET_HEX" -k 27235 -t "u=$url" -t "method=$method" -t "nonce=$nonce" -t "payload=$hash")
  else
    event=$(nak event --sec "$NOSTR_SECRET_HEX" -k 27235 -t "u=$url" -t "method=$method" -t "nonce=$nonce")
  fi
  printf 'Nostr %s' "$(printf '%s' "$event" | base64 | tr -d '\n')"
}

Python

# pip install coincurve requests
import base64, hashlib, json, os, time
from coincurve import PrivateKey, PublicKeyXOnly

SECRET = bytes.fromhex(os.environ["NOSTR_SECRET_HEX"])

def nostr_auth(method, url, body=b""):
    pubkey = PublicKeyXOnly.from_secret(SECRET).format().hex()
    tags = [["u", url], ["method", method], ["nonce", os.urandom(16).hex()]]
    if body:
        tags.append(["payload", hashlib.sha256(body).hexdigest()])
    created_at = int(time.time())
    serialized = json.dumps([0, pubkey, created_at, 27235, tags, ""], separators=(",", ":"), ensure_ascii=False)
    event_id = hashlib.sha256(serialized.encode()).digest()
    event = {
        "id": event_id.hex(),
        "pubkey": pubkey,
        "created_at": created_at,
        "kind": 27235,
        "tags": tags,
        "content": "",
        "sig": PrivateKey(SECRET).sign_schnorr(event_id).hex(),
    }
    return "Nostr " + base64.b64encode(json.dumps(event).encode()).decode()

JavaScript

// npm install nostr-tools
import { createHash, randomBytes } from "node:crypto";
import { finalizeEvent } from "nostr-tools/pure";

const secret = Buffer.from(process.env.NOSTR_SECRET_HEX, "hex");

export function nostrAuth(method, url, body = "") {
  const tags = [["u", url], ["method", method], ["nonce", randomBytes(16).toString("hex")]];
  if (body) tags.push(["payload", createHash("sha256").update(body).digest("hex")]);
  const event = finalizeEvent(
    { kind: 27235, created_at: Math.floor(Date.now() / 1000), tags, content: "" },
    secret,
  );
  return "Nostr " + Buffer.from(JSON.stringify(event)).toString("base64");
}

Di akaunt smari

Wetin di app API shit wan sho at di top: yu pabi-kili, bot balans, aw mani kili de aktif (no bin kɔnsəl ɔ ɛkspaɪəd), ɛn di Otomatik top-up setin, o null wen di serf no ofa dem.

GET https://nymbot.ai/api/v1/account — nid wan Ridest wey don sign.

Ansa

{
  "data": {
    "pubkey": "3bf0c63fcb93463407af97a5e5ee64fa883d107ef9e558472c4eb9aaaefa459d",
    "balances": {
      "standard": { "credits": 120.4, "sats": 1204 },
      "pro": { "credits": 408.33, "sats": 40833 }
    },
    "keys_active": 3,
    "nwc_auto_topup": {
      "connected": true, "threshold_sats": 5000, "topup_sats": 20000, "tier": "pro",
      "last_topup_at": null, "last_topup_sats": null, "last_error": null
    }
  }
}

cURL

URL=https://nymbot.ai/api/v1/account
curl "$URL" -H "Authorization: $(nostr_auth GET "$URL")"

Python

import requests

url = "https://nymbot.ai/api/v1/account"
print(requests.get(url, headers={"Authorization": nostr_auth("GET", url)}).json())

JavaScript

const url = "https://nymbot.ai/api/v1/account";
const res = await fetch(url, { headers: { "Authorization": nostrAuth("GET", url) } });
console.log(await res.json());

Manejin ki 🔑

Di endpoints we de bahaun di app n key list. Ol di wan nidi a apilikeshon we yu sign. Evri ki de kam bak na dis fɔm, wit tɛm in ISO 8601 an amaut in sats:

Ki objek

{
  "id": "4f0c9a1be27d3856",
  "name": "laptop scripts",
  "hint": "sk-nymbot-Qm7x…c2Lw",
  "limit_sats": 20000,
  "reset_period": "monthly",
  "reset_at": "2026-10-01T00:00:00Z",
  "expire_at": null,
  "period_used_sats": 3412,
  "total_used_sats": 18230,
  "created_at": "2026-08-14T09:21:07Z",
  "updated_at": "2026-09-02T17:40:55Z",
  "last_used_at": "2026-09-30T08:12:00Z",
  "revoked_at": null
}

hint e ɛna fo sabi wan kii, bɔt ɛn ɛna fo yuz am. Di kii de fɔ kam bak wan ɛkɔt ɛni, wen de mek am.

Lisin kii

GET https://nymbot.ai/api/v1/keys — krayt.

Ansa

{ "data": [ { "id": "4f0c9a1be27d3856", "name": "laptop scripts", "hint": "sk-nymbot-Qm7x…c2Lw", "...": "..." } ] }

cURL

URL=https://nymbot.ai/api/v1/keys
curl "$URL" -H "Authorization: $(nostr_auth GET "$URL")"

Python

import requests

url = "https://nymbot.ai/api/v1/keys"
for key in requests.get(url, headers={"Authorization": nostr_auth("GET", url)}).json()["data"]:
    print(key["id"], key["name"], key["period_used_sats"], key["limit_sats"])

JavaScript

const url = "https://nymbot.ai/api/v1/keys";
const { data } = await (await fetch(url, { headers: { "Authorization": nostrAuth("GET", url) } })).json();
for (const key of data) console.log(key.id, key.name, key.period_used_sats, key.limit_sats);

Makin wan ki

POST https://nymbot.ai/api/v1/keys — sign. I de kam bak 201.

Ansa (201)

{
  "data": {
    "id": "4f0c9a1be27d3856",
    "name": "laptop scripts",
    "hint": "sk-nymbot-Qm7x…c2Lw",
    "limit_sats": 20000,
    "reset_period": "monthly",
    "key": "sk-nymbot-Qm7x...c2Lw",
    "...": "the rest of the key object"
  }
}

cURL

URL=https://nymbot.ai/api/v1/keys
BODY='{"name":"laptop scripts","limit_sats":20000,"reset_period":"monthly"}'
curl "$URL" \
  -H "Authorization: $(nostr_auth POST "$URL" "$BODY")" \
  -H "Content-Type: application/json" \
  -d "$BODY"

Python

import json
import requests

url = "https://nymbot.ai/api/v1/keys"
body = json.dumps({"name": "laptop scripts", "limit_sats": 20000, "reset_period": "monthly"}).encode()
res = requests.post(
    url,
    data=body,
    headers={"Authorization": nostr_auth("POST", url, body), "Content-Type": "application/json"},
)
print(res.json()["data"]["key"])

JavaScript

const url = "https://nymbot.ai/api/v1/keys";
const body = JSON.stringify({ name: "laptop scripts", limit_sats: 20000, reset_period: "monthly" });
const res = await fetch(url, {
  method: "POST",
  headers: { "Authorization": nostrAuth("POST", url, body), "Content-Type": "application/json" },
  body,
});
console.log((await res.json()).data.key);

Redin wan ki

GET https://nymbot.ai/api/v1/keys/{id} — krayt.

Kama fiti rɛtɔn dɛn {"data": {…}} wit di ki obzɛkt, ɔ 404 key_not_found if no key fɔm yu get dat ID.

cURL

URL=https://nymbot.ai/api/v1/keys/4f0c9a1be27d3856
curl "$URL" -H "Authorization: $(nostr_auth GET "$URL")"

Python

import requests

url = "https://nymbot.ai/api/v1/keys/4f0c9a1be27d3856"
print(requests.get(url, headers={"Authorization": nostr_auth("GET", url)}).json()["data"])

JavaScript

const url = "https://nymbot.ai/api/v1/keys/4f0c9a1be27d3856";
console.log((await (await fetch(url, { headers: { "Authorization": nostrAuth("GET", url) } })).json()).data);

Chanje wan ki

PATCH https://nymbot.ai/api/v1/keys/{id} — krayt.

Sen eni wan na name, limit_sats, reset_period ɛn expire_at, wit de seim rul dem de as wen yu de mek wan ki. null e klia wan fild: no limit, no reset, no deksay. If yu chenj di reset period, e go stat wan nyu period at zero. Wan key we dem bin kancul e no de kin chanji (400 key_revoked). I bak {"data": {…}} wit di ki objek we mek nju.

cURL

URL=https://nymbot.ai/api/v1/keys/4f0c9a1be27d3856
BODY='{"limit_sats":50000,"expire_at":null}'
curl -X PATCH "$URL" \
  -H "Authorization: $(nostr_auth PATCH "$URL" "$BODY")" \
  -H "Content-Type: application/json" \
  -d "$BODY"

Python

import json
import requests

url = "https://nymbot.ai/api/v1/keys/4f0c9a1be27d3856"
body = json.dumps({"limit_sats": 50000, "expire_at": None}).encode()
res = requests.patch(
    url,
    data=body,
    headers={"Authorization": nostr_auth("PATCH", url, body), "Content-Type": "application/json"},
)
print(res.json()["data"])

JavaScript

const url = "https://nymbot.ai/api/v1/keys/4f0c9a1be27d3856";
const body = JSON.stringify({ limit_sats: 50000, expire_at: null });
const res = await fetch(url, {
  method: "PATCH",
  headers: { "Authorization": nostrAuth("PATCH", url, body), "Content-Type": "application/json" },
  body,
});
console.log((await res.json()).data);

Kansel wan ki

DELETE https://nymbot.ai/api/v1/keys/{id} — krayt.

Stop di key at wan, fo gud. I de stay na di lisi wit revoked_at set, ɛn yu kin si am wit include_revoked=true. If yu kɔntrol wan ki we i ɔlredy kɔntrol, de ansa go de de de de. Wan di nabɔ di laest 50 ki we i kɔntrol de; di ol kɔntrol ki de go am de fɔm di di wan di kɔntrol.

Ansa

{ "data": { "id": "4f0c9a1be27d3856", "revoked": true } }

cURL

URL=https://nymbot.ai/api/v1/keys/4f0c9a1be27d3856
curl -X DELETE "$URL" -H "Authorization: $(nostr_auth DELETE "$URL")"

Python

import requests

url = "https://nymbot.ai/api/v1/keys/4f0c9a1be27d3856"
print(requests.delete(url, headers={"Authorization": nostr_auth("DELETE", url)}).json())

JavaScript

const url = "https://nymbot.ai/api/v1/keys/4f0c9a1be27d3856";
const res = await fetch(url, { method: "DELETE", headers: { "Authorization": nostrAuth("DELETE", url) } });
console.log(await res.json());

NWC oto-top-up

Konek wan Lightning wallet wit Nostr Wallet Connect, ɛn Nymbot de top ap di balance on in in self wen di API spɛn de mek am kɔmɔn. Di app API shit de ɛn di sɛm sɛtin; ɛs de ɛndpɔint bɛhaint am. Ol ɛn dem nid wan Ridest wey don sign.

Hau di tin waka: afta wan API rikwes bin kɔɔt de balance we yu bin ɛlɛkt fɔ wɔt, if dat balance bin kam lɛs pan de limit we yu bin ɛt, Nymbot de mek ɛn invɔys fɔ di ɛni amont we yu nid fɔ ɛp, ɛn ɔs yu wɔlɛt fɔ pe am, ɛn ɛd di kredɪt. I de ɛp de bɔs ɛkɔs wan tɛm ɛf ɛri 5 minits fɔ ɛɛch nym ɛn balance, so ɛn bɔst ɔf rikwɛstɔs nɔ go ɛbil yu wɔlɛt. Di ɛspɛndin ɛn di ɛp dɛn nɔ go tɛg ɛn ɛt am. Di tɛm ɛn di saɪz ɔf di lɛst ɛp, ɛn di lɛst ɛrɔ, de in sɛtins; if wan peimɛnt bin go ɛf afa ɛn ɛrɔ, ɛf yu ɛksɛk ɛn invɔys fɔ am wit di top-up stetɔs e kreydit am.

Konɛktin wan wallet

POST https://nymbot.ai/api/v1/nwc-auto-topup/connect — krayt.

Ansa

{
  "data": {
    "connected": true,
    "threshold_sats": 5000,
    "topup_sats": 20000,
    "tier": "pro",
    "last_topup_at": null,
    "last_topup_sats": null,
    "last_error": null
  }
}

cURL

URL=https://nymbot.ai/api/v1/nwc-auto-topup/connect
BODY='{"nwc_url":"nostr+walletconnect://...","threshold_sats":5000,"topup_sats":20000,"tier":"pro"}'
curl "$URL" \
  -H "Authorization: $(nostr_auth POST "$URL" "$BODY")" \
  -H "Content-Type: application/json" \
  -d "$BODY"

Python

import json, os
import requests

url = "https://nymbot.ai/api/v1/nwc-auto-topup/connect"
body = json.dumps({
    "nwc_url": os.environ["NWC_URL"],
    "threshold_sats": 5000,
    "topup_sats": 20000,
    "tier": "pro",
}).encode()
res = requests.post(
    url,
    data=body,
    headers={"Authorization": nostr_auth("POST", url, body), "Content-Type": "application/json"},
)
print(res.json())

JavaScript

const url = "https://nymbot.ai/api/v1/nwc-auto-topup/connect";
const body = JSON.stringify({
  nwc_url: process.env.NWC_URL,
  threshold_sats: 5000,
  topup_sats: 20000,
  tier: "pro",
});
const res = await fetch(url, {
  method: "POST",
  headers: { "Authorization": nostrAuth("POST", url, body), "Content-Type": "application/json" },
  body,
});
console.log(await res.json());

Rid di setins

GET https://nymbot.ai/api/v1/nwc-auto-topup — krayt.

I gi yu di seim objek di wan we yu bin konekt, wit connected: false an di oda fild dem null wen no wallet de konekt. Di koneksin strin de nɔ de kam bak.

cURL

URL=https://nymbot.ai/api/v1/nwc-auto-topup
curl "$URL" -H "Authorization: $(nostr_auth GET "$URL")"

Python

import requests

url = "https://nymbot.ai/api/v1/nwc-auto-topup"
print(requests.get(url, headers={"Authorization": nostr_auth("GET", url)}).json())

JavaScript

const url = "https://nymbot.ai/api/v1/nwc-auto-topup";
console.log(await (await fetch(url, { headers: { "Authorization": nostrAuth("GET", url) } })).json());

Diskonɛktin

DELETE https://nymbot.ai/api/v1/nwc-auto-topup/connection — krayt.

I go dif de kin connection string we i de kip. No mo top-up go de de. Fɔ bɛ sure, yu kin pan ɔlso revok de connection na yu wallet.

Ansa

{ "data": { "connected": false, "threshold_sats": null, "topup_sats": null, "tier": null, "last_topup_at": null, "last_topup_sats": null, "last_error": null } }

cURL

URL=https://nymbot.ai/api/v1/nwc-auto-topup/connection
curl -X DELETE "$URL" -H "Authorization: $(nostr_auth DELETE "$URL")"

Python

import requests

url = "https://nymbot.ai/api/v1/nwc-auto-topup/connection"
print(requests.delete(url, headers={"Authorization": nostr_auth("DELETE", url)}).json())

JavaScript

const url = "https://nymbot.ai/api/v1/nwc-auto-topup/connection";
const res = await fetch(url, { method: "DELETE", headers: { "Authorization": nostrAuth("DELETE", url) } });
console.log(await res.json());

Yu de pe per rikwest witout wan ki

Yuan fiks-prais end-pɔnt de kɔn pay fɔ wan rɪkwɛst at wan tɛm ɔva Lightning, wit no kī, no akɔnt ɛn no bælans: POST /images/generations, POST /images/edits, POST /videos, POST /audio/speech, POST /audio/transcriptions, POST /audio/translations ɛn POST /embeddings. Chat, Responses ɛn Messages ɔlwe nid wan ki. Wan rikwest we de keri wan ki de bil di balance de fɔm ɔlwe; di pepaymen flow de stat ɔnli wen no ki sen.

Nymbot de tok tu versin bilong di sem idea, frɔm wan backend: Lightning Labs' L402 (dem de aksept am pan in oul nem pan, LSAT) an di IETF draft Peyment HTTP otentikeeshin skim wit di lightning metod an charge Inten. Yuz di wan we yu klaiennd wan sabi.

Di challenge

Sen di rikwest wit no ting Authorization header. If e valid, nɔtin nɔ rɔn, ɛnd yu get 402 Payment Required wit an invoice fɔ di eksakt kɔst fɔ dat rikwes: di seim prais we wan ki wū pay, konvert ɛt 10 sats fɔ wan stanad kridit ɔ 100 sats fɔ wan Pro kridit ɛn raund ɛp tu wan hole sat (at lɔst 1 sat, ɛn at lɔst di 0.05 kridit minimɔm). Di rispons kɛri tri WWW-Authenticate difikultiz fɔ de sem invɔys:

HTTP/1.1 402 Payment Required
Content-Type: application/problem+json; charset=utf-8
Cache-Control: no-store
WWW-Authenticate: L402 macaroon="AgJC...", invoice="lnbc2370n1..."
WWW-Authenticate: LSAT macaroon="AgJC...", invoice="lnbc2370n1..."
WWW-Authenticate: Payment id="kM9x...", realm="nymbot", method="lightning", intent="charge",
    request="eyJhbW91bnQiOiIyMzciLC...", description="Nymbot API POST /images/generations (237 sats)",
    digest="sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:", expires="2026-09-30T12:15:00.000Z",
    opaque="eyJlbmRwb2ludCI6IlBPU1QgL2ltYWdlcy9nZW5lcmF0aW9ucyJ9"

{
  "type": "https://paymentauth.org/problems/payment-required",
  "title": "Payment Required",
  "status": 402,
  "detail": "This request costs 237 sats. Pay the Lightning invoice, then send the identical request again ...",
  "challengeId": "kM9x...",
  "amount_sats": 237,
  "invoice": "lnbc2370n1...",
  "payment_hash": "9db1370f...",
  "expires_at": "2026-09-30T12:15:00.000Z",
  "error": { "message": "This request costs 237 sats. ...", "type": "payment_required", "code": "payment_required", "param": null }
}

Di peyment request pamaeta na base64url JSON: {"amount":"237","currency":"sat","methodDetails":{"invoice":"lnbc...","network":"mainnet","paymentHash":"..."}}.

Wan chalinj de boun de ɛnd-pɔnt, de to de Content-Type (di media type di de, ɛn fɔ multipart, di boundary di de) ɛn fɔ di SHA-256 di ɛksakt body bytes we yu sen, ɛn ɛ de last 15 minit. Aftaw yu pe, sen di sem se fɔse raks kwin agin: de seim Content-Type an di sem JSON bytes, ɔ fɔ di multipart endpoints (/images/edits, /audio/transcriptions, /audio/translations) di sɛm multipart bodi wetin di sɛm boundary. Mɔst HTTP librari pilɔn wan nū baundri ɛfri taim dɛn ɛnkōd fɔm, so ɛnkōd ɛn wan ɛn sɛnd dɛn bayt fɔ ɔ fɔ tū.

Di adress ɔn de kin aks fɔ 30 challenge de minut (an IPv6 adress de kɔnt as in ful /64). Requests we di adress nɔ no kin de apitiɔn fɔ 10 de minut, ɛn de ɛn awl-in limit on di challenge Nymbot de gi ɔn ɔn di ɔl adress; wan request we dem bin rifyuz bifo ɔn di challenge de (fɔ ɛksampul, wit wan bodi we nɔ de kɔrɛkt JSON) nɔ de kɔnt fɔ di limit. Pas dat, di ansua na 429 wit Retry-After, we sen am bifo dem rida di bodi. Di paid endpoints we dem de kɔl witout di key o kredenshal di de kɔnt na di jeneral limit wetin na 120 unautentikeytid rikwes na wan minit fɔ ɛvri adres. Dɛm de check kredenshal bifo dem rida di bodi, ɛn wan rikwes we Content-Type no bi de application/json (o multipart/form-data fɔ di uploads) de rifyuz wit 415 an bɛfɔ dɛn ɔ nɔ ɛvə gi an invɔys.

D pris fɔ Embeddings de bɛs fɔ dɛn dɛstimet fɔ di tokens fɔ di inpot, witɔ wan 1.5× margin, kɔs di rili kɔnt ɔnli de kōno afta dɛn dɔn de, Yu pɛ fɔ di tokens we yu ɔnli yuz, ɛn di pɔsin we yu nɔ yuz fɔ di pɛmɛnt de kɔm bak as a gi baks tokun.

A de sɛnd di pèimɛnt

Pay di invoice wit any Lightning wallet. Di wallet go gi yu di preimage, 64 hex characters. Tɛn sen di sɛm rikwest wit wan di ɔda:

Wan request wetin yu pay fɔ, de ansa ɛksaktli lɛk wan wetin yu mek wit wan kɛ, ɛksɛpt se de... nymbot Objek no get balance fild: {"payment": "l402", "tier": "pro", "paid_sats": 237, "charged_sats": 237}, and nɔ de nɔmɔ X-Nymbot-Balance-Sats header. A di wan we de pay wit di Payment scheme de get wan Payment-Receipt hed (base64url JSON wit di challenge id, di pepaymen hash de as reference, status ɛn timestamp). Di pay-di paydi rekwest nɔ de kɔnek de to eni nym, so dɛm nɔ de shoap na di kwiiri atis.

cURL

BODY='{"model":"nano-banana","prompt":"a lighthouse at dusk","response_format":"b64_json"}'
URL=https://nymbot.ai/api/v1/images/generations

# 1. Get the challenge
CH=$(curl -s -D - -o /dev/null "$URL" -H "Content-Type: application/json" -d "$BODY" | grep -i '^www-authenticate: L402')
MAC=$(echo "$CH" | sed -E 's/.*macaroon="([^"]+)".*/\1/')
INVOICE=$(echo "$CH" | sed -E 's/.*invoice="([^"]+)".*/\1/')

# 2. Pay $INVOICE with your wallet and copy the preimage
PREIMAGE=...

# 3. Send the identical request with the credential
curl "$URL" -H "Content-Type: application/json" -H "Authorization: L402 $MAC:$PREIMAGE" -d "$BODY"

lnget

# lnget (Lightning Labs) pays L402 challenges from your own lnd node and retries for you
lnget -X POST -H "Content-Type: application/json" \
  -d '{"model":"nano-banana","prompt":"a lighthouse at dusk","response_format":"b64_json"}' \
  https://nymbot.ai/api/v1/images/generations

Python

import base64, json, re
import requests

url = "https://nymbot.ai/api/v1/images/generations"
body = json.dumps({"model": "nano-banana", "prompt": "a lighthouse at dusk", "response_format": "b64_json"}).encode()
headers = {"Content-Type": "application/json"}

challenge = requests.post(url, data=body, headers=headers)
assert challenge.status_code == 402
info = challenge.json()
print("Pay", info["amount_sats"], "sats:", info["invoice"])

preimage = pay_with_your_wallet(info["invoice"])  # 64 hex characters

# L402
mac = re.search(r'L402 macaroon="([^"]+)"', challenge.headers["WWW-Authenticate"]).group(1)
res = requests.post(url, data=body, headers={**headers, "Authorization": f"L402 {mac}:{preimage}"})
print(res.json()["nymbot"])

JavaScript

const url = "https://nymbot.ai/api/v1/images/generations";
const body = JSON.stringify({ model: "nano-banana", prompt: "a lighthouse at dusk", response_format: "b64_json" });
const headers = { "Content-Type": "application/json" };

const challenge = await fetch(url, { method: "POST", headers, body });
const www = challenge.headers.get("www-authenticate");

// The Payment scheme: echo every challenge parameter back with the preimage
const start = www.indexOf("Payment ");
const params = Object.fromEntries([...www.slice(start + 8).matchAll(/(\w+)="((?:[^"\\]|\\.)*)"/g)].map((m) => [m[1], m[2]]));
const { invoice } = JSON.parse(Buffer.from(params.request, "base64url").toString()).methodDetails;
const preimage = await payWithYourWallet(invoice);

const credential = Buffer.from(JSON.stringify({ challenge: params, payload: { preimage } })).toString("base64url");
const res = await fetch(url, { method: "POST", headers: { ...headers, Authorization: `Payment ${credential}` }, body });
console.log((await res.json()).nymbot, res.headers.get("payment-receipt"));

Klaien tink de na mppx wit Lightning metod handle de Payment challenge de-self; point dem na de endpoint and mek dem pay.

Vidio

A pait POST /videos ansua 202 boku we dem bin luk am gud, plus a status_url: GET I de witout eni ki for follow di wok. I don sign an e de wok for 24 hours, as long as di wok de de.

{
  "id": "vid_...",
  "status": "in_progress",
  "status_url": "https://nymbot.ai/api/v1/videos/vid_...?exp=1790000000&sig=...",
  "nymbot": {
    "payment": "l402", "tier": "pro", "paid_sats": 4800, "charged_sats": 4800,
    "refund_token": "REFUND-5E0B..."
  }
}

Kip di refund_token frɔm dis rispons: ɛt sho ɔnli hya. È ɛmti waɛl di vidio rɛndas (GET /api/v1/l402/refunds ansua "status": "pending"); if di render feyl unbilled, di pepay de go na am. Di status URL sho refund_sats fɔ wan job we dem dif mɔni fɔ, bɔt dem no gi di token, so fɔ shɔ di status URL nɔ de shɔ di dif mɔni. Fɔ mek di token fɔ check am de fiks wan job we fail we no bod bɔt de check am.

Moni we de kam bak

If wan paid rikuest feyl an di provayda bil Nymbot fɔ di atempt, de go kip di pemen an di eror go se dat, wit charged_sats, de fɔ di ɛkzaet de se fɔ wan kii rɪkwest. If e fɛl witout ɛn bɛl, de ɛrɔ kɛri wan gi baks tokun wetin yu pepay fɔ am:

{
  "error": {
    "message": "The image generator failed. Nothing was charged. Please try again. The 237 sats you paid are on refund token REFUND-...",
    "type": "api_error",
    "code": "upstream_error",
    "refund_token": "REFUND-0C15DBED145D59131BA70298A413ADEB3D9B9AB082C476EA70A5BD38FCA5DE6D",
    "refund_sats": 237,
    "refund_expires_at": "2026-10-30T12:00:00.000Z"
  }
}

Di part wei yu no jus dɔn kam bak de de na de sef we i go: if yu ask fɔ tu pikchə bɔt wan no bin kɔm bin bɛl, di saksɛs rɪspɔns de nymbot objek keri wan refund token fɔ di wan we de mi; wan transcription we di lɛŋθ nɔ bin de klia fɔ rid fɔst, dem go di prais fɔ di longest di fawl kɔd bin de (nɔ de ɛva mɔ di 30 minits), ɛn di difrɛns fɔ di tru lɛŋθ de kam bak as wan refund token; if e turn aut se e lɛng di 30 minits, dem go rifyuz am wit 413 an di hol pepayment kam bak. Embeddings rɛn wan wet di ɛstimetat kɛp bak. Wan fɛl vidio rɛfʌnd di tokin wet in sʌbmishɔn rɛtɔn.

Refund token na wan 256-bit kod we no get pattern. Nymbot onli de keep im hash, and e go expire afta telti de. E de hole sat balance, and yu kin:

• Pe wit am. Sɛn am Authorization: Bearer REFUND-… na ɛni di ɛndpɔnt di ɛbɔv (an OpenAI SDK de tek am as in API ki). Di prais de kam frɔm di tokɛn ɛn wetin de lɛft de stɛy na ɛn (refund_token_sats in de nymbot objek). Wan token we de worth lɔs pan di rikwest ansa 💡 402 refund_insufficient; wan feyl we nɔ bil put di sats bak na di sɛm tokin.
• Check am. GET /api/v1/l402/refunds wit de seim header rin-tɔn {"sats": 237, "status": "open", "expires_at": "..."}.
• Wan token de kin beta am na mos 60 tɛm de wan minit.
• Move am go na nym. Put am inna Tek gud bofis 🫱🏾‍🫲🏼 na de Nymbot app, ɔ kɔl POST /api/v1/l402/refunds/redeem wit wan Ridest wey don sign ɛn {"refund_token": "REFUND-...", "balance": "standard"} (o "pro"). Ol krediti go na di balance (10 sats fɔ ɔvan standard, 100 fɔ Pro); di sats we nɔ mek wan ful krediti de na di token fɔ API rekwest.

cURL

URL=https://nymbot.ai/api/v1/l402/refunds/redeem
BODY='{"refund_token":"REFUND-...","balance":"standard"}'
curl "$URL" \
  -H "Authorization: $(nostr_auth POST "$URL" "$BODY")" \
  -H "Content-Type: application/json" \
  -d "$BODY"

Ansa

{ "data": { "credited": 23, "tier": "standard", "balance_credits": 123, "remaining_sats": 7 } }