Bu’uura beekumsaa / Uumtoota

Hisaaba, guuttiiwwan fi wijijoota

Hamma qabdu sakatta'i, Lightning fayyadamtee kennata dabali, walii keetiin ofumaan kennata dabali, gatii gaaffii tokko tokko ilaali, akkasumas koodii irraa 'keys' to'adhu.

Fuulli kun akka mijatutti maashiniin kan hiikamedha. Orijinaalli Ingiliffaa kan ilaallatudha.

Lakkoofsa qabaachuu (baasii) mirkaneeffachaa jira

Balansiin keessan lamaan, fi hamma kaffaltii qofaa kanaan itti fayyadamaa jirtu.

GET https://nymbot.ai/api/v1/credits/balance — API key barbaada. POST lakka'aas ni hojjeta, maamiltoota eeggannoo qabanif.

balance akkasumas gatii Bitcoin ammaa irratti, baasiin lamaan walitti qabamu biiliin yoo ta'an, meeshaalee lakkoofsa tokko qofa eeggatan (null yoo gatiin dubbifamuu hin dandeenye). Kaanisaan ni jira kirediitii fi sats, kun immoo karaa salphaa yukkoo baalansii dhugaa ittiin kuufamu dha. key wijiricha ibsa kan gaafate. Wijirri daangaa isaa gahaate akkasiisii hisaaba ilaaluu danda'a.

Deebii

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

Tooftaalee kaffaltii

Akkaataa itti kuufan (top up) fi daangaa isaa. Lightning kallattiin qofa.

GET https://nymbot.ai/api/v1/topup/payment-methods — furtuu hin barbaachisu.

Kaffaltiin gubbaa deebii (top-up) 10 hanga 1,000,000 sats dha; kaffaltii Pro tokko tokko bitachuuf kirediitii Pro tokko addunyaa bitachuu qaba, kanaaf 100 sats irraa eegala. Limitii doolarii gatii Bitcoin hordofa. bulk_bonus kreditii dabalataa kutaalee gurguddoo irratti ta'u, akka appii keessatti jiruun tarreessi: kutaalee gurguddoo kanneen 500, 1,000 ykn 5,000 sats irraa jalqaban irratti 10%, 15% ykn 20% dabalataa, kutaalee Pro kanneen 5,000, 10,000 ykn 50,000 sats irraa jalqaban irratti immoo.

Deebii

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

Lightning irratti topping up gochuu

Invooysii Lightning tokko uumii kan kireediitiin (credit) toora nym kii malkaa kireediitii sana qabu irratti dabalu. Walxaxee (wallet) Lightning kamiyyuu irraa kaffali, achiis sakatta'i kiriidiin akka itti dabalamuuf.

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

Kirediitii seerrii idilee 10 sats dha, kirediitii Pro immoo 100 sats dha, dabalataan bonus baay'inaatiin; credits invoosii kun maal akka dabalu dubbata.

Deebii

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

Gargaarsa kaffaltii (top-up) mirkaneeffachaa jira

Invoosii sun kaffalamee jiraachuu isaa gaafata, yeroo kaffaltiin raawwatamu immoo kireedii (credit) dabala. To’achuun (Checking) maaltu kireedii akka itti dabalu dha, kanaaf kaffaltiin booda, haalli isaa hanga ta’utti to’adhu credited. Itti aanuuf irra deebiin mirkaneeffachuun nagaadha: kireetiin yeroo meeqa gaafattu iyyuu al tokko qofa ni dhufe.

GET https://nymbot.ai/api/v1/topup/status/{invoice_id} — fakkii (invoice) qopheesse sana irraa furtuu (key) barbaada.

status dha pending (hanas kaffaltiin hin kaffalame), paid (ka'umsa kaffaltii raawwatame, garuu ammas hin dhufe; irra deebi'ii ilaali), credited (supha kee irratti) ykn expired (yeroo isaa hin kaffalamne). Marsaawwan salphaa (balance) kutaa qarshii (tier) inni inwoosii sun itti dabalamuuf qophaa'an.

