Motheo oa tsebo / Baetsi ba lenaneo

Balanse, litlatso le linotlolo

Hlahloba seo o nang le sona, tlatsetsa ka Lightning, tlatsetsa ka boitlahlelo ho tsoa ka wallet ea hau, bona hore mali a kofuohang ka mang, le laola lintlha (keys) ho tsoa ka khoutu.

Leqephe lena le fetoletsoe ka mochini hore le be bonolo. Phetolelo ea mantlha ea Senyesemane ke eona e sebetsang.

Ke hlahloba mofuta oa chelete e saleng

Libaka tsa lona tsohle, le hore na karolo e kae ea sechaba sa seseli sena e sebelisitsoeng.

GET https://nymbot.ai/api/v1/credits/balance — e hloka API key. POST ho sebetsa hape, bakeng sa bareki ba lebeletseng hoo.

balance Na li-balanse tse peli lia kopana ka di-dolare ka taeo ea Bitcoin ea hona joale, bakeng sa lisebelisoa tse lebelletseng palo e le 'ngoe (null (honaeba lebaloe le ke ke la baloa). Karolo e sele e ka har'a dikredite le sats, e leng tsela eo dibilansi di bolokehileng ka yona. key ho hlalosa senotlolo seo se botsotseng. Senotlolo se fihleng qetellong ea sona se ka ntse sa hlahloba bakala.

Karabo

