Ubumenyi shingiro / Abakora porogaramu

Ubwuzuzanye, kwongeza ibicuruzwa n'amfunguzo

Reba ibyo ufite, wongereze amafaranga ukoresheje Lightning, wongereze amafaranga mu buryo bwikora ukoresheje ikibanza cyawe cy'amafaranga, reba igiciro kuri buri gusaba, kandi uyobore amashanyarazi (keys) ukoresheje ikodemuri.

Uru rupapuro rwahinduwe imashini kugirango byorohe. Umwimerere wicyongereza ni verisiyo ikoreshwa.

Kureba umubare w'amafaranga asigaye

Imibare y'amafaranga yawe yose, n'uburyo uyu muryango w'urugero rw'urufunguzo rwakoreshejwe.

GET https://nymbot.ai/api/v1/credits/balance — ikenera urufunguzo rwa API. POST bikora kandi, ku bakiriya bategereza ibyo.

balance ese imibare ibiri y'amafaranga isanzwe irimo hamwe mu madolari hashingoje igiciro cya Bitcoin ubu, ku ibikoresho bikenera umubare umwe (null (niba igiciro kitashobora gusomwa). Ibindi birimo credits na sats, uburyo imibare y'amafaranga itegurwa. key ivuga urugero rw'urugero rwabahambaye. Urufunguzo rugeze ku mupaka rushobora kugira n'uburyo bwo kureba imibarire.

Igisubizo

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

Uburyo bwo kwishyura

Uko wongerera amafaranga, n'imipaka. Lightning ni uburyo bumwe bwonyine.

GET https://nymbot.ai/api/v1/topup/payment-methods — nta kirango kibikeneye.

Kuzamura ibimuri (top-up) biva kuri 10 kugeza kuri 1,000,000 sats; kuzamura ibimuri bya Pro bigomba kugura nibura agaciro kamwe ka Pro, bityo bitangira ku 100 sats. Ibihengeri by'amadolari bigendera ku igiciro cya Bitcoin. bulk_bonus yerekana inguruka y'inyongeza y'amafaranga ku nshuro nini zo kwishyura, nk'uko bimeze muri porogaramu: 10%, 15% cyangwa 20% yongereye ku nshuro zisanzwe zo kwishyura kuva kuri 500, 1,000 cyangwa 5,000 sats, n'ubundi kuri Pro kuva kuri 5,000, 10,000 cyangwa 50,000 sats.

Igisubizo

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

Kuzuzanya binyuze kuri Lightning

Kora invoice ya Lightning igaragaza ko itanga credit ku nshuro (nym) iyigize. Iyishyure ukoresheje Lightning wallet yose, hanyuma... reba uko bimeze kugira ngo amari y'uburyo (credit) yongerwe.

POST https://nymbot.ai/api/v1/topup/create/btc-lightning — ikenera urufunguzo rwa API.

Ikreditombyi y'isanzwe ni 10 sats kandi ikreditombyi ya Pro ni 100 sats, ugasigaye n'ibindi byongezo by'ubwinshi; credits bivuga icyo iyi fagitire izongeraho.

Igisubizo

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

Kureba ikirundikanyo cy'amafaranga yagutse

Baza niba inyemezabuguzi (invoice) yishyurwe, hanyuma iyo yishyurwe, yongereho ikredit. Kugenzura ni byo bituma ikredit yongera, bityo nyuma yo kwishyura, genzura kugeza igihe imiterere (status) izaba creditedKureba bwa kabiri nyuma ni ko byiza: amafaranga yinjira rimwe gusa, naho waba wabajije inshuro nyinshi.

GET https://nymbot.ai/api/v1/topup/status/{invoice_id} — asaba urugero (key) ruvuye kuri nym yakoreye invoice.

