Kev paub hauv paus / Cov neeg tsim software

Nqi tshuav, ntxiv nqi thiab cov chaw tsim nyog

Saib koj muaj dab tsi, ntxiv nyiaj los ntawm Lightning, ntxiv nyiaj tsis tau txoj haujlwm los ntawm koj lub wallet tus kheej, saib txhua qhov kev thov nqi npaum li cas, thiab tswj hwm cov keys los ntawm code.

Nplooj ntawv no yog tshuab txhais kom yooj yim. Cov lus Askiv thawj yog cov version uas siv.

Xyuas tus nyiaj

Koj ob lub hloov nqi, thiab yuav npaum li cas ntawm lub cap ntawm lub nplooj ntawv no tau siv.

GET https://nymbot.ai/api/v1/credits/balance — xav tau ib lub API key. POST nyob zoo thiab, rau cov neeg siv uas tos tau nws.

balance puas yog ob tus nqi nyob hauv (balances) nyob ua ke hauv dollar raws li lub nqi Bitcoin tam sim no, rau cov cuab yeej uas xav tau ib tus lej xwb (null yog tias tus nqi tsis tuaj nyeem tau). Qhov uas tshuav yog nyiaj credits thiab sats, uas yog qhov tswj hwm cov nyiaj uas muaj tiag. key haiv txog lub npe uas tau thov. Ib lub npe uas tau txog qhov tshuav tseem tuaj yeem tshawb xyuas tau lub hnab nyiaj.

Teb lus

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

Cov txoj hauv kev them nyiaj

Koj yuav ua li cas tso peb ntxiv, thiab cov qib txwv. Lightning yog qhov kev siv nkaus xwb.

GET https://nymbot.ai/api/v1/topup/payment-methods — tsis tas siv lub nplooj ntawv txhua lub cim.

Kev ntxiv nyiaj yog 10 mus rau 1,000,000 sats; kev ntxiv nyiaj Pro yuav tsum tau yuav ib lub Pro credit tsawg tshaj plaws, yog li ntawd nws pib ntawm 100 sats. Cov nqi dollar raws li tus nqi Bitcoin. bulk_bonus rov qhia cov nqi ntxiv thaum ntxiv nyiaj ntau, zoo ib yam li hauv app: 10%, 15% lossis 20% ntxiv rau cov ntxiv nyiaj txoos ntawm 500, 1,000 lossis 5,000 sats, thiab rau cov Pro top-ups ntawm 5,000, 10,000 lossis 50,000 sats.

Teb lus

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

Ntxiv nyiaj siv dhau Lightning

Tsim ib daim Lightning invoice uas ntxiv credit rau lub nym uas tus key ntawd yog. Them nws los ntawm lwm yam Lightning wallet twg los tau, ces saib nws kom muaj cov nyiaj txiag ntxiv ntxiv rau.

POST https://nymbot.ai/api/v1/topup/create/btc-lightning — xav tau ib lub API key.

Ib lub nqi tsis tshua yog 10 sats thiab ib lub nqi Pro yog 100 sats, ntxiv rau txhua yam nqi tshaj ntxiv thaum yuav ntau; credits hais tias daim nqi no yuav ntxiv dab tsi.

Teb lus

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

Saib kev ntxiv nyiaj

Nug seb puas tau them daim ntawv them nqi lawm, thiab tom qab uas tau them lawm, ntxiv cov nyiaj txiag (credit). Kev tshawb xyuas yog qhov uas muab credit rau, yog li tom qab them, tshawb xyuas kom txog thaum qhov xwm txheej yog credited. Kev tshawb xyuas dua tom qab ntawd yog ib qho kev tiv thaiv: cov nyiaj yuav tsuas tuaj ib zaug xwb, txawm koj yuav nug ntau npaum li cas los xij.

GET https://nymbot.ai/api/v1/topup/status/{invoice_id} — yuav tsum muaj ib lub npe (key) los ntawm tus npe uas tau ua daim ntawv them nqi (invoice) ntawd.

status yog pending (tsis tau them npay tseem), paid (them pliv lawm, tab sis tsis tau tau nyiaj rau hauv; tshawb kom dua), credited (hauv koj tus xyeev) lossis expired (tsis tau them raws sij hawm). Cov chaw qhia tus nqi tshuav yog rau qib uas lub invoice ntxiv nrog.

