Znalostná báza / Vývojári

Vyváženie, top-ups a kľúče

Skontrolujte, čo máte, prejdite cez Lightning, prejdite automaticky z vlastnej peňaženky, zistite, koľko stojí každá požiadavka a spravujte kľúče z kódu.

Táto stránka je pre pohodlie preložená strojovo. Platí anglický originál.

Skontrolujte rovnováhu

Obe vaše rovnováhy, a koľko z tohto kľúča kryt je použitý.

GET https://nymbot.ai/api/v1/credits/balance Potrebujete API kľúč. POST Funguje to aj pre zákazníkov, ktorí to očakávajú.

balance je dva zostatky spolu v dolároch pri súčasnej cene Bitcoin, pre nástroje, ktoré očakávajú jediné číslo (null zvyšok je v kreditoch a sadzbách, čo je spôsob, akým sa zostatok skutočne udržiava. key Kľúč, ktorý dosiahol svoj limit, môže stále skontrolovať zostatok.

odpoveď

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

Spôsoby platby

Ako môžete vrhnúť, a limity. blesk je jediná metóda.

GET https://nymbot.ai/api/v1/topup/payment-methods Kľúč nie je potrebný.

Top-up je 10 až 1.000.000 sats; Pro top-up musí kúpiť aspoň jeden Pro kredit, takže začína na 100 sats. bulk_bonus uvádza dodatočný kredit na väčšie top-upy, rovnaký ako v aplikácii: 10%, 15% alebo 20% viac na štandardné top-upy od 500, 1000 alebo 5000 sats a na Pro top-upy od 5000, 10.000 alebo 50 000 sats.

odpoveď

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

Stúpanie nad bleskom

Vytvára Lightning faktúru, ktorá pridáva kredit k nym kľúč patrí. zaplatiť z ľubovoľnej Lightning peňaženky, potom skontrolovať to Aby sme pridali úver.

POST https://nymbot.ai/api/v1/topup/create/btc-lightning Potrebujete API kľúč.

Štandardný kredit je 10 sats a Pro kredit 100 sats, plus akýkoľvek hromadný bonus; credits Hovorí o tom, čo táto faktúra prinesie.

odpoveď

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

Skontrolujte top-up

Pýta sa, či bola faktúra zaplatená a akonáhle ju má, pridáva kredit. Kontrola je to, čo ho kredituje, takže po zaplatení skontrolujte, kým stav nie je creditedOpäť skontrolovať neskôr je bezpečné: úver pristane raz, bez ohľadu na to, koľkokrát sa pýtate.

GET https://nymbot.ai/api/v1/topup/status/{invoice_id} - potrebuje kľúč od nym, ktorý vytvoril faktúru.

status je pending (Zatiaľ nie je platená) paid (platené, ale ešte nie kreditované; skontrolujte znova), credited (na vašej rovnováhe) alebo expired (nie je splatné včas). polia zostatku sú pre úroveň, na ktorej je faktúra vyššia.

odpoveď

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

Chcú históriu

Jeden riadok na žiadosť: čo to bolo, aký model, koľko tokenov a čo to stálo. Žiadne výzvy alebo odpovede nie sú uchovávané, takže žiadne nie sú vrátené. Rows sú uchovávané po dobu 90 dní, najnovšie najprv. Kľúč, ktorý dosiahol svoju hranicu, môže stále čítať svoju históriu.

GET https://nymbot.ai/api/v1/queries/history — potrebuje kľúč API, ktorý vidí vlastné požiadavky, alebo Podpísaná žiadosť z vášho nymu, ktorý vidí každý kľúč.

odpoveď

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

Podpísanie žiadosti o účet

Vytváranie, zmena a zrušenie kľúčov, súhrn účtu a automatické top-upy neberú kľúč API. berú podpis z vášho nym, takže únikový kľúč môže minúť až do svojho limitu, ale nikdy nemôže vytvoriť ďalší kľúč alebo zvýšiť svoj vlastný limit.

Aplikácia to robí za vás: všetko vo svojom Oheň Táto sekcia je potrebná len pre správu kľúčov z vášho vlastného kódu.

Podpis je udalosť Nostr typu 27235 (NIP-98), odosielané base64-kódované v Authorization header so slovom Nostr Na prednej strane:

udalosť

{
  "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 je úplná adresa URL žiadosti, vrátane reťazca dotazu, presne tak, ako bola odoslaná.
• method Je to metóda HTTP.
• payload je SHA-256 surového žiadosti tela, v hex. POST a PATCH, a telo, ktoré odošlete, musí byť byte za byte, ktoré ste hashovali.
• created_at musí byť v priebehu 60 sekúnd od hodiny servera.
• Každá udalosť funguje raz, a GET zahrnuté, takže zachytené hlavičky nie je možné prehrať. Podpíšte novú hlavičku pre každú požiadavku. nonce označte náhodnou hodnotou tak, aby sa dve žiadosti podpísané v tej istej sekunde stále líšili.
• Telo podpísanej žiadosti môže byť maximálne 64 KB a telo potrebuje Content-Type: application/json.

Chýbajúca udalosť sa vracia 401 missing_nostr_auth; jeden, ktorý je zle vytvorený, zle podpísaný, príliš starý, alebo pre inú adresu URL, metódu alebo telo vráti invalid_nostr_auth, s dôvodom v správe; opätovne použitý sa vráti nostr_auth_replayedPodpis sa skontroluje pred čítaním tela a každá adresa ju môže zlyhať 30 krát za minútu (adresa IPv6 sa počíta ako celok /64); potom dostane 429 s Retry-After.

Prehliadače môžu tieto koncové body volať iba z vlastných stránok Nymbotu (https://nymbot.ai, https://nymchat.app Stránka na akejkoľvek inej stránke nedostane žiadne hlavičky CORS späť, takže nemôže čítať to, čo vrátia. OriginNie sú ovplyvnené.

Títo pomocníci vytvárajú hlavičku. Neskoršie príklady na tejto stránke ich používajú. Čítajú tajný kľúč v hexadecimáli od NOSTR_SECRET_HEX; cURL jeden používa nak nástroj príkazového riadka, ktorý používa nsec alebo hexový kľúč, a sha256sum v prípade 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");
}

Zhrnutie účtu

Čo ukazuje tabuľka API aplikácie v hornej časti: váš verejný kľúč, rovnováha, koľko kľúčov je aktívnych (nie je zrušené alebo vypršalo) a Automatický top-up nastavenia alebo null keď ich server neposkytuje.

GET https://nymbot.ai/api/v1/account Potrebuje a Podpísaná žiadosť.

odpoveď

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

Správa kľúčov

Koncové body za zoznamom kľúčov aplikácie. Všetky z nich potrebujú Podpísaná žiadosťKaždý kľúč sa vráti v tomto formulári, s časmi v ISO 8601 a sumami v sats:

kľúčový objekt

{
  "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 Stačí rozpoznať kľúč, ale nie ho použiť.Kľúč sa vráti len raz, keď je vytvorený.

Zoznam kľúčov

GET https://nymbot.ai/api/v1/keys a podpísané.

odpoveď

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

Vytvorenie kľúča

POST https://nymbot.ai/api/v1/keys Podpísané, vrátené 201.

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

Čítať jeden kľúč

GET https://nymbot.ai/api/v1/keys/{id} a podpísané.

Vrátenie {"data": {…}} s kľúčovým objektom, alebo 404 key_not_found ak žiadny z vašich kľúčov nemá toto 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);

Zmena kľúča

PATCH https://nymbot.ai/api/v1/keys/{id} a podpísané.

Pošlite akúkoľvek name, limit_sats, reset_period a expire_ats rovnakými pravidlami ako pri vytváraní kľúča. null vymaže pole: bez obmedzenia, bez resetu, bez uplynutia platnosti. Zmena obdobia resetu začína nové obdobie od nuly. Zrušený kľúč sa nedá zmeniť (400 key_revoked) Návraty {"data": {…}} s aktualizovaným kľúčovým objektom.

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

Odstránenie kľúča

DELETE https://nymbot.ai/api/v1/keys/{id} a podpísané.

Zastaví kľúč naraz, pre dobro. Zostáva v zozname s revoked_at nastaviť, a môže byť videný s include_revoked=trueZrušenie kľúča, ktorý už bol zrušený, odpovie rovnakým spôsobom. Zachová sa len 50 najnovších zrušených kľúčov; staršie kľúče sa vymažú, keď sa zruší ďalší kľúč.

odpoveď

{ "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 súprava

Pripojte peňaženku Lightning s Nostr Wallet Connect a Nymbot dosahuje rovnováhu sám o sebe, keď výdavky API bežia nízko. Podpísaná žiadosť.

Ako to funguje: po žiadosti o API sa účtuje do zostatku, ktorý ste sa rozhodli sledovať, ak táto bilancia klesla pod vašu prahovú hodnotu, Nymbot vyhotoví faktúru za vašu vrchnú sumu, požiada vašu peňaženku, aby ju zaplatila, a pridáva kredit. Vypláca sa maximálne raz za každých 5 minút pre každú nym a bilanciu, takže výbuch žiadostí nemôže vyčerpať peňaženku. Výdavky v aplikáciách ju nespúšťajú. Čas a veľkosť posledného vrchného a poslednej chyby sú v nastaveniach; ak platba prešla po chybe, skontrolujte svoju faktúru s Štatút top-up kreditovať to.

Pripojenie peňaženky

POST https://nymbot.ai/api/v1/nwc-auto-topup/connect a podpísané.

odpoveď

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

Čítať nastavenia

GET https://nymbot.ai/api/v1/nwc-auto-topup a podpísané.

Vráti rovnaký objekt ako pripojenie, s connected: false a ostatné polia null Keď nie je pripojená peňaženka, samotný reťazec pripojenia sa nikdy nevráti.

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

Odpojiť

DELETE https://nymbot.ai/api/v1/nwc-auto-topup/connection a podpísané.

Odstráni uložený reťazec pripojenia. Nie sú vytvorené žiadne ďalšie top-upy. Aby ste boli istí, môžete tiež zrušiť pripojenie vo vašej peňaženke.

odpoveď

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

Platba na požiadanie bez kľúča

Koncové body s pevnou cenou je možné zaplatiť za jednu žiadosť naraz cez Lightning, bez kľúča, bez účtu a bez zostatku: POST /images/generations, POST /images/edits, POST /videos, POST /audio/speech, POST /audio/transcriptions, POST /audio/translations a POST /embeddingsŽiadosť, ktorá nesie kľúč, sa účtuje do zostatku ako obvykle; platobný tok začína len vtedy, keď nie je poslaný žiadny kľúč.

Nymbot hovorí dve verzie tej istej myšlienky, z jedného backend: Lightning Labs ' M402 (taktiež prijímané pod jeho starým menom, LSAT) a návrh IETF platba HTTP Authentication schéma s lightning Metóda a charge Používajte čokoľvek, čo váš klient chápe.

Výzva

Odoslať žiadosť s nie Authorization header. ak je platná, nič nefunguje a dostanete 402 Payment Required s faktúrou za presne to, čo požiadavka stojí: rovnakú cenu, ktorú by kľúč zaplatil, premenený na 10 sats štandardný kredit alebo 100 sats Pro kredit a zaokrúhlený na celý sat (aspoň 1 sat, a aspoň 0.05 kreditný minimum). WWW-Authenticate Výzvy pre rovnakú faktúru:

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

- platba request Základný parameter je base64url JSON: {"amount":"237","currency":"sat","methodDetails":{"invoice":"lnbc...","network":"mainnet","paymentHash":"..."}}.

Výzva je viazaná na koncový bod, na Content-Type (jeho typ média a, pre multiparty, jeho hranica) a na SHA-256 presné telo bajtov, ktoré ste poslali, a trvá 15 minút. identické Opäť žiadosť: rovnaké Content-Type a rovnaké JSON bajty, alebo pre viaceré časti koncových bodov (/images/edits, /audio/transcriptions, /audio/translationsVäčšina HTTP knižníc vyberá nový limit zakaždým, keď šifruje formulár, takže ho šifrujte raz a pošlite tieto bajty dvakrát.

Každá adresa môže požiadať o 30 výziev za minútu (adresa IPv6 sa počíta ako celok /64). Žiadosti, ktorých adresa nie je známa, zdieľajú prísnejšie 10 za minútu a existuje celková hranica na výzvy Nymbot problémov vo všetkých adresách; žiadosť zamietnutá pred výzvou je vykonaná (napríklad s telom, ktorý nie je platný JSON) sa k nej nepočíta. 429 s Retry-AfterPlatené koncové body volané bez kľúča alebo poverenia sa tiež započítavajú do všeobecného limitu 120 neautentifikovaných požiadaviek za minútu na adresu. Content-Type Nie je application/json (alebo multipart/form-data pre nahrávanie) je odmietnutý s 415 Nikdy nedostanete faktúru.

Embeddings sú oceňované z odhadu tokenov v vstupe, s marginou 1,5 krát, pretože skutočný počet je známy až potom. Vrátiť token.

Odoslanie platby

Zaplatiť faktúru s ľubovoľnou Lightning peňaženku. Peňaženka vám dáva predobraz, 64 hex znakov. Potom odoslať rovnakú žiadosť s jedným z týchto:

Platená žiadosť odpovedá presne tak, ako tá, ktorá bola vykonaná s kľúčom, s výnimkou toho, že nymbot objekt nemá polia rovnováhy: {"payment": "l402", "tier": "pro", "paid_sats": 237, "charged_sats": 237}a nie je tam žiadny X-Nymbot-Balance-Sats header. Žiadosť zaplatená pomocou platobnej schémy tiež dostane Payment-Receipt header (base64url JSON s ID výzvy, platobný hash ako reference, status a timestampPlacené požiadavky nie sú viazané na žiadny nym, takže sa nezobrazia v histórii dotazov.

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

Zákazníci sú postavení na mppx s metódou blesku zvládnuť výzvu platieb sami; ukázať im na koncový bod a nechať ich platiť.

Videá

a platené POST /videos Odpovede 202 ako kľúčový jeden, plus a status_url: GET bez akéhokoľvek kľúča na sledovanie práce. je podpísaný a pracuje 24 hodín, pokiaľ je práca udržiavaná.

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

Udržujte si refund_token z tejto odpovede: je zobrazená iba tu. Je prázdna, zatiaľ čo video zobrazuje (GET /api/v1/l402/refunds Odpovede "status": "pending"); ak renderovanie zlyhá bez faktúry, platba pristane na ňom. refund_sats pre vrátenú prácu, ale nikdy token, takže zdieľanie URL adresy stavu nezdieľa vrátenie peňazí.

Vrátenie

Ak platená žiadosť zlyhá a poskytovateľ účtuje Nymbot za pokus, platba sa ponechá a chyba tak hovorí, s charged_sats, presne ako pre kľúčovú žiadosť. Ak zlyhá bez fakturácie, chyba nesie Vrátiť token Stojí za to, čo ste zaplatili:

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

Nepoužité diely sa vrátia rovnakým spôsobom: ak ste požiadali o dve fotografie a jedna sa nepodarilo vyúčtovať, úspešná odpoveď nymbot objekt nesie token na vrátenie peňazí za chýbajúci jeden; transkripcia, ktorej dĺžka sa nedá čítať dopredu, sa oceňuje za najdlhšie, čo môže byť súbor (nikdy viac ako 30 minút), a rozdiel k skutočnej dĺžke sa vráti ako token na vrátenie peňazí; ak sa ukáže, že je dlhší ako 30 minút, je odmietnutý s 413 a celá platba sa vráti.Zahrnuté vráti to, čo odhad držal späť.Neúspešné video vráti token jeho predloženie vrátené.

Token na vrátenie peňazí je náhodný 256-bitový kód. Nymbot ukladá iba jeho hash a vyprší po 30 dňoch.

• Zaplatiť s ním. Poslať Authorization: Bearer REFUND-… na niektorom z vyššie uvedených koncových bodov (OpenAI SDK to berie ako svoj API kľúč). cena pochádza z tokenu a to, čo zostáva, zostáva na ňom (refund_token_sats V tejto nymbot objekt). token v hodnote menšej ako odpoveď na žiadosť 402 refund_insufficientNeúčtované zlyhanie vráti sadzbu späť na ten istý token.
• Skontrolujte to GET /api/v1/l402/refunds s rovnakým headerom sa vracia {"sats": 237, "status": "open", "expires_at": "..."}.
• Jeden token môže byť použitý maximálne 60 krát za minútu.
• Presuňte ho na nym. Vložte ho do Získajte darček v aplikácii Nymbot, alebo zavolať POST /api/v1/l402/refunds/redeem s A Podpísaná žiadosť a {"refund_token": "REFUND-...", "balance": "standard"} (alebo "pro"Celé kredity idú do zostatku (10 sadzieb každý na štandard, 100 na Pro); sadzby, ktoré nerobia celý kredit zostať na tokene pre požiadavky 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"

odpoveď

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