status ni pending (ntarayahembwe), paid (yishyuwe, ariko ntacyo yagezeho; reba nanone), credited (ku isubizo ryawe) cyangwa expired (itabishwa ntitabishwe ku gihe). Amategeko y'uburenganzira yerekana umwanya (tier) inyandiko y'amafaranga yuzura.

Igisubizo

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

Amateka y'ibibazo

Umurongo umwe kuri buri gusaba: icyo ari cyo, igimodeli yakoreshejwe, ingano y'amagambo (tokens) n'igiciro cyacyo. Nta bibazo cyangwa ibisubizo byatangiwe byasigara, bityo nta byatanzwe. Imirongo igumana amakuru mu minsi 90, itangira ku nshya cyane. Icyapa (key) cyageze ku mupaka gishobora gusoma amateka yacyo.

GET https://nymbot.ai/api/v1/queries/history — ikeneye API key, iyibona ibyo isaba, cyangwa a ubusabe bwashyikirijwe umurongo w'umukono kuva ku izina ryawe, rirebeye kuri buri funguzo.

Igisubizo

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

Gushyikiriza ubusabe bwo kwinjira kuri konti

Gukora, guhindura no gukuraho amashkey, incamake y'ikonti n'inyongeza y'amafaranga yo mu buryo bwikora ntibakeneye API key. Bikenera umukono (signature) uturuka kuri nym yawe, bityo amashkey niba yamenetse ashobora gukoreshwa kugeza ku kigero cyagenwe ariko ntashobora gukora undi mashkey cyangwa kwongera kigero kacyo.

Iyi porogaramu ikora ibi ku bwanyu: byose mu buryo bwacyo API imbonerahamwe ikoresha aya maponto. Ukeneye iki gice gusa kugira ngo ukore imfunguzo uturutse muri code yawe.

Umukono ni Nostr event ya kind 27235 (NIP-98), yoherejwe mu buryo bwa base64-encoded muri Authorization umutwe urimo ijambo Nostr imbere:

Ibirori

