Okubelelwe elwazini / Iimveliso

I-Balance, i-top-ups kunye ne-keys

Qhagamshelana nathi, up up up phezu Lightning, up up up ngokuzenzakalelayo ukusuka wallet yakho, ukubona iindleko ngamnye isicelo, kunye nokulawula iingcebiso ukusuka ikhowudi.

Eli phepha liguqulelwe ngoomatshini ukuze kube lula. Uqobo lwesiNgesi yinguqulelo esebenzayo.

Qhagamshelana ne-balance

Zonke izilwanyana zakho, kunye nokuninzi le-cap ye-keyile isetyenziselwa.

GET https://nymbot.ai/api/v1/credits/balance - kufuneka i-API key. POST Ukusebenza kwakhona, kubathengi abalandeli.

balance iiyure ezimbini ezixhomekeke ngama-dollars ngexabiso le-Bitcoin, ukuba izixhobo ezihambisa inani elilodwa (null Ukuba ixabiso ayikwazi ukucacisa). Ixabiso i-credits kunye ne-sats, nto leyo yintoni izilinganiso zikhuselwa. key Ukubonisa umqulu owayeleyo. Umqulu oya kufumana i-cap yaye ungenza i-balance.

Qhagamshelana

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

Izindlela zePayment

Yintoni ungenza, kunye neengxaki. Lightning yindlela kuphela.

GET https://nymbot.ai/api/v1/topup/payment-methods - Akukho key ebonakalayo.

I-top-up yi-10 ukuya kwi-1,000,000 i-sats; i-pro-top-up kufuneka ibekwe i-credit ye-Pro, ngoko kuqala kwi-100 i-sats. I-dollar limits ilandelayo ixabiso ye-Bitcoin. bulk_bonus inikeza i-credit extra kwi-top-ups ezinkulu, efanayo ne-app: i-10%, i-15% okanye i-20% ngaphezulu kwi-top-ups eziqhelekileyo kwi-500, i-1000 okanye i-5000 sats, kunye ne-Pro top-ups kwi-5000, i-10,000 okanye i-50,000 sats.

Qhagamshelana

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

Ukuphakamisa phezu Lightning

Yenza i-Invoice ye-Lightning enikezela i-credit ye-nym ye-key. Yenza ngexabiso kwi-Lightning ye-wallet, ke Zibonisa ukuba i-credit eyongezelelwe.

POST https://nymbot.ai/api/v1/topup/create/btc-lightning - kufuneka i-API key.

I-credit ye-standard yi-10 sats kunye ne-Pro credit ye-100 sats, kunye ne-bonus ye-mass; credits Ukubonisa ukuba oku kukongeza.

Qhagamshelana

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

Ukuhlolwa kwe-top-up

Qaphela ukuba inkinobho ifayilishwe kwaye, ngoko ke, ukongeza i-credit. Ukubuyekeza ukuba i-credits, ngoko emva kokubuyekeza, qinisekisa ukuba i-status creditedUkubuyekeza kwakhona emva kwexesha elifanelekileyo: i-credit iholide nje, nangona imizuzu embalwa.

GET https://nymbot.ai/api/v1/topup/status/{invoice_id} - kufuneka i-key evela kwi-nym eyenza i-facture.

status Yintoni pending (Wagqibela ukuba ushiye imali), paid (Wagqibela, kodwa ayikho kwakhona; Qhagamshelana nathi), credited (kuye kwi-balance yakho) okanye expired (hhayi akubhalwe ngexesha elandelayo). Iindawo ze-balance ziquka kwinqanaba le-invoice.

Qhagamshelana

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

Qhagamshelana noHistory

Umgca omnye ngalinye ngalinye: nto leyo, iimodeli, iintlobo ze-token kunye neentlawulo. Akukho imibuzo okanye imibuzo ezihlabathi, ngoko akuyona. Imibuzo ezihlabathi iintsuku ze-90, i-newest yokuqala. Umgca oya kufumana i-cap inokufunda i-history yayo.

GET https://nymbot.ai/api/v1/queries/history — kufuneka i-API key, ebonakalayo izicelo zayo, okanye a Isicelo sokubhalisa ukusuka nym yakho, leyo uyazi zonke iingcebiso.