Deebii

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

Seenaa gaaffii

Gaaffii tokkoof riqicha tokko: maaltu ture, modelii kam, tokkaleen meeqa fi gatiin isaa meeqa. Prompt-wwan ykn deebiiwwan hin kuufamu, kanaafis tokko hin deebisamu. Riqichonni guyyaa 90f qabamu, kan haaraa dura. Kiiin limitii isaa gahu danda'e seenaa isaa dubbisuu ni danda'a.

GET https://nymbot.ai/api/v1/queries/history — API key barbaada, kan gaaffii isaa ofii argu, yookaan... gaaffii mallatteeffame nym keetiirraa, kan furtii hunda argu.

Deebii

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

Iyyattoota herregaa mallatteessuu

Uffata uumuu, jijjiiruu fi haqsuu, gabaasa herregaa fi kaffaltii ofumaan gaggeeffamu (automatic top-ups) API key hin fudhatan. Isaan mallattoo (signature) nym keessanii fudhatu, kanaafuu, key uumamee fi dhangala'e (leaked key) dandeettii gabaa (cap) isaa hamma danda'amutti fayyadamuu danda'a, garuu key biraa uumuu ykn dandeettii gabaa isaa ofii isaa dabaluu hin danda'u.

Appiin kun kan sadii siif taasisa: waan hundumaa bakka isaa keessatti API sheet endpoints kanneen fayyadama. Sekshinii kana koodii keetiin koodii (keys) bulchuuf qofa barbaaddu.

Mallattoo sun waa'ee NIP-98 (kind 27235) event Nostr ti, kan base64-encoded ta'een ergame... Authorization barruu jecha qabuun Nostr duratti:

Garaa sana