{
  "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 ese URL yuzuye y'ubutumwa bwo gusaba, irimo n'ibitekerezo by'ubushakashatsi (query string), nk'uko yaboherejwe neza.
• method ni uburyo bwa HTTP.
• payload ese SHA-256 y'umubiri w'ubusabe bwuzuye, mu buryo bwa hex. Birasabwa kuri POST na PATCH, kandi umubiri uwo utumye ugomba kuba uwo washinze byte ku byte.
• created_at bigana n'isaha ya serivure mu gihe cy'amasegonda 60.
• Buri igikorwa gikora rimwe, a GET bishyizwemo, bityo iyandiko y'icyerekezo (header) ifatanywe ntishobora gusubirwamo. Shyiraho ikindi gishya kuri buri gusaba. Shyiraho a nonce Shyiraho agaciro k'amahirwe kugira ngo ubusabe bubiri bwashyiriweho umukono mu kanya kamwe bukomeze kuba butari kimwe.
• Umubiri w'ubusabe bwashyizweho umukono ushobora kuba ubuze 64 KB atari byinshi, kandi umubiri ukeneye Content-Type: application/json.

Ibintu bicyeye bitariho bigaruka 401 missing_nostr_auth; ikintu kiba kagiye nabi cyangwa kagiye mu buryo butari bwo, cyasinywe nabi, kiba kera cyane, cyangwa ari ku URL, uburyo cyangwa umubiri utandukanye kiba kigarura invalid_nostr_auth, n'impamvu iri mu butumwa; icyakoreshejwe noneho kiragaruka nostr_auth_replayed. Kaminira ya API yoherejwe kuri aya mwandiko ntiyakirwa. Igisobanutso (signature) gipimwa mbere y'uko umubiri w'ubutumwa usomwa, kandi buri aho ushobora kugira ikibazo inshuro 30 mu minota imwe (aho aho IPv6 hateganywa nko kureba ubumenyi bwayo bwose bwa /64); nyuma yaho igahagarikwa 429 hamwe na Retry-After.

Browsers bashobora guhamagara aya endpoints gusa kuva ku mbuga za Nymbot ubwayo (https://nymbot.ai, https://nymchat.app (n'ubundi bube bwa subdomains). Urubuga ruri kuri site iyindi niyo yose ntiruhabwa headers za CORS, bityo ntirushobora gusoma ibyo bitoroshye. Scripts n'amappu ya native, atari yo ituma Origin, ntibagerwaho.

Aba bafasha baranga umutwe. Ingero zikurikira kuri uru rupapuro zirayikoresha. Basoma iyihishe y'urugero mu nkingi ya hex kuva NOSTR_SECRET_HEX; iy' cURL ikoresha nak igikoresho cyo kuri command-line, kigira imiterere ya nsec cyangwa hex key, hanyuma na sha256sum ( kuri 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");
}

Incamake y'ibarurishamari ry'konti

Icyo urutonde rwa API rw'icyiciro (app) rwerekana hejuru: public key yawe, imibare y'amafaranga (balances) yose ibiri, uko amazinga (keys) ari menshi akora (atari yo yasubitswe cyangwa yarangiye), n' kwiyongerera imari ukwayo izingatanye, cyangwa null igihe seriveri itabaha.

GET https://nymbot.ai/api/v1/account — akenera ubusabe bwashyikirijwe umurongo w'umukono.

Igisubizo

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

Gucunga amashiga

Endpoints ziri inyuma y'urutonde rw'imfunguzo rw'iyo porogaramu. Zose zikeneye isabuwe isaba. Buri kintu kagaruka muri ubu buryo, aho igihe binyuze mu miterere ya ISO 8601 ndetse n'umubare w'amafaranga mu sats:

Icyerekezo cy'ikintu

{
  "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 bihagije kumenya funguzo ariko ntibishobora kuyikoresha. Funguzo ubwayo itangwa rimwe gusa, igihe ikorwa.

Kurebesha amashami

GET https://nymbot.ai/api/v1/keys — ashyize umukono.

Igisubizo

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

Gukora urufunguzo

POST https://nymbot.ai/api/v1/keys — bishyizweho umukono. Ibisubizo 201.

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

Gusoma umwe mu nkingi z'ingenzi

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

Igisubizo {"data": {…}} hamwe n'ikintu gikuru, cyangwa 404 key_not_found niba nta funguro ryawe rifite iyo 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);

Guhindura funguro

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

Ongerereze rimwe na rimwe muri name, limit_sats, reset_period na expire_at, n'amategeko amwe n'ayo ukoresha iyo urekuye urugero. null isukura ubutumwa: nta mupaka, nta gusubizwa inyuma, nta gihe cyo gusoza. Guhindura igihe cyo gusubizwa inyuma bitangiza igihe gishya ku bwa zero. Ikirango cyakozweho umukano nticyashobora guhindurwa (400 key_revoked). Gusubiza {"data": {…}} hamwe n'ikintu cy'urufunguzo rwihindutse.

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

Gukuraho urubuga rw'urugero (key)

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

Hagarika urugamba ako kanya, burundu. Giguma muri uru rutonde hamwe na revoked_at bishyizweho, kandi bashobora kubonwamo include_revoked=trueGuhagarika urufunguzo rurimo rwahatswe n’ubundi ruzatanga igisubizo kimwe. Kurugero, urufunguzo rwa nyuma rw'ibyangombwa 50 rwahatswe rwonyine ruragumazwa; urwo rwasanzwe ruriho rurashimangirwa iyo urundi rwahatswe.

Igisubizo

{ "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 kuzuzanya bwikora

Huza Lightning wallet na Nostr Wallet Connect, hanyuma Nymbot yongere imari ifite ubwigenge iyo imari yo gukoresha API igiye gushira. Urutonde rw'API rwa app ruragira ibyo mategeko; aya ni amashereka (endpoints) ari inyuma yabyo. Yose asaba... ubusabe bwashyikirijwe umurongo w'umukono.

Uko bikora: nyuma y'uko ubusuguro bwa API bwakuwe ku miterere y'amafaranga watoranyijeho kugenzura, niba iyo miterere y'amafaranga imaze kugera munsi y'urugero wateganyije, Nymbot ikora inyandiko y'ibarura (invoice) y'umubare w'amafaranga ushaka kongeramo, ikabaza wallet yawe kuyishyura, hanyuma ikongeramo ayo mafaranga. Kongeramo amafaranga bikorwa inshuro imwe gusa buri minota 5 kuri buri nym na buri miterere y'amafaranga, bityo imenyekanisha y'ibibazo byihuse by'ubusuguro ntibishobora gusubiza wallet yose. Gukoresha amafaranga muri apps ntibitera ibyo. Igihe n'umubare w'amafaranga ya nyuma yongerewe, ndetse n'ikosa rya nyuma, biba muri settings; niba kwishyura byagenze neza nyuma y'ikosa, kugenzura invoice yaryo kuri imbonezamubano y'uko ikintu cyashyizweho ibituma bitanga amayira.

Kuhuza ikibanza cy'amafaranga (wallet)

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

Igisubizo

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

Gusoma izinganirezo

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

Guhagarura ibintu bimwe n'ibyo ubona iyo ufunguye, na connected: false n'andi mafundo yandi null iyo nta wallet yashyizweho. Uburyo bwo guhuza (connection string) ubwacyo ntibukirizwa na rimwe.

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

Kuvaho

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

Igera ku nshingano yo gusesa aho uburyo bwo guhuza bwakunze kubikwa. Nta yindi kuryozwa kuzongeraho izindi zahindura umutungo. Kugira ngo ube witeguye, ushobora no guhagarika uburyo bwo guhuza mu mufuka wawe (wallet).

Igisubizo

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

Kwishura kuri buri gusaba nta kigega (key) ukoresha

Ahantu hishyirwaho igiciro gihagije, bishobora kwishyurwa kuri Lightning kuri buri gusaba rimwe, nta kigero, nta konti kandi nta mbaraga z'amafaranga: POST /images/generations, POST /images/edits, POST /videos, POST /audio/speech, POST /audio/transcriptions, POST /audio/translations na POST /embeddings. Ibiganiro, Ibisubizo n' Ubutumwa byo gihora bikeneye urugero (key). Icyifuzo cyitwaje urugero kirabazwa ku ishami ry'imari nk'ibisanzwe; uruzinduko rw'ubwishyu rwatangira igihe nta rugero rwatumijwe.

Nymbot avuga verisiyo ebyiri z'igitekerezo kimwe, biva kuri backend imwe: Lightning Labs' L402 (cyemewe kandi n'izina ryaryo rya kera, LSAT) n'icyandiko cya IETF Ukwishyura Uburyo bwo kwizera HTTP nahawe lightning uburyo na charge intego. Koresha iyose yakwemerera umukiriya wawe.

Imbogamizi

Yohereze ubusabe nta Authorization umutwe. Niba ari uwo kwemera, nta kintu gikorwa, kandi ubona 402 Payment Required hamwe n'ubwandikisho bw'amafaranga asobanura neza igiciro cy'icyo cyifuzo: igiciro kimwe n'icyo kuremewe (key) kwishyura, bishyizwe mu miterere ya 10 sats kuri credit isanzwe cyangwa 100 sats kuri Pro credit kandi bikagurishwa mu mibare yuzuye ya sat (nibura sat 1, kandi nibura 0.05 credit minimum). Inyandiko irimo eshatu WWW-Authenticate imbogamizi ku fagitire imwe:

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

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

Ikibazo gihambiranye ku mpera, kuri Content-Type (uburyo bw'uburyo bwo kwakira amakuru n'uburyo bwa multipart, urugero rwa boundary) ndetse n'SHA-256 y'amakuru ya body yose wakoze, kandi biba bibanza iminota 15. Nyuma yo kwishyura, tumira bimwe na bimwe gusaba nanone: kimwe na kimwe Content-Type na amabureti ya JSON ako kanya, cyangwa ku muryango w'uburyo bwinshi (/images/edits, /audio/transcriptions, /audio/translations) umubiri w'ibice nyinshi (multipart body) nk'uyu ariko ufite umukubito (boundary) ukora nk'uyu. Amategeko menshi ya HTTP akora imiterere nshya y'umukubito buri nshuro akora ishyirwa mu miterere y'ifomu (encode a form), bityo shyira mu miterere inshuro imwe hanyuma utume amabati (bytes) nk'ayo kabiri.

Icyerekezo cose gashobora gusaba ibibazo 30 mu minota imwe (icyerekezo cya IPv6 kireberwa nk'icyo /64 cyose). Ibisabwa aho icyerekezo cyabyo kitazwi bigabanyirizwa ibindi 10 mu minota imwe bikaba bikaze kurushaho, kandi harimo uruzinduko rwo hejuru rw'ibibazo Nymbot itanga kuri n'ibindi cyerekezo byose; isaba ryavunzwe mbere y'uko ibibazo bitangwa (urugero, kubera umubiri utajyanye n'JSON yemewe) ntiribariwe mu rwo ruzego. Nyuma yaho igisubizo ni 429 hamwe na Retry-After, yoherejwe mbere y'uko umubiri usomwa. Amafunguro ya endpoints yariherereye yo kutakoresha funguro cyangwa ibimenyetso bishingiye ku bwishingizi na yo areba igipimo rusange cya 120 ubusabe budafite ibimenyetso mu minota imwe kuri adresi imwe. Icyimenyetso kizamurwa mbere y'uko umubiri usomwa, kandi ubusabe uwo Content-Type si application/json (cyangwa multipart/form-data ku gushyira inyandiko muri (uploads) biratanzwe na 415 kandi ntigeze agira fagitire.

Ibara ry'ibiciro bya Embeddings rishingikirije ku gakeza k'ibitekerezo (tokens) biri muri input, hakoreshejwe umubare w'inyongezo ya 1.5×, kuko umubare w'ukuri ubasanga ari nyuma. Wishyura ibitekerezo byakoreshejwe rwose, kandi igice cy'umutungo utakoreshejwe kugaruka nk'a akagurisha k'amafaranga.

Ndi kohereza ibyo kuri wishyu

Ishyure inyandiko y'amafaranga (invoice) ukoresheje ikiyandiko cyo kuri Lightning wallet rimwe na rimwe. Icyo kiyandiko kiguha preimage, imyandiko 64 ya hex characters. Hanyuma utume ubu busabe busubirwamo ukoresheje kimwe muri ibi:

Ubushakashatsi bwishyurwe buhindura neza nk'ubwakoze ukoresheje urufunguzo, uretse ko... nymbot icyiciro ntigifite amategeko yerekeye imibare y'amafaranga: {"payment": "l402", "tier": "pro", "paid_sats": 237, "charged_sats": 237}, kandi nta X-Nymbot-Balance-Sats umutwe. A ubwishyu bukorwa ukoresheje gahunda y'ubwishyu na bwo bubona Payment-Receipt header (base64url JSON urimo id ya challenge, hash y'uburishye nka reference, status na timestamp). Ibicuru bywishyurijwe ntibihuza n'izina rya nym, bityo ntibigaragara muri amateka y'ibibazo byavuzwe.

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

Abakiriya bubatse kuri mppx bikoresheje Lightning handle ikizamara cy'ubwishyu; banyuze ku muryango w'ubwo wishyu (endpoint) maze bakishyure.

Amavideo

Byishyuwe POST /videos ibisubizo 202 nk'icyo cyafashwe n'urufunguzo, n'ubundi status_url: GET bitabayeho ikintu cyose kigiye gukurikiza akazi. Cyashyizweho umukono kandi gikorana amasaha 24, igihe cyose akazi kaba kigumye.

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

Gumana ibyo refund_token kuva kuri ubu gisubizo: bigaragara hano gusa. Birimo ubusa mu gihe video igikorwa (GET /api/v1/l402/refunds ibisubizo "status": "pending"); niba imiterere (render) itagatsindagiye itarishyuwe, inyandiko y'uburishyu twizera ko izagera kuri yo. URL y'imiterere (status) yerekana refund_sats ku kazi ryashowe iguzurwa ariko ritarabona token, bityo kugabana URL y'imiterere byo ntibigaragaza iguzurwa. Kugenzura token na byo birashyamira akazi kageze ku mpera komeye kagiye mu kaga nta muntu warigenzuye.

Kwishyura amafaranga yakozwe mu kosa

Niba ubusabe bwishyu bwanga, hanyuma uwayoboye bukura amafaranga kuri Nymbot ku bw'iyo gerageza, amafaranga agumana kandi ikosa ryerekana ibyo, hamwe na charged_sats, nk'uko bimeze ku gusaba kwometseho urufunguzo. Iyo bitanzwe bidasubizwaho amafaranga, ikosa ririmo akagurisha k'amafaranga bihuye n'ibyo wishyuye:

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

Ibice bitakoreshejwe bigaruka mu buryo bumwe: niba wasabye amafoto abiri hanyuma imwe ikaba itarishyuwe, igisubizo cy'icyo cyagenzewe biba nymbot igikorwa kirimo ikarita y'imyegurure y'ibyo burawe; inyandiko ishyirwa mu magambo aho isuregeranya itari yashoboranye gusomwa mbere ihindurirwa igiciro cy'igihe kirekireya ifayile ishobora kuba (ntitizigera biba birenze iminota 30), kandi itandukaniro riri hagati y'igihe nyacyo n'icyo byateganyijwe rihindurwa nk'ikarita y'imyegurure; niba bigaragara ko birenze iminota 30, biratwarwa n' 413 kandi ikiguzi cyose kiragaruka. Embeddings ziragarura ibyo igenenurwa ryafaridaga. Video yatsinzwe isubiza mu miterere ya token iyo yohereje.

Icyitonderwa cy'ishowe (refund token) ni ikode y'amayeri ashingiye kuri 256-bit. Nymbot ibika hash yacyo gusa, kandi ikazaza gusesa nyuma y'iminsi 30. Icyo cyitonderwa gifite umubare wa sat, kandi ushobora:

• Yishyure ukiyishyurireho. Ogera Authorization: Bearer REFUND-… ku yo muri ayo macebe hejuru (OpenAI SDK ikayikoresha nk'urugero rwa API key). Igiciro gikurwa kuri token kandi icyasigaye kigumaho (refund_token_sats mu nymbot ibintu). Agaciro gato kurusha ibyo gusaba bitanga ibisubizo 402 refund_insufficient; ikosa ritagurirwa risubiza sats kuri token imwe nk'iyo.
• Reba. GET /api/v1/l402/refunds na umutwe undo gusubiza {"sats": 237, "status": "open", "expires_at": "..."}.
• Token imwe ishobora gukoreshwa inshuro 60 atari nyinshi mu minota imwe.
• Yimurire ku nym. Shira muri Guhabwa impano mu app ya Nymbot, cyangwa telefoni POST /api/v1/l402/refunds/redeem na ubusabe bwashyikirijwe umurongo w'umukono na {"refund_token": "REFUND-...", "balance": "standard"} (cyangwa "pro"). Amafaranga yose ajya kuri balance (sats 10 kuri buri standard, 100 kuri Pro); sats zitagira credit yuzuye ziguma kuri token kugira ngo hanywe 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"

Igisubizo

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