{"openapi":"3.1.0","info":{"title":"NimBill","version":"1.0.0","description":"Pay NimBill users in NIM or USDT: read a board, create an invoice, lock the price, send the payment from a wallet, then confirm it on-chain. No API key. NimBill never holds funds."},"servers":[{"url":"https://nimbill.mblob.me"}],"paths":{"/api/pay/{tag}":{"get":{"operationId":"getBoard","summary":"Read a board","description":"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.","parameters":[{"name":"tag","in":"path","required":true,"schema":{"type":"string","description":"The tag, with or without @nimbill: ada or ada@nimbill."},"description":"The tag, with or without @nimbill: ada or ada@nimbill."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"merchant":{"tag":"ada","handle":"ada@nimbill","name":"Ada Studio","bio":"Brand designer, Lagos","address":"NQ16 ADMA EM3A 32VA BTBJ SA58 B0FV 909J FQE4","acceptsUsdt":true,"openAmounts":true,"avatarUrl":"/api/avatars/ada?v=1"},"products":[{"id":"g3exvt33mh","name":"Logo pack","description":"3 concepts, 2 rounds of changes","price":"120000.00","currency":"NGN","imageUrl":"/api/products/g3exvt33mh/image?v=1"}],"howToPay":{"assets":["NIM","USDT"],"steps":["…5 steps with URLs…"],"rules":["…"],"docs":"https://…/docs"}}}}},"default":{"description":"404 NOT_FOUND: no one has that tag","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/pay/{tag}/invoices":{"post":{"operationId":"createBoardInvoice","summary":"Create an invoice on a board","description":"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).","parameters":[{"name":"tag","in":"path","required":true,"schema":{"type":"string","description":"The board's tag."},"description":"The board's tag."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["payerName"],"properties":{"payerName":{"type":"string","description":"Who is paying. The merchant sees it on the order. Agents: say who you act for, e.g. “Shop bot for Tunde”."},"productId":{"type":"string","description":"A product id from the board. Use this or amount."},"quantity":{"type":"integer","description":"How many of the product, 1 to 100. Default 1."},"amount":{"type":"number","description":"Amount to pay when not buying a product."},"currency":{"type":"string","description":"Currency of amount, e.g. USD, NGN, EUR.","enum":["USD","EUR","GBP","NGN","KES","GHS","ZAR","XAF","INR","PHP","IDR","BRL","MXN","ARS","TRY","CHF","CAD","AUD","CRC"]},"description":{"type":"string","description":"What the amount is for, up to 120 characters."},"reference":{"type":"string","description":"Pay with NimBill only (signed requests): your own order id, up to 100 characters. Sent back in webhooks; never shown publicly."},"metadata":{"type":"object","description":"Pay with NimBill only: up to 20 string keys and values of your own, sent back in webhooks."},"returnUrl":{"type":"string","description":"Pay with NimBill only: where the payer goes back to after paying. Must be on the store address saved in NimBill."}}},"example":{"productId":"g3exvt33mh","quantity":2,"payerName":"Shop bot for Tunde"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"invoice":{"id":"89mwch33sp","number":"NMN-89MWC-H33SP","merchantName":"Ada Studio","clientName":"Shop bot for Tunde","items":[{"description":"Logo pack","quantity":2,"unitPrice":120000}],"currency":"NGN","total":"240000.00","status":"unpaid","memo":"NimBill 89mwch33sp"}}}}},"default":{"description":"400 VALIDATION: a field is missing or wrong (the message says which); 400 BAD_REQUEST: the board doesn't take open amounts, or reference/metadata/returnUrl were sent without a signature; 401 UNAUTHORIZED: a NimBill-Signature header was sent but doesn't match, is older than 5 minutes, or webhooks are off; 404 NOT_FOUND: no such tag, or the product isn't available; 429 RATE_LIMITED: more than 30 invoices on this board in 10 minutes (300 for the merchant's own signed requests), or more than 10 a minute from one address. Wait RateLimit-Reset seconds","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/invoices/{id}":{"get":{"operationId":"getInvoice","summary":"Read an invoice","description":"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.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The invoice id."},"description":"The invoice id."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"invoice":{"id":"89mwch33sp","number":"INV-0042","status":"paid","total":"240000.00","currency":"NGN","payment":{"asset":"NIM","amount":"75266000","rate":"0.31886","txHash":"8f3c…a91e","paidAt":"2026-11-12T19:20:04.000Z"}},"isOwner":false}}}},"default":{"description":"404 NOT_FOUND: no invoice with that id","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/invoices/{id}/quote":{"post":{"operationId":"createQuote","summary":"Lock the price","description":"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.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The invoice id."},"description":"The invoice id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["asset"],"properties":{"asset":{"type":"string","description":"NIM, or USDT on Polygon (only if the merchant accepts it).","enum":["NIM","USDT"]},"tip":{"type":"number","description":"Optional extra on top, in the invoice currency."}}},"example":{"asset":"NIM"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"quote":{"id":"q1x…","asset":"NIM","amount":"75266000","rate":"0.31886","tip":"0.00","expiresAt":"2026-11-12T19:25:00.000Z","recipient":"NQ16 ADMA EM3A 32VA BTBJ SA58 B0FV 909J FQE4","memo":"NimBill 89mwch33sp"}}}}},"default":{"description":"400 BAD_REQUEST: already paid, cancelled, or USDT not accepted; 503 UPSTREAM: live prices unavailable, try again shortly","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/invoices/{id}/verify":{"post":{"operationId":"verifyPayment","summary":"Confirm the payment","description":"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.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The invoice id."},"description":"The invoice id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["asset","txHash"],"properties":{"asset":{"type":"string","description":"The coin you paid with.","enum":["NIM","USDT"]},"txHash":{"type":"string","description":"The transaction hash: 64 hex characters for NIM, 0x + 64 for Polygon."}}},"example":{"asset":"NIM","txHash":"8f3c…a91e"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"status":"paid","invoice":{"id":"89mwch33sp","number":"INV-0042","status":"paid"}}}}},"default":{"description":"status “pending”: not in a block yet, ask again; status “rejected”: the transaction doesn't pay this invoice (message says why)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/tags/{tag}":{"get":{"operationId":"lookupTag","summary":"Look up a tag","description":"Check who owns a tag before money moves: their name, wallet address and whether they take USDT.","parameters":[{"name":"tag","in":"path","required":true,"schema":{"type":"string","description":"The tag, with or without @nimbill."},"description":"The tag, with or without @nimbill."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"owner":{"tag":"ada","handle":"ada@nimbill","name":"Ada Studio","address":"NQ16 ADMA EM3A 32VA BTBJ SA58 B0FV 909J FQE4","acceptsUsdt":true,"avatarUrl":"/api/avatars/ada?v=1"}}}}},"default":{"description":"404 NOT_FOUND: no one has that tag","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/rates":{"get":{"operationId":"getRates","summary":"Live prices","description":"Price of 1 NIM and 1 USDT in a currency, to show estimates before creating an invoice. Quotes use the same prices.","parameters":[{"name":"currency","in":"query","required":false,"schema":{"type":"string","description":"Fiat currency code. Default USD.","enum":["USD","EUR","GBP","NGN","KES","GHS","ZAR","XAF","INR","PHP","IDR","BRL","MXN","ARS","TRY","CHF","CAD","AUD","CRC"]},"description":"Fiat currency code. Default USD."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"},"example":{"currency":"NGN","rates":{"NIM":0.31886,"USDT":1345.7}}}}},"default":{"description":"400 VALIDATION: unsupported currency; 503 UPSTREAM: live prices unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}}}}