{
  "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 URL guutuu ijaarsa gaaffii sanaa, qubeeffannoo query string dabalatee, akka ergame sana qofadha.
• method karaa HTTP ti.
• payload SHA-256 request body ragaa dhagamuun (raw), bifa hex ta'een dha. Inni kana irratti barbaachisaadha POST fi PATCH, fi qaama ati ergtu byte tokkoon byte tokko wal fakkaachuu qaba, kan ati hash goote sana.
• created_at sa'aatii serveerii irraa sekondii 60 keessatti qabamuu qaba.
• Garaagarummaa hundi yeroo tokko hojjata, a GET dabalameera, kanaafuu header qabame deebisanii fayyadamuu hin danda'u. Karaa tokkoon gaaffii hundaaf haaraa mallatteessi. Dabali nonce valii tasgabbii (random) tokkoon itti mallatteessi kanaafuu, gaaffiin lamaan sekondii tokko keessatti mallatteeffamanis adda ta'uu qabu.
• Qaamaan gaaffii mallatteeffamee hamma 64 KB qofa ta'uu danda'a, fi qaamni barbaada Content-Type: application/json.

Mul'ata dhabame deebii kenna 401 missing_nostr_auth; kan bifa hin taane, mallattoo hin taane, baay'ee durii, yookaan URL, mala yookaan qaama biraa kanatiin wal hin simne deebisa invalid_nostr_auth, sababa ergaa keessatti jiru waliin; kan irra deebi'ee tajaajila deebisu nostr_auth_replayedAPI key erga endpoint-wwan kanaaf ergamee booda ni رفضatama. Saantigini (signature) qaamaan (body) dubbisuun dura ni qoratama, akkasumas teessoon tokko tokko daqiiqaa tokko keessatti yeroo 30 fashaleeffachuu danda'a (teessoon IPv6 hundi /64 akka tokkootti lakkaa'ama); sana booda ni... 429 waliin Retry-After.

Biraawaraawwan endpoint-wwan kana weebsaayitota Nymbot qofa irraa waamuu danda'u (https://nymbot.ai, https://nymchat.app fi subdoomaani isaanii). Fuulli marsariitii biroo kamiyyuu deebii header-ota CORS hin argatu, kanaafuu waan isaan deebisan dubbisuu hin danda'u. Skriptoonni fi appilikeeshiniiwwan uumamaa (native apps), kanneen kanneen hin ergin... Origin, miidhamuu hin qaban.

Gargaartoonni kun mata-duree ijaaru. Fakkeenyi dabalataa fuula kana irratti kan argaman isaan fayyadamu. Isaan furtuu iccitii hex keessatti argamu dubbisu. NOSTR_SECRET_HEX; kan cURL fayyadama nak meeshaa command-line, kan nsec ykn hex key fudhatu, fi sha256sum (macOS irratti, 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");
}

Gabaasa herregaa

Waraqaan API appii kanaa olitti maal agarsiisa: furtuu kee basummaa, walaloo (balances) lamaan, furtuunni meeqa akka ta'an (kanneen hin haqamne ykn hin dhumne), fi ufurtaa ofumaan deebi'u sochannoo, ykn null yeroo serwerri isaan hin kennin.

GET https://nymbot.ai/api/v1/account — barbaada gaaffii mallatteeffame.

Deebii

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

Tooraalee bulchuu

Dhaabbataalee (endpoints) tarree furtuu appii sanaa duuba jiran. Isaan hundi __________ barbaadu. mallattoo guutame gaaffii. Keyni hundi bifa kanaan deebifama, yeroon ISO 8601 ta'ee fi hammi sats ta'ee:

Obeektii furtuu

{
  "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 iiqisii furtuu sana addaan baasuf qofadha, garuu fayyadamuf miti. Furtuun itu yeroo tokkoffaa, yeroo hojjetamutti qofa deebisama.

Kallattiiwwan tarreessuu

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

Deebii

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

Iccitii uumuu

POST https://nymbot.ai/api/v1/keys — mallatteeffame. Deebiiwwan 201.

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

Kakuu tokko dubbisuu

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

Deebiiwwan {"data": {…}} keeyyicha kanaan, yookaan 404 key_not_found yoo kallattii keessan tokko iidii sana hin qabne.

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

Koflii jijjiiruu

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

Kamiyyuu kan keessaa ergi name, limit_sats, reset_period fi expire_at, seera kanaan wal fakkaatuun yeroo furtuu hojjetan akkuma sana. null furaa tokko: dabalataa hin jiru, deebisanii hin sirreessan, dhumatti hin qabu. Yeroo deebisanii sirreessuu jijjiiruun yeroo haaraa eessaa (zero) jalqaba. Kiiyaan (key) haqame jijjiiramuu hin danda'u (400 key_revoked). Deebisanoo {"data": {…}} keeyyoo fooyya'aa dhaabbata sana waliin.

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

Furtuu haqqa'sisuu

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

Yeroo tokkoffaa, barabaraaf, furtuu sana dhaaba. Liistii keessatti kan hafu... revoked_at qaroo, akkasumas ni mul'achuu danda'a include_revoked=trueKii kan duraan dhowwame deebisanii dhowwuun deebii wal fakkaatu kenna. Kiiwwan dhowwaman hunda keessaa kanneen dhiyoo qofa 50 kanaan dura dhowwaman qabama; kiiwwan durii ammoo kii biraa yoo dhowwame irra deebi'anii balleessama.

Deebii

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

Waletii Lightning Nostr Wallet Connect waliin walitti hidhi, yeroo baasii API gadi bu'u immoo Nymbot ofii isaa baasii (balance) guuta. Waraqaan API appichaa qindoomina wal-fakkaataa qaba; kunneen immoo endpoints isaa jiru dha. Isaan hundi barbaadu... gaaffii mallatteeffame.

Akkaataa itti hojjetu: erga gaaffiin API tokko baajata ati ilaaluuf filatte irratti kaffalamu eegalee, yoo baasni sun sadarkaa (threshold) ati murteeffatte jalaa gad bu'e, Nymbot kaffaltii dabalataa (top-up) kennamaa jiruuf inwooisii (invoice) hojjeta, waletii kee akka kaffalu gaafata, ergasii kaffaltii sanis dabala. Nym fi baajata hundaaf daqiiqaa 5 keessatti tokko qofa kaffaltii dabalataa (top-up) hojjeta, kanaaf ergaa walitti aanu (burst of requests) waletii kee hin xumuru. Appilikeeshonoota keessatti maallaqa baasuun kaffaltii dabalataa kana hin uumu. Yeroon fi hamma kaffaltii dabalataa dhumaa, akkasumas dogoggorri dhumaa, tooftaa (settings) keessatti jira; yoo dogoggorri tokko booda kaffaltiin tokko milkaa'e, inwooisii isaa kana _______ waliin __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ Haala galtee kireeditii itti kenna.

Wallet walitti hidhachuu

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

Deebii

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

Qindoomina dubbisuu

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

Walitti dhufeenya qabu koo fakkaatu kan walitti hidhuun wal fakkaatu deebisiisa, waliin connected: false fi dameewwan biroo null yeroo walii galteen walii gallee hin jirre. Walii galteen (connection string) ofii isaa yoomiyyuu hin deebisamu.

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

Walitti kutachaa jira

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

Kutaa walitti hidhaa (connection string) kuufame balleessa. Itti fufiinsaan kaffaltii (top-ups) hin taasifamu. Akka mirkanaa'uuf, walitti hidhaa kee waleteetiin (wallet) ni haqsuu dandeessa.

Deebii

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

Furtii malee ergaa tokkoof kaffaluu

Dhaabbii gatii murtaa'e irratti hundaa'uun, Lightning fayyadamuun gaaffii tokko tokkoon, koodii (key) malee, herrega (account) malee fi maallaqa (balance) malee kaffaluun ni danda'ama: POST /images/generations, POST /images/edits, POST /videos, POST /audio/speech, POST /audio/transcriptions, POST /audio/translations fi POST /embeddings. Chat, Deebiinni fi Ergaafni yoomiyyuu furtuu ni barbaadu. Ergaan furtuu qabu akka baramaatti kaffaltii bu'aa (balance) irraa ni fudhata; adeemsi kaffaltii sun kan jalqabu yoo furtuun hin ergamin qofa.

Nymbot yaada tokko gara wal fakkaatu lamaatti, backend tokko irraa dubbata: Lightning Labs' L402 (akkasumas maqaa isaa durii jalatti fudhatama qaba,) LSAT) fi qaxxaamichi IETF Kaffaltii Samaa odeeffannoo HTTP kanaan wal qabatu lightning tarkaanfii fi charge kaayyoo. Kan maamilichi hubatu kamiyyuu fayyadami.

Qorumicha

Gaaffii sana eenyuun ykn maaloon malee ergi Authorization header. Yoo sirrii ta'e, nothing runs, fi atis argatta 402 Payment Required invoosii wanta gaaffiin sun gatii meeqa akka itti kaffalamu qabuun: gatii kootii madda (key) tokko kaffaluun wal qabatu, kireettii (credit) sagantaa idilee irratti 10 sats ykn kireettii Pro irratti 100 satsitti jijjiiramee fi gara sats guutuutti olitti dabalame (ufannaa tokko, fi uguumama kireettii 0.05 irra). deebiin kun sadii of keessaa qaba WWW-Authenticate Rakkoolee inbooyisii sanaaf:

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

Kaffaltii sana request parameterii base64url JSON: {"amount":"237","currency":"sat","methodDetails":{"invoice":"lnbc...","network":"mainnet","paymentHash":"..."}}.

Waraanni duubdee (endpoint) irratti hidhama, kan... Content-Type (gosa miidiyaa isaa fi, multipart ta'ee yoo ta'e, daangaa isaa) fi SHA-256 byte-ota qaama (body) ati ergite kan sirrii ta'an irratti, akkasumas daqiiqaa 15f ni turta. Kaffaltii booda, ... wal-fakkaataa irra deebi'ii gaafadhu: kan sana Content-Type fi byteeyyii JSON kan wal-fakaatu, yookaan endpoint-ota multipart ta'aniif (/images/edits, /audio/transcriptions, /audio/translations) qaabdii multipart wal-fakaataa daangaa (boundary) wal-fakaataa qabuun. Liibariwwan HTTP hedduun yeroo hunda foormii irra deebisanii hiikan daangaa haaraa filatu, kanaaf immoo yeroo tokko qoodi (encode) sana ergaa bytesii sana kana lamaan ergi.

Teessoonni hundi daqiiqaatti gaaffii (challenge) 30 gaafachuu danda'u (teessoonni IPv6 hundi /64 isatti lakkaawama). Gaaffiin teessoonni isaanii hin beekamne murtoo cimaa daqiiqaatti 10 qofa gaafachuu danda'u, akkasumas gaaffiiwwan Nymbot teessoonota hunda irratti kennu irratti dhibbaa (cap) walii-galaa jira; gaaffiin gaaffii (challenge) dhiyaachuu dura dhorkame (fakkeenyaaf, yoo JSON sirrii ta'e hin taane) lakkoofsa sana keessatti hin lakkaawamu. Kana booda deebiin isaa... 429 waliin Retry-After, qaama dura kan ergame. Bakka itti fayyadamaa (endpoints) key ykn ragaa (credential) malee waamamanis lakkoofsa daangaa waliigalaa daqiiqaa tokkotti iddoo tokko irraa ergame kan 120 gaaffii ragaa hin qabne keessatti lakkaawama. Ragaa (credential) qaama dura kan qulqullaa'u, fi gaaffiin kan jedhu... Content-Type miti application/json (yookaan multipart/form-data (ufata ol fe'uuf) ni diigama waliin 415 akkiis yeroo hunda invooisi hin argatu.

Gadi lakkaisuun (embeddings) lakkoofsa tookenii (tokens) galmee keessa jiru irratti hundaa'uun, margin 1.5× ta'een gatii itti kaffalamu, sababni isaas lakkoofsi dhugaan booda qofaan beekamu dha. Tookenii dhugumaan fayyadaman qofa kaffaltu, kan kaffaltii hin fayyadamin immoo deebisanii siif kenna. token deebii.

Kaffaltii ergaa jira

Invoosii kana waletii Lightning kamiyyuu kaffali. Waletiin preimage, qabxiiwwan hex 64 siif kenna. Sana booda ergaa kana isaan keessaa tokkoon ergi:

Gaaffiin kaffaltii barbaadu akkuma kanii dhaabbataa (key) ittiin hojjetamu fakkaata, garuu... nymbot meeshaan kutaalee baasii hin qabu: {"payment": "l402", "tier": "pro", "paid_sats": 237, "charged_sats": 237}, akkasumas hin jiru X-Nymbot-Balance-Sats header. A gaaffiin kaffaltiin sirna Payment jedhamuun kaffalameis argata Payment-Receipt header (base64url JSON id challenge, hash kaffaltii akkasiin reference, status fi timestamp). Gaaffiin kaffaltii ragaa kennu nym kamiyyuu wajjin hin hidhamu, kanaafuu seenaa gaaffii (query history) keessatti hin mul'atan.

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

Maamiltoonni irratti ijaaraman mppx Tooftaa Lightning'aan rakkoo kaffaltii ofiin hiiku; bakka endpoint'itti qajeelchi kaffaltii isaan raawwachuuf dhiisi.

Viidiyoowwan

Kaffaltii POST /videos deebiiwwan 202 kan qabxii qabuun akka, dabalataan a status_url: GET Hojii hordofuu danda'u furtuu tokko malee. Kan mallatteeffame dha akkias hojiin sun yoo eegame sa'aatii 24f hojjeta.

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

Hojiirra kaa'i refund_token deebii kana irraa: as qofa ni argama. Viidiyoon suuraa ka'uu (render) manatti immoo duwwaadha (GET /api/v1/l402/refunds deebiiwwan "status": "pending"); yoo render-iin dhimma kaffaltii hin qabne fashale, kaffaltichi irratti bu'a. URL haala (status) agarsiisa refund_sats hojii deebisii (refunded) ta'eef garuu tookenii hin dabalne, kanaaf URL haala (status) agarsiisu sana qooduun deebii (refund) hin qoodu. Tookenii sakatta'uun hojii fashala'e kan eenyuyyuu hin hordofne (polled) sirreessuudha.

Deebiiwwan kaffaltii

Yoo gaaffiin kaffaltii barbaadu tokko gufatee, dhiyeessaan immoo yaalii sanaaf Nymbot irratti kaffaltii buuse, kaffaltichi ni qabatama, erroon immoo akkas jedha, kan inni... charged_sats, akka gaaffii qabxii qabuutti guutumaan. Yoo kaffaltii malee dadhabe, dogoggorri sun qabata token deebii kennata kaffaltii keetiiti:

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

Kutaaleen hin fayyadamin akkuma kanaan duraan deebi'an: yoo fakkii lama gaafattee tokko kaffaltii malee gufuu irra ga'e, deebiin milkaa'inaa dha nymbot meeshaan tokko tokenii deebii (refund token) kan tokko hin jirreef qabata; barreeffama hiikamee dhumina isaa dura dursee dubbisuu hin dandeenye gatiin isaa dheerina isaa inni danda'amuun (yeroo tokkoo daqiiqaa 30 ol hin ta'u) kaffalama, gara dheerina isaa dhugaa jiruutti inni garaagarummaan jiru immoo tokenii deebii (refund token) dhuunfaatti deebifama; yoo daqiiqaa 30 ol ta'e immoo, kanaan tola hin fudhatamu 413 akkaataa kanaan kaffaltiin guutumtuu deebi'a. Embeddings-n wanta tilmaamaan dorkame deebisa. Viidiyoon dadhabe token isa submission isaa deebiseef deebii (refund) kenna.

Tokenii deebii (refund) mallattoo random 256-bitii dha. Nymbot hashii isaa qofa kuusa, akkasumas guyyaa 30 booda darba. Inni saldoo satii qaba, akkasumas ati:

• Ittiin kaffali. Ergi Authorization: Bearer REFUND-… kan dursa irratti ramaddii (endpoint) kamiyyuu (OpenAI SDK key API isaanitti fayyadama). gatiin token irratti ragadu, inni hafe immoo irratti hafa (refund_token_sats keessatti nymbot objektii). Toora gatii gaaffii san gadi bu'aa qabu. 402 refund_insufficient; fashalaan billii hin qabne satsiiwwan tokko tokko tokko irratti deebisa.
• Qulqulleessi. GET /api/v1/l402/refunds mataafara sana waliin deebisi {"sats": 237, "status": "open", "expires_at": "..."}.
• Token tokko daqiiqaa tokkotti yoo danda'ame qofa akka 60 yeroo fayyadamuu danda'a.
• Nym tokko irratti geessii. Keessa kaayi Kennaa tokko fudhadhu appii Nymbot keessatti, ykn bilbili POST /api/v1/l402/refunds/redeem --> aannaniin gaaffii mallatteeffame fi {"refund_token": "REFUND-...", "balance": "standard"} (yookaan "pro"). Kreditiwwan guutun gara baalanziitti deemu (standard irratti 10 satsii, Pro irratti 100 satsii); satsiiwwan krediti guutuu hin taane gaaffiiwwan APIf tookenii irratti hafu.

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"

Deebii

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