NimBillDocs

Set up your AI

Cursor

Add a project rule.

For building NimBill payments into your own app. Save this as .cursor/rules/nimbill.mdc, and Cursor's agent will use it when you ask it to add NimBill checkout, invoices or verification.

Add a project rule

.cursor/rules/nimbill.mdc
---
description: NimBill payments API (pay links, invoices, on-chain verification). Use when adding NimBill payments to this codebase.
alwaysApply: false
---

# NimBill API

Base URL: https://nimbill.mblob.me. JSON in and out, no API key. Errors are { error: { code, message } } with a matching HTTP status.
OpenAPI spec: https://nimbill.mblob.me/openapi.json

## Endpoints
- GET /api/pay/{tag}: Read a board. Start here. Shows who you're paying, what they sell, whether you may pay any amount, which coins they take, and the exact next steps with this board's URLs filled in.
- POST /api/pay/{tag}/invoices: Create an invoice on a board. Turns “I want to buy this” or “I want to pay 25 USD for that” into an invoice the merchant will recognise. Send a productId to buy a product, or amount + currency + description to pay any amount (only when merchant.openAmounts is true).
- GET /api/invoices/{id}: Read an invoice. See an invoice's total and status at any time. Once paid, invoice.payment has the coin, amount, rate and transaction hash. It also finds payments sent without a verify call.
- POST /api/invoices/{id}/quote: Lock the price. Converts the invoice total into an exact coin amount at the live rate (rounded up, so the merchant never gets less) and holds it for 5 minutes. It also tells you where to send it and the memo to attach.
- POST /api/invoices/{id}/verify: Confirm the payment. After sending, report the transaction hash. NimBill reads it from the blockchain and checks the recipient, the amount, the memo and the time before marking the invoice paid. Poll every few seconds until it isn't pending.
- GET /api/tags/{tag}: Look up a tag. Check who owns a tag before money moves: their name, wallet address and whether they take USDT.
- GET /api/rates: Live prices. Price of 1 NIM and 1 USDT in a currency, to show estimates before creating an invoice. Quotes use the same prices.

## Payment flow
1. Read the board (GET /api/pay/{tag}): Who you are paying (merchant.name, merchant.handle), whether any amount is accepted (merchant.openAmounts), which coins are accepted (NIM always, USDT when merchant.acceptsUsdt) and the products for sale with their id, name, price and currency.
2. Create the invoice (POST /api/pay/{tag}/invoices): To pay an amount instead of buying a product (only when merchant.openAmounts is true), send { "amount": 25, "currency": "USD", "description": "<what it is for>", "payerName": "…" }. The answer is { invoice } with invoice.id and invoice.total in invoice.currency.
3. Lock the price (POST /api/invoices/{invoiceId}/quote): Use "USDT" to pay in USDT on Polygon. The answer is { quote } with amount (smallest units: Luna for NIM, 1 NIM = 100000 Luna; 6 decimals for USDT), recipient, memo and expiresAt. The price holds for 5 minutes; ask for a new quote if it runs out.
4. Send the payment: NIM: send a basic transaction of exactly quote.amount Luna to quote.recipient with quote.memo as the transaction data (UTF-8). The memo is how the payment is matched, so it is required. USDT: send an ERC-20 transfer of exactly quote.amount on Polygon to quote.recipient. USDT can't carry a memo, so the exact amount is what identifies the invoice: don't round it. Send before quote.expiresAt.
5. Confirm it (POST /api/invoices/{invoiceId}/verify): Poll every few seconds. status is "pending" until the transaction is in a block, then "paid" with the updated invoice (and its invoice.payment details), or "rejected" with a message. The invoice and its receipt stay at /i/{invoiceId}.

## Implementation notes
- Amounts in quotes are strings in the smallest unit (Luna for NIM: 1 NIM = 100000; 6 decimals for USDT). Use BigInt, never floats.
- Poll verify every 3 to 5 seconds, for up to about 3 minutes. Treat "rejected" as final.
- Never trust a transaction hash on your side alone: the invoice is paid only when verify (or GET /api/invoices/{id}) says status "paid".