Skip to content

Funding and account

Your token is your account: it has exactly one balance, invoices credit exactly their creating token, and there are no transfers between tokens. If a token is revoked, its remaining balance is stranded (support can re-credit a replacement token manually).

Balance

GET /v1/balance
{"balance_cents": 12300, "spending_cents": 423,
 "period_start": "2026-09-01T00:00:00Z"}

spending_cents is your total debits since the start of the current UTC calendar month (period_start).

Creating an invoice

POST /v1/funding/invoices
{"amount_cents": 2000}

201
{
  "invoice_id": "inv_Qk7...",
  "status": "pending",
  "amount_cents": 2000,
  "checkout_url": "https://btcpay.basegrep.com/i/inv_Qk7...",
  "created_at": "2026-09-17T12:00:00Z",
  "expires_at": "2026-09-17T12:20:00Z"
}
  • Bounds: 500 <= amount_cents <= 10,000,000 (USD cents).
  • Payment is via the checkout_url (Monero). The exact XMR amount is fixed at creation from the then-current rate; complete payment within the invoice window (typically 15–20 minutes).
  • Duplicates are harmless — unpaid invoices simply expire, and only paid invoices credit anything.

Statuses

pending → confirming → paid, or pending → expired. Underpaid invoices end as invalid and are never auto-credited — contact support for a manual resolution. Late or over payments are credited in full.

Poll with GET /v1/funding/invoices/{invoice_id} (or list with GET /v1/funding/invoices, newest first). Paid invoices expose a ledger_id linking to the credit. The checkout page always shows current status, so re-fetching the link is safe at any time.

Ledger

GET /v1/ledger (paginated) is an append-only record. Exactly two entry types:

  • credit — funding (a refund is a credit with order_id set)
  • debit — a search charge

Every charge writes a row, including 0-cent chunks. Your balance at any moment is the latest row's balance_after_cents.