Fa'avae poto / Atia'i Fausiaina

Toteniga, fa'atumu, ma ki

Siaki lau mea o iai, fa'aalu le Lightning mo le fa'aopoopo, fa'aopoopo otometi mai lau lava pusa tupe, va'ai le tau o fa'asologa ta'itasi, ma pulea mai le kōdu.

O lenei itulau ua fa'aliliuina i masini mo le fa'afaigofieina. O le ulua'i fa'a-Peretania o le fa'amatalaga lea e fa'atatau.

Siakiina le tupe o lo'o iai

O au tupe fa'aopoopo uma, ma le tele o le fua o lenei ki ua fa'aaogāina.

GET https://nymbot.ai/api/v1/credits/balance — e mana'omia se API key. POST e galue foi, mo tagata faatau o lo'o fa'amoemoe i ai.

balance pe o le lua tau falafala o lo'o fa'atasi i tausaga i le tau o le Bitcoin i le taimi nei, mo meafaigaluega e mana'omia ai se tasi numera (null afai e le mafai ona faitau le tau). O le totoe o lo'o i ai credits ma sats, o le auala moni lea e teu ai tupe. key faamatala le ki na fesili atu. O se ki ua o'o i lona limit e mafai lava ona siaki le totogi.

Aiga

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

Faiga totogi

Fa'afefea ona e fa'atumuina, ma ia fa'atapula'a. O le Lightning o le auala lava e tasi.

GET https://nymbot.ai/api/v1/topup/payment-methods — e le mana'omia se ki.

O se fa'atumu e 10 i le 1,000,000 sats; o se fa'atumu Pro e tatau ona fa'atau i le aua o le tasi fa'amau Pro, o lea e amata i le 100 sats. O fa'atapula'a o le dola e mulimuli i le tau o le Bitcoin. bulk_bonus O lo'o lisiina ai le tupe faaopoopo i totonu o ni tupe faaopoopo e sili atu, e tutusa ma le apa i le app: 10%, 15% po o le 20% faaopoopo i tupe faaopoopo masani mai le 500, 1,000 po o le 5,000 sats, ma i tupe faaopoopo Pro mai le 5,000, 10,000 po o le 50,000 sats.

Aiga

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

Fa'atumu i luga o le Lightning

Faia se Lightning invoice e fa'aopoopo ai le tupe (credit) i le nym o lo'o iai le ki. Totogi mai i so'o se Lightning wallet, ona siaki ina ia fa'aopoopo ai le tupe fa'asao.

POST https://nymbot.ai/api/v1/topup/create/btc-lightning — e mana'omia se API key.

O se tupe faʻastandard o le 10 sats ma se tupe Pro o le 100 sats, faʻapea soʻo se faʻaopoopo mo le faʻatau tele; credits ole a mea o le a faaopoopoina e lenei invoice.

Aiga

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

Toe va'ai i se fa'alauiloaga o tupe

Fai atu pe ua totogi le invoice ma, pe a uma ona totogi, faaopoopo le credit. O le siakiina o le mea e faaopoopo ai le credit, o lea pe a uma ona totogi, siaki seia oʻo i le tulaga o le credited. O le toe siakiina fai i lona mulimuli e saogalemu: e tasi lava le taimi e maua ai le tupe, e tusa lava po o āfea e fai ai lau talosaga.

GET https://nymbot.ai/api/v1/topup/status/{invoice_id} — e mana'omia se ki mai le nym na fai ai le invoice.

status o lo'o pending (le totogiina anei), paid (solia, ae le'i maua le tupe; toe siaki fa'again), credited (i lau tupe i totonu) poʻo expired (lē totogiina i le taimi tonu). O vaega o le tau o loʻo mo le tulaga o loʻo faʻatumuina ai le invoice.

Aiga

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

Talafaasolopito o fesili

Lau tasi mo le talosaga: o le mea na fai, le ituaiga masini, le faitau o tokens ma lona tau. E le teuina ni fesili po'o ni tali, o lea e le toe fa'afo'i mai se mea lava. O lenei lisi e teuina mo le 90 aso, o mea fou e muamua. O se ki ua o'o i lona tapete e mafai lava ona faitau lona talafaasolopito.

GET https://nymbot.ai/api/v1/queries/history — e mana'omia se API key, lea e va'ai i ana lava talosaga, pe a talosaga ua saini mai lau nym, o lo o vaai i le ki a soo se tasi.