{
  "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);

Mefuta ea tefo

O ka tlatsa joang, le meeli. Lightning ke mokhoa o le mong feela.

GET https://nymbot.ai/api/v1/topup/payment-methods — ha ho hloke kofutši.

Ho tlatsetsa ho tloha ho 10 ho isa ho 1,000,000 sats; ho tlatsetsa ha Pro ho tlameha ho reka kerekiti e le 'ngoe ea Pro ha least, kahoo ho qala ho 100 sats. Meeli ea dolar ea latela mosto ea Bitcoin. bulk_bonus e bontša khredit e eketsehileng liponahanong tse kholo tsa ho tlatsa, joalo ka ka har'a app: 10%, 15% kapa 20% e eketsehileng litlatso tsa tlhophiso tse tsamaelang le 500, 1,000 kapa 5,000 sats, le litlatso tsa Pro tse tsamaelang le 5,000, 10,000 kapa 50,000 sats.

Karabo

{
  "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);

Ho tlatsetsa ka Lightning

Ethellele invoice ea Lightning e eketsang kerediti ho nym eo senotlolo e le belonging ho eona. E lefelle ho tsoa lefetše lefe la Lightning wallet, ebe u itika ho etsa hore kredite e eketsoe

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

Kredite e tloaelehileng ke 10 sats mme kredite ea Pro ke 100 sats, e eketseletseng bohlefu bofe kapa bofe ba mofuta oa bulk; credits ho bolela hore koto ena e tla eketsa eng.

Karabo

{
  "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);

Ho hlahloba ho eketsa tšebeliso 📲

O botsa hore na fakture e lefetswe, mme ha e le jalo, o eketsa boleng ba tebelo. Ho hlahloba ke ntho e e fang boleng ba tebelo, kahoo ka mor'a ho lefa, hlahloba ho fihlela boemo ba hore creditedHo hlahloba hape ka mor'a nako ke ntho e bolokehileng: khrediti e fihla hang feela, le ha e le hore na u e kopile makalo a mangata hakae.

GET https://nymbot.ai/api/v1/topup/status/{invoice_id} — o hloka senotlolo ho nym e entseng invoice.

status ke pending (ha e sa lefu), paid (le duelitse, empa ha e sa eketsewa; le hlahlobe hape), credited (kotloloanong ea hau) kapa expired (ha e lefihlwe ka nako). Mafelo a dipalo a saletso a bakeng sa sehlopha seo invoice e tswelang pele ka sona.

Karabo

{
  "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);

Tšohlorguo ea nalane

Mola o le mong bakeng sa kopo e nngwe: e ne e le eng, ke mofuta ofe, litokene ke tse lingata hakae le hore na e bile le lefu le le kae. Lipotso kapa likarabo ha li boloiwa, kahoo ha ho khutlisoe letho. Mehlala e bolokwa ka matsatsi a 90, e ncha pele. Senotlolo se fihletseng leemo la sona se ka ntse sa bala nalane ea sona.

GET https://nymbot.ai/api/v1/queries/history — e hloka senotlolo sa API, se bonang litlhoko tsa sona ka bo sona, kapa pampiri e saennoeng ea kopo ho tloha lebitso la hao, le bonang sa chaves e nngwe le e nngwe.

Karabo

{
  "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);

Ho saena lipaki tsa akhaonto

Ho etsa, ho fetola le ho tima lintlha (keys), kakaretso ea akhaonto le ho tlatsetsa ka boiketsetso ha li hloke API key. Li hloka saenō (signature) e tsoang nym ea hau, kahoo key e tsoang ka sephiri e ka qeta chelete e fihlang leemong la eona empa e ke ke ea etsa key e nngwe kapa ea phahamisa leemo la eona.

App ena e etsa sena bakeng sa uena: ntho e nngwe le e nngwe ka har'a eona API leporofoto e sebelisa lintlha tsena. You only need this section to manage keys from your own code.

Signature ke ketsahalo ea Nostr ea mofuta oa 27235 (NIP-98), e rometsoeng e hlolehetsoe ka base64 ho Authorization moqala ka lentswe Nostr pele:

Taba

{
  "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 ke URL e feletseng ea kopo, e akaretsang query string, e le joalo ka ha e rometsoe.
• method ke mokhoa oa HTTP.
• payload ke SHA-256 ea mmele oa kopo o hloekileng, ka hex. E hlokahala ho POST le PATCH, 'me mmele oo o o romang o tlameha ho ba byte ka byte o le oona oo o o haseletseng.
• created_at ho lokela ho ba ka har'a metsotso e 60 ea waktu ea sekhala.
• Ketsahalo e nngwe le e nngwe e sebetsa hang feela, a GET e kenngiloe, kahoo header e nkilw nonce letafolle ka boleng bo akaretsang ka hona hoo lipaki li mabeli tse saentweng nakong e le nngwe e tšoanang li tla tsamaea ka tsela e fapaneng.
• Mmele oa kopo e saenoe o ka ba 64 KB feela, mme mmele o hloka Content-Type: application/json.

Ketso e lahlehileng e khutla 401 missing_nostr_auth; e entsoeng hampe, e fetišitsoeng hampe, e fetileng nako haholo, kapa bakeng sa URL, mokhoa kapa mmele o fapaneng e khutlisetsa invalid_nostr_auth, ka lebaka le le molaetseng; e sebelisitsoeng hape e khutla nostr_auth_replayed. API key e rometsoeng litseleng tsena e hanaoloa. Signature e hlahlobooa pele body e baloa, mme aro e nngwe le e nngwe e ka hloleha ka e 30 ka metsotso e le nngwe (aro ea IPv6 e baloa e le /64 eohle); ka mor'a moo e fumana 429 le / le hokahanya Retry-After.

Librowara li ka khona ho bitsa li-endpoint tsena feela ho tsoa litseliteng tsa Nymbot tsa bo eona (https://nymbot.ai, https://nymchat.app (le subdomains ea bona). Letshelele leetseng ho lefung lefe kapa lefe le lingoloa tse ling ha li fumane di-CORS headers, kahoo li ke ke tsa bala seo li fetisang. Likhoutu le lisebelisoa tsa tlhaho, tse sa romeng Origin, ha li amahale.

Lisebelisoa tsena li baka hlooho (header). Mehlala e latelang leqepheng lena e li sebelisa. Li bala senotlolo se thahaselletsoeng (secret key) ka hex ho tsoa NOSTR_SECRET_HEX; e e sebelisang cURL e sebelisa nak sesebelisoa sa command-line, se amohang nsec kapa hex key, le sha256sum (ho 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");
}

Kakaretso ea akhaonto

Se o lehlakorela la API la app le bontšang holimo: senotlolo sa hao sa sechaba, li-balance tsohle tse peli, hore na ho na le senotlolo se kae se se sebetsang (se sa hlakotsoe kapa se sa phele), le tlatsa ka boitšhabeli linako, kapa null ha server e sa ba fana ka tsona.

GET https://nymbot.ai/api/v1/account — o hloka pampiri e saennoeng ea kopo.

Karabo

{
  "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());

Ho laola lithupu

Lintlha tsa bofelo tse ka morao ho lenljha la lenaneo. Tsohle li hloka setshwantsho sa kopo se saenoe. Seli le leng le le leng le khutlisetsoa ka mokhoa ona, ka nako ea ISO 8601 le meroho ka sats:

Boleng ba sesebelisoa sa senotlolo

{
  "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 ho lekanela ho tseba senotlolo empa eseng ho se sebelisa. Senotlolo ka bo sona se khutletsoa hang feela, ha se entsoe.

Ho fana ka lethathamo la linaka

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

Karabo

{ "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);

Ho etsa senehe

POST https://nymbot.ai/api/v1/keys — saenoe. Liphetso 201.

Karabo (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);

Ho bala kata e le 'ngoe

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

Ho khutlisetsoa {"data": {…}} le object ea key, kapa 404 key_not_found haeba ha ho na kataana ea hao e nang le ID eo.

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

Ho fetola konokono

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

Romela efe kapa efe ea name, limit_sats, reset_period le expire_at, ka melao e tšoanang le ha ho nkuoa ntho e etsang senotlolo. null ho hlakola ntho e e tletseng: ha ho na thuso, ha ho na ho hloleha, ha ho na le nako e fela. Ho fetola nako ea ho hloleha ho qala nako e ncha ho tloha ho zero. Sefofane se tsoiloeng se ke ke sa fetoloa (400 key_revoked). E fana ka {"data": {…}} le sebōpuo se sehlonolo se nchafalitsoeng.

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

Ho hlakola konokono

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

E emisa konota hang-hang, ka ho sa khutlela. E lula lenaong le nang le revoked_at bebeletsoe, mme e ka bonoa le include_revoked=trueHo tima konokono e se e tima ho fana ka karabo e le 'ngoe. Ke likonokono tse tima tse 50 tsa morao-rao feela tse bolokehang; tse khale li hlakolwa ha konokono e nngwe e tima.

Karabo

{ "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 auto-top-up

Kobanya Lightning wallet ka Nostr Wallet Connect mme Nymbot e eketsa chelete ka boona e le hore e se ke ea fela ha nako ea ho sebelisa API e fokola. Phaele ea API ea app e na le lisebelisoa tse tšoanang; tsena ke lisebelisoa tsa bohlokoa tse ka morao. Tsohle li hloka pampiri e saennoeng ea kopo.

Mosebetsi oa o jwang: ka mor'a hore kopo ea API e hloelele ka ntho e khetiloeng ho e shebella, haeba ntho eo e ile ea feta tlase ho ntlha ea hao, Nymbot e etsa ntho ea kofisa (invoice) bakeng sa ntho eo u e tlatsetsang, e kopa wallet ea hao hore e le felise, 'me e eketse kofiso. E tlatsetsa hang feela ka hara metsotso e 5 ho latela nym le ntho e itseng, kahoo ntho ea likopo tse ntle e ke ke ea tlohela wallet e se na letho. Ho senya ka har'a lioapp ha se hloelele ntho ena. Nako le boholo ba tlatsetso la ho qetela, le phoso ea ho qetela, li fumaneha settings; haeba tekofiso e ile ea phethahala ka mor'a phoso, ho hlahloba invoice ea eona ka boemo ba ho tlatsetsa kgethollo ea tsona.

Ho hokahanya wallet

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

Karabo

{
  "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());

Ho bala lisebelisoa

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

E fana ka objekti e le eona efe joalo ka ho hokahanya, ka connected: false le mafelo a mangwe null ha ho na wallet e hokonyehileng. String ea tlhophiso ka boona ha e ke ea khutlisoa.

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());

Ke ntse ke tloha

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

Ho tlosa lereo la tlamo le bolailoe. Ha ho sa etsoa tlhophiso tse ling tsa ho kenya chelete. Ho tiisa, u ka nna ua nka tlamo eo ka ho e hlakola mokotleng oa hau.

Karabo

{ "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());

Ho lefa ka mosebetsi kaofela ntle le senotlolo

Lintlha-motheo tsa tefo e tšoaneng li ka lefelwa ka kopo e le e nngwe ka nako ka Lightning, ntle le konokono, ntle le akhaonto le ntle le mofuta oa chelete: POST /images/generations, POST /images/edits, POST /videos, POST /audio/speech, POST /audio/transcriptions, POST /audio/translations le POST /embeddings. Lipuisano, Liphetho le Melaetsa ka nako tsohle li hloka senotlolo. Pang e nang le senotlolo e nkoatsoa ho pawalo joalo ka mofuta o tloaelehileng; tsela ya tefo e qala feela ha ho se rometswe senotlolo.

Nymbot o bua mefuta e 'meli ea ntho e le 'ngoe, e tsoa backend e le 'ngoe: Lightning Labs' L402 (me amohela le ka lebitso la lona la khale, LSAT) le mookotaba oa IETF Tealerofisō Moralo oa tlhahlobo ea HTTP le ea lightning mokhoa le charge sepheo. Sebelisa efe kapa efe eo moreki oa hau a e utloisisang.

Tlhaji

Romela kopo ntle le Authorization header. Ha e ne e le e nepahetseng, ha ho khetisoe ntho, mme o fumana 402 Payment Required ka invoice bakeng sa se se khetlohang ka botlalo: prise e le 'ngoe eo key e ka e lefhelang ka eona, e fetolehileng ka 10 sats ho credit ea mantlha kapa 100 sats ho Pro credit mme e ruloletsoe holimo ho sat e tletseng (haholo-holo 1 sat, le ka ho tala minimum ea 0.05 credit). Karabo e na le tse tharo WWW-Authenticate mathata bakeng sa invoice e le 'ngoe:

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 }
}

Mefuohlelo request parameter ke base64url JSON: {"amount":"237","currency":"sat","methodDetails":{"invoice":"lnbc...","network":"mainnet","paymentHash":"..."}}.

Liphephetso li amolohiloe qetellong, ho ea ho Content-Type (mofuta oa media le, bakeng sa multipart, lekhetho la lona) le ho SHA-256 ea bytes tsa mmele tseo u li rometseng ka ho nepahetseng, 'me eha 15 minpe. Ka mor'a ho lefa, romela ngofana kopela hape: e le 'ngoe Content-Type le dibaitse tseo tsa JSON tse tšoanang, kapa bakeng sa dintlha tsa multipart (/images/edits, /audio/transcriptions, /audio/translations) mono mofuta ofe kapa ofe o mong oa multipart o sebelisang boundary e le nngwe. Libuka tse ngata tsa HTTP li khetha boundary e ncha nako le nako ha li nka mokhoa oa ho encode form, kahoo e encode hang feela mme o romelle bytes tseo ka makgetlo a mabeli.

Aporo e nngwe le e nngwe e ka kopa lipapali tsa 30 ka metsotso e le nngwe (aporo ea IPv6 e baloa e le /64 ea yona kaofela). Litlhoko tse nang le aporo e sa tsejoeng li arola karolo e nngwe e qatellang ea 10 ka metsotso e le nngwe, hape ho na le phahamiso ea kakaretso lipapaling tseo Nymbot e li fang aporo tsohle; kopo e hana e le nngwe pele papali e etsoa (mohlala, ka mmele oa JSON o sa lulang hantle) ha e arolele karolo ho eona. Ho feta moo karabo ke 429 le / le hokahanya Retry-After, e rometsoe pele mmele o balwa. Lintlha tsa mosebetsi tse sebelisitsoeng ntle le konokono kapa litokomane tsa bohlokoa le tsona li akaretsa kapa li kenyelletsa har'a thuso e akaretsang ea 120 lipaki tseo li sa tšepahalang ka metsotso e le 'ngoe ka address e le 'ngoe. Tokomane e hlahloboa pele mmele o balwa, 'me kopo e nang le Content-Type ha se application/json (kapa multipart/form-data bakeng sa li-upload) e hana ka 415 'mele o sa fumane invoice.

Litšobotsi tsa Embeddings li tšepetsoe ka akanyetso ea litemana (tokens) tse ka har'a mooko, ka mosebetsi oa 1.5× margin, hobane palo ea nnete e tsejoa feela ka mor'a nako. U lefa ka litemana tse sebelisitsoeng ha e le thusa, 'me karolo e sa sebelisetsoeng ea tefo e khutlisetsoa ho uena e le a Tokene ea khutlisetso.

Ke romela tefo

Robetsa invoice ka wallet efe kapa efe ea Lightning. Wallet e tla u fa preimage, ke litemana tsa hex tse 64. Etsaneng kapa u romele pitso e tšoanang ka e ’ngoe ea tsena:

Kopo e lefuoeng e araba ka tsela e tšoanang le e entsoeng ka senotlolo, ntle le hore nymbot object ha e na mafelo a pehelo: {"payment": "l402", "tier": "pro", "paid_sats": 237, "charged_sats": 237}, ha ho letho X-Nymbot-Balance-Sats setlhaku. A pajament e lefetsweng ka mokhoa wa Payment scheme e fumana Payment-Receipt header (base64url JSON e nang le id ea challenge, hash ea tefo jwalokaha reference, status le timestamp). Litlhoko tsa tebelo ha li amane le nym efe kapa efe, kahoo ha li tlatse ka nalane ea lipotso.

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"));

Bareki ba hahiloe holim'a mppx ba sebelisa mokhoa oa Lightning ho rarolla qoso ea Tefo baphone ba bona ho endpoint mme ba tlohele ba lefe.

Livideo

E lefutiloeng POST /videos karabo 202 joaloka ea nang le lenaka, ho eketsehileng a status_url: GET ntle le sesakili se se latelang mosebetsi. Se saenitsoe mme se sebetsa ka dihora tse 24, haeba mosebetsi o ntse o hlokomelletsoe.

{
  "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..."
  }
}

Boloka refund_token ho tloha karabelong ena: e bontšoa mona feela. E le sefahloeng ha video e ntse e eha (GET /api/v1/l402/refunds karabo "status": "pending"); haeba ho hlahloha ho sa tsoa lula ho sa lefuoa, tefo e tla ea ho sona. URL ea boemo e bontša refund_sats bakeng sa mosebetsi o khutlisitsoeng empa token ha e tšoaroe, kahoo ho arolelana URL ea boemo ha ho arolelane khutlisetso. Ho hlahloba token ho rarolla mosebetsi o hlolehileng oo motho e mong le e mong a sa o hlahlobang.

Ho khutlisetsoa chelete

Ha kopo e lefilo e hloleha mme mofahi a lefile Nymbot bakeng sa boितlo, tefo e bolokehiloe mme phoso e bolela jalo, ka charged_sats, ka ho nepahetso joalo ka bakeng sa kopo e nang le lentho. Ha e hlōle ntle le hore e bokelloe tefo, phoso e na le Tokene ea khutlisetso ho lekela seo u se lefutileng:

{
  "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"
  }
}

Likarolo tse sa sebelisetsoeng li khutla ka tsela e tšoanang: haeba u kile ua kopa litšoantšo tse peli 'me e le 'ngoe ea hofoloa e sa lefishoang, karabo ea katleho ea nymbot selo se tsamaea le letshwao la ho khutlisetsa chelete bakeng sa se sa le teng; taelo ea ho ngola e lebelang e neng e ke ke ea baloa pele e ne e lekolloa ka nako e telele ka ho fetisisa e le hore e ka ba (e sa feta metsotso e 30), le phapang pakeng tsa nako ea nnete le e ne e lekolloa e khutlisetsoa ka letshwao la ho khutlisetsa chelete; haeba ho hlahlamoha hore e le telele ho feta metsotso e 30, e hana e le ka 413 mme tefo eohle e khutla. Embeddings li khutlisetsa seo akanyetso e neng e se tšoaretse. Video e hlolehileng e khutlisetsa token eo submission ea eohle e ilela ho e khutlisetsa.

Token ea phetheloho ke khoutu e akaretsang 256-bit e sa tloaeleheng. Nymbot e boloka hash ea eona feela, mme e fela ka mor'a matsatsi a 30. E na le balance ea sat, mme u ka:

• E felise ka yona. Romela Authorization: Bearer REFUND-… ho efe kapa efe ea li-endpoint tse ka holimo (OpenAI SDK e e amohela e le sesebelisoa sa API sa eona). Ntlha e tsoa ho token mme se setseng se lula ho eona (refund_token_sats ka hara nymbot (object). Letšoana le le nang le boleng bo fokang se kopo se arabang le lona 402 refund_insufficient; ho hloleha ho sa lefisho ho khutlisetsa sats tsebeng e tšoanang.
• E hlahlobe. GET /api/v1/l402/refunds ka hlooho e le nngwe boitšobodutso {"sats": 237, "status": "open", "expires_at": "..."}.
• Token e le 'ngoe e ka sebelisoa makgetlo a 60 feela ka metsotso e le 'ngoe.
• Tsamaisa ho nym. E tsenye ka har'a Fetola mpho ka hara app ea Nymbot, kapa u letše POST /api/v1/l402/refunds/redeem ka pampiri e saennoeng ea kopo le {"refund_token": "REFUND-...", "balance": "standard"} (kapa "pro"). Dikrethe tse tletseng li ea balansi (sats tse 10 kae le kae holim'a standard, 100 holim'a Pro); sats tse hloelang ho etsa krethe e tletseng li sala holim'a token bakeng sa API requests.

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"

Karabo

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