Qhagamshelana

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

Qhagamshelana nezicelo ze-akhawunti

Ukwenza, ukuguqulwa kunye nokuguqulwa iingcebiso, isibuyekezo yekhompyutha kunye ne-automatic top-ups ayidinga i-API key. Zibonisa i-signature ye-nym yakho, ngoko iingcebiso ebonakalayo ingathumela ukuya kwi-cap yayo kodwa ayikwazi ukwenza i-key enye okanye ukwandisa i-cap yayo.

I-app ikwenza oku ngenxa yenu: yonke into yayo Ukucinga sheet usebenzisa le endpoints. Ufuna kuphela le ndawo ukulawula iingcebiso ukusuka ikhowudi yakho.

I-signature yi-Nostr event ye-type 27235 (NIP-98), ifumaneka kwi-base64 Authorization i-header kunye ne-word Nostr Ukusuka ku:

Ukusebenza

{
  "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 i-URL epheleleyo ye-request, i-query string kuquka, ngokufanelekileyo njenge-envoy.
• method Yintoni indlela ye-HTTP.
• payload i-SHA-256 ye-body ye-request raw, kwi-hex. I-SHA-256 ye-body ye-request raw POST kwaye PATCH, kwaye umzimba ufumana kufuneka yi-byte ye-byte eyayithunyelwe.
• created_at kufuneka kuxhomekeke ngaphakathi kwexesha le-60 ye-server.
• Zonke iziganeko zokusebenza ngexesha elinye, a GET kuhlanganiswe, ngoko i-header ebonakalayo ayikwazi ukudlala kwakhona. Yenza i-header entsha ngalinye imibuzo. Yongeza i nonce i-tag nge-value ye-random ukuze izicelo ezimbini ziye zithunyelwe ngexesha elifanelekileyo.
• I-body ye-signed request ingaba kwi-64 KB, kwaye i-body kufuneka Content-Type: application/json.

I-event yokuzonwabisa ifumaneka 401 missing_nostr_authI-URL ye-URL, i-method okanye i-body ye-URL ezininzi invalid_nostr_auth, kunye neengxaki kwi-message; a reused one returns nostr_auth_replayed. I-API key ekuthunyelwe kwezi endpoints ifumaneka. I-signature ifumaneka ngaphambi kokufunda i-body, kwaye ngalinye i-address inokufumana i-30 iiyure ngenyanga (i-address ye-IPv6 ibekwe njengoko yonke /64); emva kokuba ibekwe 429 Ukucinga Retry-After.

I-Browser inokufumana i-endpoints ezininzi kuphela kwi-website ye-Nymbot (https://nymbot.ai, https://nymchat.app yayo subdomains). I-page kwi-website ye-orange ayikho i-CORS headers ekugqibeleni, ngoko ayikwazi ukucacisa into ezivela. I-scripts kunye ne-app ye-native, eyenza akukho OriginKwakhona akuyona.

Iintlawulo ze-helper zibonise i-header. Iimeko ezidlulileyo kule sayithi zisebenzisa. Zibonisa i-keyword ye-hex NOSTR_SECRET_HEX; i-cURL one isebenzisa i Ukucinga isixhobo se-command-line, ebonakalayo nsec okanye i-hex key, kwaye sha256sum (Nge 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");
}

Iinkcukacha ze-account

Yintoni ifowuni ye-API ye-app ibonisa phezulu: key yakho ye-publish, i-balances ezimbini, inani le-keys esebenzayo (ayikwazanga okanye ifumaneka), kunye ne- Okuzenzakalelayo Top-up iimveliso, okanye null xa i-server ayikwazanga.

GET https://nymbot.ai/api/v1/account Ngaba ufuna a Isicelo sokubhalisa.

Qhagamshelana

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

Ukuqhagamshelwano Key

I-endpoints esekelwe kwi-list ye-key ye-app. Zonke kufuneka Isicelo sokubhalisaZonke iingcebiso ziya kubhalwe kule fomu, kunye nexesha kwi-ISO 8601 kunye neeyunithi kwi-sats:

Isixhobo Key

{
  "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 Ukubonakaliswa kwe-key, kodwa akukho ukusetyenziswa kwe-key. I-key inokufumana nje nje, xa ifumaneka.

Ukubhalisa Key

GET https://nymbot.ai/api/v1/keys Ukubhalisa

Qhagamshelana

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

Ukwenza Key

POST https://nymbot.ai/api/v1/keys Ukubhalisa. Ukubhalisa 201.

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

Ukucinga Key One

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

Ukuguqulwa {"data": {…}} kunye ne-object key, okanye 404 key_not_found Ukuba akukho key yakho unayo le 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);

Ukuguqulwa kwe-key

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

Thumela nayiphi na name, limit_sats, reset_period kwaye expire_at, kunye neengxaki efanayo njengoko ukuvelisa key. null Ukubhalisa indawo: akukho cap, akukho reset, akukho ukuhlaziywa. Ukuguqulwa kwexesha le-reset kuqala ixesha elitsha kwi-zero. I-key eyenziwe ayikwazi ukuguqulwa (400 key_revoked(Wagqibela ukufika) {"data": {…}} kunye ne-object key eyakhiweyo.

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

Ukubala i-key

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

Ukukhusela i-key ngexesha elifanayo, ngokufanelekileyo. Kukho kwi-list revoked_at iimveliso, kwaye kunokufumana kunye include_revoked=trueUkuguqulwa kwe-key eyenziwe ngexesha elifanayo. Kukho kuphela i-50 keys ezidlulileyo ezidlulileyo; ezidlulileyo zithunyelwe xa i-key elinye isivulwe.

Qhagamshelana

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

Qhagamshela i-Lightning wallet nge-Nostr Wallet Connect kunye ne-Nymbot uqhagamshelane ngokufanelekileyo xa izindleko ze-API ziyafumaneka ezantsi. I-API sheet ye-app inesibelelwano efanayo; apha iingxaki zangaphakathi. Zonke ze Isicelo sokubhalisa.

Indlela yokusebenza: emva kokufakwa kwe-API ku-balance oyifunayo ukubuyekeza, ukuba i-balance iyaphantsi kwinqanaba yakho, i-Nymbot ithatha i-invoice ye-top-up amount yakho, ibiza i-wallet yakho ukuba bayidlulele, kwaye ibandakanya i-credit. I-invoice ibandakanya ngexesha elide ngamaminithi angama-5 ngamaminithi ngamnye kunye ne-balance, ngoko i-invoice ebandakanya i-wallet. Ukutyelela kwi-apps ayidala. Ixesha kunye ne-size ye-top-up yokuqala, kunye ne-error yokuqala, ziyafumaneka kwi-settings; ukuba i-payment yandwa emva kwe-error, ukhangela i-invoice yayo kunye Umgangatho we-top-up Yintoni credit it.

Ukuqhagamshela i-Wallet

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

Qhagamshelana

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

Ukucinga i-Settings

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

Iphumela i-object efanayo ne-connect, kunye connected: false Kwimeko ezininzi null xa akukho i-wallet ifumaneka. I-connection string itself is never returned.

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

Ukuqhagamshelana

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

Ukukhusela i-string ye-connection ebhalisiweyo. Akukho i-top-ups ezininzi ziye ziye ziye ziye ziye ziye ziye ziye ziye ziye ziye ziye ziye ziye ziye ziye ziye ziye ziye ziye ziye ziye ziye ziye ziye ziye zibe.

Qhagamshelana

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

Ukubhalisa ngexesha elandelayo ngaphandle kwe-key

I-Fixed-price endpoints ingathengiswa ngexesha elinye ngexesha nge-Lightning, ngaphandle kwe-key, ngaphandle kwe-account, ngaphandle kwe-balance: POST /images/generations, POST /images/edits, POST /videos, POST /audio/speech, POST /audio/transcriptions, POST /audio/translations kwaye POST /embeddings. I-Chat, i-Response kunye ne-Messages yintoni kufuneka i-key. I-Request eyenza i-key ifayile kwi-balance njenge-normally; i-payment flow kuqala kuphela xa akukho i-key ifakwe.

I-Nymbot ibonisa iintlobo ezimbini ye-idea efanayo, ukusuka kwi-backend eyodwa: i-Lightning Labs' Nqakraza 402 (Wagqibela ukufikelela kwimveliso yayo, LSAT) kunye nenkqubo ye-IETF Ukubhalisa I-HTTP authentication scheme kunye ne- lightning indlela kunye charge Intshayelelo. Ukusetyenziswa njengoko abathengi bakho uyazi.

Ukuphendula

Thumela isicelo nge-no Authorization ifayibha. Ukuba iyatholakala, akukho isebenze, kwaye ufumane 402 Payment Required kunye ne-invoice ngenxa yintoni okufanayo iindleko: ixabiso efanayo i-key uya kulula, ifayibha kwi-10 sats i-credit ye-standard okanye i-100 sats i-Credit ye-Pro kwaye ifakwe kwi-set epheleleyo (ngaphansi kwe-1 sat, kwaye angaphansi kwe-0.05 credit minimum). WWW-Authenticate Iingxaki ze-account ye-account ye-account:

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

Ukuhambisa request isampuli ye base64url JSON: {"amount":"237","currency":"sat","methodDetails":{"invoice":"lnbc...","network":"mainnet","paymentHash":"..."}}.

Umxholo uqhagamshelane kwi-endpoint, kwi- Content-Type (umgangatho we-media yaye, ukuba i-multipart, i-limit) kunye ne-SHA-256 ye-body ye-byte esifunyenweyo, kwaye ithatha ixesha le-15 imizuzu. Emva kokukhokha, uqhagamshelane i Ukucinga isicelo esifanayo: sama Content-Type kwaye i-JSON bytes efanayo, okanye i-endpoint ye-multipart (/images/edits, /audio/transcriptions, /audio/translationsIzixhobo ezininzi ze-HTTP zibonise i-limit entsha ngexesha lokufaka ifomu, ngoko ufake ngexesha elinye kwaye zithumela i-byte ezimbini.

Yonke i-address inokufunda i-30 iingxaki ngenyanga (i-address ye-IPv6 ibekwe njengoko /64 yayo). Iingxaki apho i-address ayikho yaziwayo zihlanganisa i-10 ngenyanga, kwaye kukho iingxaki epheleleyo kwiingxaki ze-Nymbot kwiingxaki ze-address zonke; isixazululo ekugqibeleni ngaphambi kokufumana iingxaki (isib. nge-body eyenza i-JSON) ayikwazanga kwakhona. 429 Ukucinga Retry-AfterIingxelo ze-endpoints ezamahala ngaphandle kwe-key okanye i-credential zihlanganisa kwi-limit ye-120 yeengxelo ze-non-authenticated ngenyanga ngalinye. Iingxelo ze-credential zihlanganisa ngaphambi kokufunda i-body, kwaye iingxelo ebonakalayo Content-Type Yintoni application/json (Ukuba multipart/form-data ukuze uploads) is a refusal with 415 Kwaye akukwazi ukufumana inkinobho.

I-embeddings iyahlaziywa kwi-estimating ye-tokens e-input, kunye ne-margin ye-1.5; njengoko i-real count iyaziwe kuphela emva koko. Uyakwazi ukulayisha i-tokens ezisetyenziswayo, kwaye i-part ebonakalayo ye-payment iyafumaneka njengoko Ukuguqulwa kweToken.

Ukuvumela imali

Ukubhalisa i-invoice kunye ne-Lightning wallet. I-wallet ibonelela i-preimage, i-64 iimpawu ze-hex. Emva koko uqhagamshelane isicelo esifanayo nge-one of these:

I-Request ye-Payment ifumaneka ngexabiso efanelekileyo efanelekileyo efanelekileyo efanelekileyo kunye ne-key, ngaphandle kokuba nymbot i-object ayikho izixeko ze-balance: {"payment": "l402", "tier": "pro", "paid_sats": 237, "charged_sats": 237}, kwaye akukho X-Nymbot-Balance-Sats i-header. Isicelo esekelwe nge-Payment Scheme kunokwenzeka Payment-Receipt i-header (base64url JSON kunye ne-challenge id, i-payment hash as reference, status kwaye timestamp). Iimfuno ze-Payed ayihlaziywa kwi-nym ye-nym ye-nym ye-nym ye-nym ye-nym ye-nym ye-nym ye-nym ye-nym ye-nym.

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

Iinkcukacha ezisekelwe mppx kunye ne-Method Lightning, ukulawula i-Payment Challenge ngokufanelekileyo; uthetha kwi-endpoint kwaye baye baye baye baye baye.

iindidi

Ukubhalisa POST /videos Imibuzo 202 like a keyed one, plus a status_url: GET it ngaphandle kokubili ukuba uqhagamshelane nenkqubo. It is signed and works for 24 hours, ngexesha ukuba inkulumo.

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

Yenza i refund_token ukususela ku: it is shown only here. It is empty while the video rendering (GET /api/v1/l402/refunds Imibuzo "status": "pending"); ukuba i- render ibonakaliswe, i-payment ibekwe. I-URL ye-status ibonisa refund_sats Ukubhalisa i-token, kodwa akukwazi ukufumana i-token, ngoko ukusuka kwi-URL ye-status akukwazi ukufumana i-refund. Ukubhalisa i-token kunceda ukufumana i-token eyenziwe ngexabiso.

Ukubuyiselwa

Ukuba isicelo sokukhokha isisombululo kwaye inikeza i-Nymbot ngenxa yokusabela, ukugcina imali kunye ne-error ithi, kunye charged_sats, ngexesha elifanayo ngexesha le-keyed request. Ukuba isisombululo ngaphandle kokufaka, i-error ithatha Ukuguqulwa kweToken Yintoni iingcebiso ezifanelekileyo:

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

Iimpawu ezisetyenziswayo ziya kubhalwe ngexesha elifanelekileyo: Ukuba uthathe iifoto ezimbini kwaye enye asikwazanga ukufumana iifoto ezisetyenziswayo, ukufumana iifoto ezisetyenziswayo nymbot i-object ibonelela i-token ye-refund ye-omnye eyenza; i-transcription ebonakalayo ekugqibeleni kufuneka ifayilishwe ngexesha elide kakhulu le ifayile kunokwenzeka (kwixesha engaphezulu kwe-30 imizuzu), kwaye i-difference kwi-length efanelekileyo ibonelela njenge-token ye-refund; ukuba ibonakalisa ukuba kunzima ngaphezu kwe-30 imizuzu, ibonakalisa 413 yaye ixabiso epheleleyo iyafumaneka. I-Embeddings ibonelela into efunyenweyo. Ividiyo ebuthile ibonelela kwi-token ebonakalayo.

I-refund token i-code ye-256-bit ye-random. I-Nymbot ibhokisi kuphela i-hash yayo, kwaye ifumaneka emva kwe-30 iintsuku. I-Nymbot ibhokisi i-sat, kwaye unako:

• Yenza i-pay with it. Yenza Authorization: Bearer REFUND-… iimveliso ezininzi ezidlulileyo (i-OpenAI SDK ithathwe njenge-API key). Ixabiso ifumaneka kwi-token kwaye into efunyenweyo (refund_token_sats Kwimeko nymbot i-object). I-token ye-value ye-less than the request answers 402 refund_insufficientI-Unbiled Failure yenza i-SAT kwakhona kwi-token efanayo.
• Zibonisa GET /api/v1/l402/refunds kunye ne-header efanayo ifumaneka {"sats": 237, "status": "open", "expires_at": "..."}.
• I-token enye ingasetyenziswa kwi-60 iiyure ngenyanga.
• Yenza ku-nym Yenza ku Yenza i-cadeau kwi-app ye-Nymbot, okanye i-call POST /api/v1/l402/refunds/redeem Nge A Isicelo sokubhalisa kwaye {"refund_token": "REFUND-...", "balance": "standard"} (Ukuba "pro"). I-Credits ephelele kwi-balance (10 i-sats ngamnye kwi-standard, i-100 kwi-Pro); i-sats eyenza i-credit epheleleyo kwi-token ye-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"

Qhagamshelana

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