Aiga

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

Faatumuina o talosaga mo teugatupe

O le faia, suia ma le aveesea o ki, le lisi o tala, ma le faaopoopoina o tupe otometi e le manaomia se ki API. E manaomia se saunia (signature) mai lau nym, o lea e mafai e se ki ua faalavelave ona faaalu e oo i lona tapulaa, ae e le mafai lava ona faia se isi ki pe a faateleina lona tapulaa.

O lo'o faia e le polokalame lenei mo oe: mea uma i lona... API o le pepa e fa'aaogā nei endpoint. E na'o lenei vaega e te mana'omia e pulea ai ki mai lau lava kōdu.

O le saunia o le sootaga o se mea e aofia ai le Nostr event o le ituaiga 27235 (NIP-98), lea e lafoina i le faiga o le base64-encoded i le Authorization ulutala ma le upu Nostr i luma:

Le mea faia

{
  "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 o le URL atoa o le talosaga, e aofia ai le query string, e tutusa lava ma le lafoina.
• method o le faiga HTTP.
• payload o le SHA-256 o le raw request body, i le hex. E mana'omia i luga o POST ma PATCH, ma o le tino o mea e te auina atu e tatau lava ona tutusa le byte i le byte ma le mea na e fa'aaogāina ai le hash.
• created_at e tatau lava ona i totonu o le 60 sekone mai le taimi o le server.
• O mea uma e galue fa'apea lava e tasi, a GET ua aofia atu, ina ia le mafai ona toe fa'aaogā se header ua fa'amaumauina. Fa'amau se tasi fou mo masini ta'itasi. Fa'aopoopo i se nonce fa'ailoga ma se tau o iai se mea e lē mafaia ona silasila ina ia eseese lava lava lua talosaga na fa'amautu i le lava sekone e tasi.
• O le tino o se talosaga ua sainia e mafai ona e oo atu i le 64 KB i le tele, ma o le tino e manaomia Content-Type: application/json.

O se mea e leai se mea ua toe fo'i mai 401 missing_nostr_auth; o se tasi e leaga le fausia, leaga le faamamafa, matua tuai, pe mo se URL, faiga po o se tino eseese e toe foai mai invalid_nostr_auth, ma le mafuaaga i totonu o le feau; o se mea ua toe faaaogā e toe fo'i mai nostr_auth_replayed. E lē taliaina se API key e lafo atu i nei fa'amau (endpoints). E siaki le fa'ailoga (signature) a'o le'i faitauina le vaega o le fe'au (body), ma o le ala (address) ta'itasi e mafai ona sese ai i lenei mea i le 30 taimi i se minute (o se ala IPv6 e i ai lona /64 atoa); a'o mulimuli ane e maua 429 tau Retry-After.

E mafai e numera o upega tafa'ilagi (browsers) ona valaauina nei endpoint na'o mai upega tafa'ilagi a Nymbot lava ia (https://nymbot.ai, https://nymchat.app (ma a latou subdomains). O se itulau i so o se isi upega tafa'ilagi e le maua ni CORS headers toe fo'i mai, o lea e le mafai ona faitau mea ua latou toe fo'i mai. O script ma apps masani, o nei e le laai e auina atu Origin, e le o aafia.

O nei fesoasoani e fausia ai le ulu. O faʻataʻitaʻiga mulimuli i lenei lauga e faʻaaogā i ai i latou. Latou te faitauina le ki lilo i le hex mai NOSTR_SECRET_HEX; o le mea cURL e fa'aaogaina le nak meafaigaluega i le polokalame, o lo'o maua se key nsec po'o se hex, ma sha256sum (i luga o 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");
}

Le otootoga o le akauntī

O le mea o lo'o fa'aalia i le pito i luga o le pepa API a le polokalame: lau pūpū lautele (public key), tulaga o tupe uma e lua, le faitau o ki o lo'o galue (e lē fa'aleaogaina pe ua uma le vaitaimi), ma le fa'auto top-up fa'atulagaga, pe null pe a le ofoina atu e le server ia i ai.

GET https://nymbot.ai/api/v1/account — e manaʻomia se talosaga ua saini.

Aiga

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

Fa'atautaia moli

O endpoints o lo'o i tua o le lisi o ki a le polokalame. E mana'omia i latou uma se fa'amauina talosaga. O kono uma e toe fo'i mai i lenei tulaga, ma taimi i le ISO 8601 ma tupe i le sats:

Mea autu