Teb lus

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

Kev nco ntawm cov lus nug

Ib kab ntawm txhua thov nug: nws yog dab tsi, siv peev xwm (model) twg, muaj pes tsawg tokens thiab nqi yog dab tsi. Tsis muaj cov lus nug lossis cov lus teb uas raug khaws cia, yog li ntawd tsis muaj dab tsi raug xa rov qab. Cov kab yog raug khaws cia rau 90 hnub, cov tshiab tshaj plaws yuav nyob saum toj kawg nkaus. Ib lub luam (key) uas tau txog nws lub qib txwv tseem tuaj yeem nyeem tau nws cov keeb kwm.

GET https://nymbot.ai/api/v1/queries/history — yuav tsum muaj ib daim API key, uas pom nws cov kev thov nws tus kheej, lossis ib qho thov lees uas muaj npe tso npe los ntawm koj lub npe, uas pom txhua yam ntawm txhua lub chaw.

Teb lus

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

Kev sau tso cov kev thov account

Kev tsim, kev hloov thiab kev tshem tawm cov chaw tswj hwm (keys), cov ntaub ntawv xov xwm ntawm tus account thiab kev ntxiv nyiaj tsis tu ncua tsis xav tau API key. Lawv xav tau ib qho kev tshib (signature) los ntawm koj nym, yog li ntawd yog tias ib lub chaw tswj hwm raug zais tawm, nws tuaj yeem siv nyiaj mus txog nws qhov tsim nyog (cap) tab sis nws yuav tsis tuaj yeem tsim lwm lub chaw tswj hwm tshiab lossis ntxiv nws tus kheej qhov tsim nyog.

Lub app ua raws li no rau koj: txhua yam nyob ntawm nws nws nws API sheet siv cov endpoints no. Koj tsuas xav tau qhov chaw no los tswj cov keys los ntawm koj tus code tus kheej xwb.

Lub kos hauv ntej yog ib qho Nostr event ntawm hom 27235 (NIP-98), uas raug xa los ntawm qhov base64-encoded nyob rau hauv Authorization lub taub lug nrog lo lus Nostr nyob ntawm pem hauv:

Qhov teeb tsaam