{
  "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 lava e iloa se ki ae le o se mea e faaaogā ai. O le ki lava e toe foai atu only once, when it is made.

O le lisiina o ki

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

Aiga

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

Faitauina o se ki

POST https://nymbot.ai/api/v1/keys — sautaʻiina. Foia 201.

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

Faitau o se ki autū

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

Toe faafoi {"data": {…}} ma le mea o le ki, po o 404 key_not_found afai e leai se ki lau e iai lena 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);

Suia o se ki

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

Auina mai so'o se tasi o name, limit_sats, reset_period ma expire_at, ma ia tutusa tulafono pe a faitau se ki. null faamamāina se ata: e leai se limitiga, e leai se toe faasetuluga, e leai se vā o le faamaumauina. O le suia o le vā o le toe faasetuluga e amata ai se vā fou i le zero. O se ki ua aveeseina e le mafai ona suia (400 key_revoked). Toe fo'i mai {"data": {…}} ma le mea o loʻo faʻafouina le object o le ki.

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

Fa'aleaogaina o se ki

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

Taofi le ki i le taimi lava e tasi, mo le faavavau. E tumau pea i le lisi faatasi ma revoked_at fa'atulaga, ma e mafai ona va'aia ma include_revoked=trueO le fa'aleaogaina o se ki ua uma ona fa'aleaogaina e tali mai i le ala tutusa. Na'o ki uma lava 50 ua uma ona fa'aleaogaina e teuina; o ki tuai e tapeina pe a fa'aleaogaina se isi ki.

Aiga