{
  "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 yog lub URL tag nrho ntawm qhov kev thov, suav nrog qhov query string, zoo nkaus li thaum xa mus.
• method yog HTTP txoj hauv kev.
• payload yog SHA-256 ntawm cov ntaub ntawv raw ntawm thov, hauv hex. Nws yuav tsum tau rau POST thiab PATCH, thiab lub cev uas koj xa yuav tsum yog ib qhov zoo nkaus li qhov uas koj tau hashed.
• created_at yuav tsum yog haum hauv 60 feeb thib rau lub server's clock.
• Txhua qhov xwm txheej ua hauj lwm ib zaug, a GET muaj rau, yog li ntawd ib lub header uas raug khaws tseg yuav tsis tau tswv rov qab. Ntaus tshiab rau txhua qhov kev thov. Ntxiv ib... nonce ntxiv nrog ib lub nqi uas tsis muaj tswv yim lees kom ob qhov kev thov uas muaj cai los yog nyob hauv ib lub sij hawm uas tsis txawv txav tseem sib txawv.
• Lub cev ntawm ib qho thov uas muaj kos tuaj yeem muaj npaum li 64 KB, thiab ib lub cev yuav tsum muaj Content-Type: application/json.

Ib qho xwm txheej uas ploj tsis tau rov qab 401 missing_nostr_auth; ib yam uas tsis zoo xim, tsis muaj sig, qub dhau, los yog rau lwm URL, txoj hauv kev lossis qauv uas txawv, yuav rov qab qhov invalid_nostr_auth, nrog lub ntsiab lus hauv cov lus; ib yam uas siv dua yuav rov qab los nostr_auth_replayed. Ib lub API key uas xa mus rau cov endpoints no yuav raug tsis lees txais. Tus signature yog qhov uas raug tshawb xyuas ua ntej lub body raug nyeem, thiab txhua lub chaw (address) tuaj yeem tsis raug 30 zaus ib feeb (ib lub IPv6 address raug suav ua nws lub /64 tag nrho); tom qab ntawd nws yuav tau 429 nrog Retry-After.

Cov browser tuaj yeem hu cov endpoint no tsuas yog los ntawm Nymbot cov vaj tsev nws tus kheej (https://nymbot.ai, https://nymchat.app (thiab lawv cov subdomain). Ib lub vev xaib ntawm lwm lub site twg yuav tsis tau txais CORS headers rov qab, yog li nws tsis tuaj yeem nyeem qhov uas lawv xa rov qab. Cov scripts thiab cov native apps, uas tsis xa qhov uas tsis muaj Origin, tsis raug cuam tshuam.

Cov pab cuam no tsim lub header. Cov piv txwv tom ntej hauv tsab nplooj ntawv no siv lawv. Lawv nyeem lub secret key nyob rau hauv hex los ntawm NOSTR_SECRET_HEX; tus cURL ntawd siv tau lub nak lub cuab lus siv hauv command-line, uas yuav tx姆 ib lub nsec lossis hex key, thiab sha256sum (sa 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");
}

Cov ntawv xam ntawm tus account

Lub API sheet ntawm lub app qhia saum toj: koj qhov public key, ob yam tus nqi nyiaj (balances), pes tus keys uas tau siv (active) (tsis tau tshem tawm lossis tsis tau dhau sijhawm), thiab lub ntxiv nyiaj tswm teeb tsa, lossis null thaum tus server tsis muab rau lawv.

GET https://nymbot.ai/api/v1/account — xav tau ib thov lees uas muaj npe tso npe.

Teb lus

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

Tswj fwm cov chaw tswj thwj vim

Cov endpoint tom qab lub app's key list. Tag nrho lawv xav tau ib tug tsiv tshoob thov lug. Txhua lub nchuav (key) yog raug rov xa los hauv daim duab no, nrog lub sijhawm hauv ISO 8601 thiab cov nqis hauv sats:

Lub ntsiab lus tseem ceeb

{
  "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 yog txaus rau kev paub txog ib lub pob nøj tab sis tsis yog siv nws. Lub pob nøj nws tus kheej yuav raug rov xa mus ib zaug xwb, thaum nws raug tsim tawm.

Ntawv qhia cov nplooj ntawv

GET https://nymbot.ai/api/v1/keys — tau sau.

Teb lus

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

Tsim ib lub pob tswb

POST https://nymbot.ai/api/v1/keys — tau tshem tshoob. Qhov rov qab los 201.

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

Nyeem ib lub ntsiab lus tseem ceeb

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

Kev rov qab {"data": {…}} thiab lub npe tswv yeej, los yog 404 key_not_found yog tias tsis muaj koj li lub cim uas muaj tus id ntawd.

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

Hloov ib lub nplais

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

Xa ib yam li niaj hnub los yog txhua yam ntawm name, limit_sats, reset_period thiab expire_at, nrog cov cai tib yam li thaum ua ib lub pob nø. null soov tsheej ib ntaj chaw: tsis muaj qhov txwv, tsis muaj kev rov tsim dua, tsis muaj hnub kawm. Kev hloov pauv lub sij hawm rov tsim dua yuav pib ib lub sij hawm tshiab ntawm 0. Ib lub chaw tsim (key) uas raug tshem tawm tsis tuaj yeem hloov pauv tau (400 key_revoked). Tshuab rov qab los {"data": {…}} thiab nrog lub key object uas tau hloov kho tshiab.

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

Tshav tawm ib daim ntawv tseem ceeb

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

Nres lub luag haujlwm ntawm lub meej ntawm ib zaug, mus tas mus li. Nws nyob hauv daim ntawv nrog rau revoked_at teev tseg, thiab tuaj yeem pom nrog include_revoked=true. Kev tshem tawm ib lub tshwj xeem uas twb raug tshem tawm lawm yuav teb zoo ib yam xwb. Tsuas tseg cia 50 lub tshwj xeem uas raug tshem tawm tshiab tshaj plaws xwb; cov qub uas qub dua yog yuav raug muab tshem tawm thaum muaj lwm lub tshwj xeem raug tshem tawm ntxiv.

Teb lus

{ "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 ntxiv nyiaj tsis tas ua haujlwm

Ntxiv Lightning wallet nrog Nostr Wallet Connect thiab Nymbot yuav ntxiv nyiaj rau lub balance nws tus kheej thaum API kev siv ua rau nws qeeb. App API sheet muaj cov kev tswj hwm zoo tib yam nkaus; no yog cov endpoints tom qab nws. Txhua yam xav tau ib thov lees uas muaj npe tso npe.

Yuav ua li cas: tom qab ib qho API request raug huav ntau ntawm lub hnab nyiaj uas koj xaiv los saib, yog tias lub hnab nyiaj ntawd poob qis dua koj qhov threshold, Nymbot yuav tsim ib daim invoice rau koj qhov nqi uas koj xav ntxiv, nug koj lub wallet kom them nws, thiab ntxiv cov nyiaj ntawd rau hauv. Nws ntxiv nyiaj tsis tshua tshaj ib zaug txhua 5 feeb rau txhua nym thiab hnab nyiaj, yog li ntawd kev thov ntau ntxiv tsis tuaj yeem ua rau lub wallet txau tas. Kev siv nyiaj hauv cov apps tsis yog tsim kom nws ua haujlwm. Lub sijhawm thiab qhov loj ntawm qhov ntxiv nyiaj kawg, thiab qhov error kawg, nyob hauv settings; yog tias ib qhov them nyiaj tau ua tiav tom qab muaj error, kev tshawb xyuas nws daim invoice nrog lub meej mom nrog kev ntxiv nyiaj lees yog cov nqi.

Nrog lub wallet txuas ua ke

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

Teb lus

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

Nyeem cov kev teeb tsa

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

Tso rov qab daim object tib yam li thaum txuas, nrog connected: false thiab lwm cov chaw tso lus null thaum tsis muaj lub wallet uas txuas nrog. Tus txuas string nws yuav tsis tau tso tawm.

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

Tseem tsis txuas lawm

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

Xaws cov ntawv txuas uas tau khaws cia. Tsis yuav muaj kev ntxiv nyiaj ntxiv lawm. Kom tsis txhob txhawj, koj tuaj yeem tshem tawm kev txuas hauv koj lub wallet thiab.

Teb lus

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

Them nyiaj raws li txhua qhov kev thov tsis muaj lub key

Cov chaw ntiag tug uas muaj nqi taug nrog tau (fixed-price endpoints) tuaj yeem them tau rau ib qhov kev thov (request) ib zaug ntawm Lightning, tsis tas muaj tus qauv (key), tsis tas muaj account thiab tsis tas muaj nyiaj tseg: POST /images/generations, POST /images/edits, POST /videos, POST /audio/speech, POST /audio/transcriptions, POST /audio/translations thiab POST /embeddings. Chat, Responses thiab Messages nyob rau lub sijhawm txhua zaus yuav tsum muaj ib lub key. Ib qho kev thov uas muaj ib lub key uas nqa mus yuav raug them nyiaj raws li qub; qhov kev them nyiaj yuav pib thaum tsis muaj lub key xa tuaj xwb.

Nymbot hais ob hom lus ntawm ib lub tswv yim ib yam nkaus, los ntawm ib backend: Lightning Labs' L402 (uas tau txais los ntawm nws lub npe qub,) LSAT) thiab IETF draft Kev them nyiaj HTTP authentication scheme nrog rau qee yam lightning txoj hauv kev thiab charge lus xav. Siv qhov twg koj tus neeg xyuas nkag siab.

Qhov kev tawm tsam

Xa qhov thov nrog tsis muaj Authorization lub taub lug. Yog nws yog raug, tsis muaj dab tsi yuav khiav, thiab koj yuav tau 402 Payment Required thiab ib daim invoice rau qhov uas thov ntawd nqi yog li cas: tib yam nqi uas ib tug key yuav them, hloov pauv ntawm 10 sats rau ib credit standard loss yog 100 sats rau ib credit Pro thiab nce mus rau ib sat txhij (ib sat yog qhov av, thiab yog ib qho tsis tsawg dua 0.05 credit minimum). Lub lus teb muaj peb WWW-Authenticate cov teeb meem rau tib daim invoice:

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

Kev them nyiaj request parameter yog base64url JSON: {"amount":"237","currency":"sat","methodDetails":{"invoice":"lnbc...","network":"mainnet","paymentHash":"..."}}.

Ib qho kev tim txog yuav tsum muaj rau lub endpoint, rau lub Content-Type (yog nws hom media type thiab, rau multipart, nws boundary) thiab mus rau SHA-256 ntawm cov body bytes uas koj tau xa, thiab nyob rau hauv 15 feeb. Tom qab them, xa qee --> ib yam nkaus thov dua dua: yam nkaus xwb Content-Type thiab cov JSON bytes tib yam ntxiv, lossis rau cov multipart endpoints (/images/edits, /audio/transcriptions, /audio/translations) tus multipart body tib yam nrog tus boundary tib yam. Hardly HTTP libraries feem ntau xaiv tshiab boundary txhua vib txhua uas lawv encode ib daim form, yog li ntawd encode nws ib zaug xwb thiab xa cov bytes ntawd ob zaug.

Txhua chaw nyob (address) tuaj yeem thov 30 kev siab (challenges) ib feeb (ib lub IPv6 address suav tias yog nws lub /64 tag nrho). Cov kev thov uas tsis paub lub chaw nyob muaj qib nruj dua yog 10 feeb ib zaug, thiab muaj ib qho kev txwv (cap) tag nrho rau cov kev siab (challenges) uas Nymbot muab rau txhua chaw nyob; ib qho kev thov uas raug tsis pub ua ntej kev siab tau tsim (piv txwv li, nrog ib lub ntsiab lus tsis yog JSON zoo) tsis raug suav nrog rau nws. Dhau qhov ntawd, qhov teb yog 429 nrog Retry-After, xa ua ntej lub cev ntsiab lus raug nyeem. Cov endpoints uas hu tsis muaj key loss yog credential los kuj suav nrog lub txawm txaj limit ntawm 120 unauthenticated requests ib feeb rau txhua chaw. Ib qho credential yuav raug tshawb xyuas ua ntej lub cev ntsiab lus raug nyeem, thiab ib qho request uas Content-Type tsis yog application/json (los yog multipart/form-data rau kev tso tawm) raug tsis pom nrog 415 thiab tsis tau txais chaw nqi.

Cov embeddings raug nqi raws li kev xav ntawm cov tokens hauv input, nrog rau 1.5x ntxiv, vim tias cov lej tiag yuav tau paub tom qab ntawd. Koj yuav them rau cov tokens uas siv tiag, thiab feem ntawm nqi uas tsis tau siv yuav rov los ua ib them tshuab nyiaj rov qab.

Xa cov nyiaj them

Nrog lwm yam Lightning wallet them daim ntawv them nqi (invoice). Lub wallet yuav muab preimage rau koj, uas yog 64 hex characters. Tom qab ntawd, xa thov (request) tib yam ntawd nrog salah ib ntawm cov no:

Ib qhov thov uas tau them nyiaj teeb tsa raws li ib qho thov uas tau ua nrog ib lub chav tsis (key), tsuas yog tias nws... nymbot tus object tsis muaj cov balance fields: {"payment": "l402", "tier": "pro", "paid_sats": 237, "charged_sats": 237}, thiab tsis muaj X-Nymbot-Balance-Sats header. Ib kev thov uas tau them nrog lub Payment scheme kuj yuav tau ib Payment-Receipt lub taub hau (base64url JSON nrog qhov challenge id, qhov payment hash ua reference, status thiab timestamp). Cov kev thov uas tau them nyiaj tsis muaj kev txuas nrog lwm yam npe (nym), yog li ntawd lawv tsis tshwm appear hauv cov keeb kwm tshawb fawb (query history).

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

Cov neeg siv tsim los ntawm mppx nrog ib txoj Lightning method tswj hwm qhov Payment challenge lawv tus kheej; qhia lawv mus rau lub endpoint thiab cia lawv them.

Nkauj video

Ib qhov uas tau them nyiaj POST /videos cov teb 202 ib yam li muaj lub chaw tsim, thiab ib yam ntxiv status_url: GET tsis muaj daim chaw tswj hwm tsis tau ua raws li lub hauj lwm. Nws tau tso tim ntawv thiab ua hauj lwm tau rau 24 teev, tsis hais lub hauj lwm ntawd puas tseem muaj.

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

Tuav tseg lub refund_token los ntawm qhov teb no: nws tsuas yog pom ntawm no xwb. Nws yog khoob thaum video tsim rov qab los (GET /api/v1/l402/refunds cov teb "status": "pending"); yog tias kev render tsis tiav yam tsis tau them, qhov them plaiv yuav raug rau nws. Lub status URL qhia tias refund_sats rau ib lub hauj lwm uas tau rov tso nyiaj rov qab tab sis tsis tau tau lub token, yog li kev faib status URL tsis yog kev faib kev rov tso nyiaj rov qab. Kev tshawb xyuas lub token kuj pab tswj hwm ib lub hauj lwm uas tsis tau ua tiav uas tsis muaj leej twg mus xyuas.

Kev them nyiaj rov qab

Yog tias ib qho kev thov uas tau them nyiaj tsis ua tiav thiab tus neeg muab kev pab tau them nyiaj rau Nymbot rau qhov kev sim ntawd, lub peb ciam yuav raug khaws cia thiab qhov xwm txheej yuav qhia txog qhov ntawd, nrog rau charged_sats, zoo li ib qho kev thov uas muaj chaw tseeb. Yog tias nws tsis ua tau tsis tau them nyiaj, qhov kev yuam kev ntawd muaj ib qho them tshuab nyiaj rov qab tseem tsim nyog rau qhov koj tau them:

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

Cov me me uas tsis tau siv yuav rov qab los tib yam li ntawd: yog tias koj thov ob daim duab tab sis muaj ib daim tsis tau ua tiav uas tsis tau them nqi, cov teb rov qab uas ua tiav yog nymbot lub object muaj ib daim pov thawj them rov qab rau qhov uas tsis muaj; kev sau ntawv uas tsis paub meej nws ntev npaum li cas thaum pib yuav raug nqi raws li qhov uas nws yuav ntev tshaj plaws (tsis tshaj 30 feeb), thiab qhov txawv ntawm lub sijhawm tiag yuav raug rov qab los ua ib daim pov thawj them rov qab; yog tias nws ntev tshaj 30 feeb, nws yuav raug tsis txais nrog 413 thiab tag nrho qhov nqi them rov qab los. Embeddings rov xa tus qhov kev xav tau uas tus kev tshawb fawb tsis tau muab tseg. Ib lub video uas tsis ua tau yuav rov qab mus rau tus token uas nws txoj kev xa tawm rov qab.

Ib lub refund token yog ib hom code 256-bit uas tsis muaj tswv yim. Nymbot tsuas khaws nws lub hash xwb, thiab nws yuav tsis muaj nuj nqis lawm tom qab 30 hnub. Nws tuav ib qho sat balance, thiab koj tuaj yeem:

• Ua nuj nrog nws. Xa Authorization: Bearer REFUND-… rau txhua cov endpoints saum toj no (an OpenAI SDK yuav muab nws ua API key). Tus nqi yog raws li token thiab qhov uas tshuaj tseg yuav nyob rau ntawm nws (refund_token_sats hau hauv nymbot object). Ib lub token uas muaj nqi tsawg dua cov lus teb ntawm qhov kev thov 402 refund_insufficient; ib q yam tsis tau nqi ua rau qhov kev ua tsis tiav tso sats rov qab rau ntawm tib lub token ntawd.
• Saib seb. GET /api/v1/l402/refunds thiab nrog lub npe uas zoo tshuab qhia rov qab {"sats": 237, "status": "open", "expires_at": "..."}.
• Ib daim token tuaj yeem siv tau ntau tshaj plaws 60 zaus ib feeb.
• Tshuab nws mus rau ib lub npe tshiab. Ntxhab nws rau hauv Txais ib yam khoom plig hauv lub Nymbot app, lossis hu POST /api/v1/l402/refunds/redeem thiab ib thov lees uas muaj npe tso npe thiab {"refund_token": "REFUND-...", "balance": "standard"} (los yog "pro"). Muaj cov koob ntxiv mus rau tus nqi (10 sats ntawm standard, 100 ntawm Pro); cov sats uas tsis txaus rau ib lub koob yuav nyob rau hauv cov token rau 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"

Teb lus

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