{ "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 fa'autasi-fa'atumu

Fa'afeso'ota'i se Lightning wallet ma le Nostr Wallet Connect ma o le a fa'atumu e le Nymbot lava ia le totogi pe a pasi atu le tulaga o le fa'aaluina o le API. O le pepa API o le polokalame o lo'o iai ai fa'atulagaga tutusa; o nei o endpoints o lo'o i tua atu. E mana'omia i la latou uma se talosaga ua saini.

Fa'afefea ona galue: pe a uma ona totogi se talosaga API mai le tauvaga na e filifilia e va'ai i ai, afai ua pa'u lea tauvaga i lalo o lau tulaga fa'atatau, o lo'o faia e Nymbot se invoice mo le vaega o le toe fa'aolaola o le tupe, e talosaga i lau wallet e totogi ai, ma fa'aopoopo le tupe. E toe fa'aolaola i le tele o le taimi e tasi i le 5 minute mo taimi uma nym ma le tauvaga, ina ia ne'i mafai ona fa'amaumauina le wallet e i le tele o talosaga fa'afuase'i. O le fa'aaluina o tupe i totonu o polokalame e le taua ai lenei faiga. O le taimi ma le tele o le toe fa'aolaola na fai muamua, fa'apea le mea na sese, o lo'o i totonu o tulaga fa'atulaga; afai ua māua se totogi ina ua uma se mea na sese, ia siakiina le invoice milo ma le tulaga o le fa'aigoaina o tupe fa'asolo i ai ana tulaga fa'aletulafono.

Feso'ota'i mai se wallet

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

Aiga

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

Faitauina o faasologa

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

Toe fo'i mai le lava lava o le object lava e pei o le connecting, ma connected: false ma isi vaega foofo null Pe a leai se wallet ua kếtetia. O le lava lava o le connection string e le toe toe fo'i mai.

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

O lo'o tapuni le feso'ota'iga

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

Elimia le fa'akonega (connection string) ua teuina. E leai ni isi toe fa'atumu e fai. Ina ia mautinoa, e mafai fo'i ona fa'aleaogaina le fa'akonega i lau wallet.

Aiga

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

Totogi i le talosaga ta'itasi e aunoa ma se ki

O fuafuaga o le tau fa'asao e mafai ona totogi ai mo le tasi talosaga i le taimi e tasi e ala i le Lightning, e aunoa ma se ki, e aunoa ma se aka운t ma se totogi i luma: POST /images/generations, POST /images/edits, POST /videos, POST /audio/speech, POST /audio/transcriptions, POST /audio/translations ma POST /embeddingsE mana'omia pea se ki mo Chat, Tali (Responses) ma Feau (Messages). O se talosaga o lo'o iai se ki e totogi e tusa ai ma le masani; e amata lava le faagasologa o le totogi pe a leai se ki ua lafoina.

O lo'o tautala Nymbot i ni fa'ata'itai lua o le lava lava manatu, mai se backend e tasi: Lightning Labs' L402 (fa'apea fo'i ona talia i lona igoa tuai, LSAT) ma le fuafuaga a le IETF Totogi Faiga fa'atulagaina o le fa'amaoni'i o HTTP ma le lightning faiga ma charge fa'amoemoe. Fa'aaoga le mea lava e malamalama ai lau tagata fa'atau.

O le fa'afitauli

Lafo le talosaga e aunoa ma se mea Authorization ulutala. Afai e sa'o, e leai se mea e fa'atinoina, ma e maua oe i 402 Payment Required ma se invoice mo le sa'o o le tau o lena talosaga: le tau tutusa e totogi ai se key, ua suia i le 10 sats mo se credit masani po'o le 100 sats mo se Pro credit ma fa'atupula'ia i se sat atoa (lua le 1 sat, ma lua le 0.05 credit minimum). O le fa'asilasilaga e iai ni tiga WWW-Authenticate avega mo le lava lava pepa fa'asolopito:

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

Le Totogi request o le parameter o se base64url JSON: {"amount":"237","currency":"sat","methodDetails":{"invoice":"lnbc...","network":"mainnet","paymentHash":"..."}}.

O se faigata o lo'o fa'atali i le matafo'i, i le Content-Type (o lona ituaiga media ma, mo multipart, lona boundary) ma le SHA-256 o bytes o le tino tonu na e lafoina, ma tumau pea mo le 15 mineti. A mae'a le totogiina, lafo le fa'atofutofu toe talosaga: e tutusa le mea Content-Type ma le lava fa'ifai o bytes JSON, pe mo vaega multipart endpoints (/images/edits, /audio/transcriptions, /audio/translations) le lava tutusa o le tino multipart ma le tutusa o le boundary. O le tele o tuʻutuʻuga HTTP e filifili ai se boundary fou i taimi uma e faʻamaopopo ai se foma, o le mea lea faʻamaopopo i luga o se taimi e uma ai ona lafo atu ia bytes e lua.

O lea lava tulaga e mafai ona talosaga mo ni fa'aaliga e 30 i le minute (o se tulaga IPv6 e i ai lona /64 atoa). O talosaga e le iloa le tulaga e mafai ona maua ai se fa'aletonu fa'apitoa e 10 i le minute, ma ia iai se tapu i le taua o fa'aaliga o lo'o tu'uina atu e le Nymbot i luga o tulaga uma; o se talosaga ua lē taliaina a o le'i tu'uina atu se fa'aaliga (mo se fa'ata'ita'iga, ma se tino e lē sa'o le JSON) e lē aofia i ai. I luga o lena, o le tali o le 429 tau Retry-After, lafo ahi ae le'i faitauina le isi o tala. O endpoints fa'aaogāina e aunoa ma se ki po'o se fa'amaoni (credential) e aofia atu fo'i i le tulaga masani o le 120 talosaga e aunoa ma se fa'amaoni i le minute mo ipu (address) ta'itasi. E siakiina se fa'amaoni a'o le'i faitauina le isi o tala, ma se talosaga o loo Content-Type e lē application/json (poʻo multipart/form-data mo suʻuina o mea (uploads) ua lē taliaina ma 415 ma e lē maua lava se invoice.

O le tau o fa'aopoopoina (Embeddings) e fa'avae i se fuainumera e fa'atatau i le aofa'i o fa'ailoga (tokens) i totonu o le fa'amaumauga o lo'o fa'aaogāina, ma se fa'atupula'ia e 1.5×, ona e iloa tonu le aofa'i moni ae uma ona faia le galuega. E totogi oe mo fa'ailoga ua fa'aaogā moni, ma le vaega o le totogi ua fa'aalu e le'i fa'aaogāina e toe fo'i mai e pei o se toe foi le tupe o le token.

O lo'o auina atu le totogi

Totogi le invoice i so'o se Lightning wallet. O le wallet o le a tu'uina atu ia te oe le preimage, 64 hex characters. O nisi nei e lafo ai le fa'asologa tutusa:

O se talosaga totogi e tali tonu lava pei o se tasi na fai i se ki, peita'i o le nymbot e leai ni vaega o le tupe i le object: {"payment": "l402", "tier": "pro", "paid_sats": 237, "charged_sats": 237}, ma e leai se X-Nymbot-Balance-Sats ulutala. O se talosaga totogi i le faiga Totogi e maua fo'i se Payment-Receipt ulu (base64url JSON ma le challenge id, le payment hash e pei o reference, status ma timestamp). E lē fa'atali talosaga totogi i so'o se nym, o lea e lē fa'aalia i le talosaga o tala i le lisi.

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

Tagata faatau fausia i luga o mppx ma se faiga Lightning, ia latou lava e faia le fa'afitauli o le Totogi; ave i ai i le endpoint ma ia latou totogi.

Vitio

Se totogiina POST /videos tali 202 pei o se tasi ua fa'ataga, fa'apea se status_url: GET e aunoa ma se ki e mulimulita'i ai i le galuega. Ua saini ma e galue mo le 24 patū o le aso, solia lava e te tausia le galuega.

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

Taofia le refund_token mai lenei tali: o lo'o fa'aalia atu lava iinei. E mamā i le taimi lava e tufa ai le vitio (GET /api/v1/l402/refunds tali "status": "pending"); afai e le manuia le fa'atinoina o le unbilled, o le totogi e fa'atupulaia ai lena mea. O le URL o le tulaga o lo'o fa'aalia ai refund_sats mo se galuega ua toe foi atu le totogi ae le'i maua le token, o le fa'asoa atu o le URL o le tulaga o lo'o faia ai e le'i fa'asoa atu ai le toe foi atu o le totogi. O le siakiina o le token e fa'atulaga ai fo'i se galuega ua pegata e le'i su'esu'eina e se tasi.

Toe foi tupe

Afai e le manuia se talosaga totogi ma siitia e le pulega le tau o le taumafaiga i Nymbot, e taofia le totogi ma e fa'ailoa mai le mea sese, ma le charged_sats, e pei lava o se talosaga ua fa'afeso'ota'i. Afai e le manuia ae a le totogia, o le mea sese e iai se toe foi le tupe o le token tau manaia i le tau na e totogia:

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

O vaega e leʻi faʻaaogaina e toe foʻi mai i le lava lava faʻapea: afai na e talosaga mo ata e lua ae o le tasi na le manuia ma le leʻi totogia, o le tali manuia o le nymbot o le mea o lo'o iai se token toe fo'i mai mo le mea ua leai; o se tusi fa'aliliu e le mafai ona faitau ai lona umi i luma, o le a totogi i le umi sili lea e mafai ona i ai le failauga (e lē tele atu i le 30 minute), ma o le eseesega i le umi moni o le a toe fo'i mai i le tulaga o se token toe fo'i mai; afai e sili atu le umi i le 30 minute, o le a lē fa'amaoni ma fa'atali ma 413 ā ina toe fo'i mai le totogi atoa. O Embeddings e toe fo'i mai mea na taofia e le fuainumera o le tau. O se vitiō ua le manuia e toe fo'i atu le token na toe fo'i mai ai lona tu'uina atu.

O se token toe foi tupe o se kōdu 256-bit e lē mautu. O lo'o teuina e le Nymbot na'o lona hash, ma e mae'a lona aoga i le 30 asu. E iai lona totogi sat, ma e mafai ona e:

• Fa'aoga e totogi ai. Auina atu Authorization: Bearer REFUND-… i luga o so'o tasi o endpoints i luga nei (e taina e se OpenAI SDK o lona API key). O le tau e aveese mai i le token ma mea e totoe e tumau pea i ai (refund_token_sats i totonu o le nymbot oboject). O se tusi e tauena lalo ifo i le talosaga tali 402 refund_insufficient; o se lamatia e leʻi totogia e toe faʻafoʻi ai sats i le lava lava failauga.
• Siaki le. GET /api/v1/l402/refunds ma le lava tutulu e tutusa mauaina {"sats": 237, "status": "open", "expires_at": "..."}.
• E mafai ona fa'aaogaina e tasi le token i le 60 vaitau i le miniti i le tele lava.
• Ave i se nym. Fa'apipi'i i loto i Fa'aaoga se meaalofa i le app o le Nymbot, po o le telefoni atu POST /api/v1/l402/refunds/redeem ma se talosaga ua saini ma {"refund_token": "REFUND-...", "balance": "standard"} (poʻo "pro"). O le fuafuaga atoa e aga'i atu i le totogi (10 sats ta'itasi i le standard, 100 i le Pro); o sats e le o atoatoa se fuafuaga e nofo pea i le token mo lu'itau o API.

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"

Aiga

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