NimBillDocs

Overview

How an AI pays with NimBill

Teach your assistant to pay with NimBill.

An assistant that can make HTTP requests can pay any NimBill board: it reads the board, makes the invoice and locks the price. Copy one of the setups below once. After that, “pay ada@nimbill for the logo pack” is enough.

Works with

Works with

  • ChatGPT
  • Claude
  • Cursor
  • Grok
  • Gemini
  • Perplexity

…and any agent or program that can make HTTP requests. Logos belong to their owners.

Two ways to pay

Hand it to a person, or pay on its own. Most AI assistants can't hold money, and they shouldn't ask for your keys. So there are two patterns.

Hand-off (most assistants)

  1. The assistant reads the board and creates the invoice.
  2. It locks a quote and shows you who, what and how much.
  3. It gives you the invoice link (/i/{id}) or a nimiq: payment link.
  4. You approve in Nimiq Pay. It checks the invoice until it's paid.

Best for ChatGPT, Claude, Grok, Gemini.

Autonomous (agents with a wallet)

  1. Same first three steps.
  2. The agent signs and sends the payment from its own wallet: NIM with the memo, or USDT on Polygon.
  3. It reports the hash to verify and waits for "paid".

Best for shop backends, bots and agents with a budget.

What the assistant does

These are the steps every setup teaches. A board's own JSON (howToPay) and llms.txt give the same steps, so an assistant that reads either can follow them.

  1. Read the board

    GET https://nimbill.mblob.me/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 https://nimbill.mblob.me/api/pay/{tag}/invoices

    Body
    {"productId":"<a product id>","quantity":1,"payerName":"<who is paying, shown to the merchant>"}

    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 https://nimbill.mblob.me/api/invoices/{invoiceId}/quote

    Body
    {"asset":"NIM"}

    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 https://nimbill.mblob.me/api/invoices/{invoiceId}/verify

    Body
    {"asset":"NIM","txHash":"<transaction hash>"}

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

Set up your AI

Copy one of these once. Each page has the file or instructions to paste.

MCP Server: give your AI agent its own Nimiq wallet

The nimbill-mcp server (on npm) gives your agent its own non-custodial Ed25519 Nimiq wallet (~/.nimbill/agent-wallet.json) and 15 tools to claim a @tag, pay invoices and boards on-chain, send NIM by tag, and write or cash cheques. See the full guide and all 15 tools on /mcp.

mcp.json
{
  "mcpServers": {
    "nimbill": {
      "command": "npx",
      "args": [
        "-y",
        "nimbill-mcp"
      ],
      "env": {
        "NIMBILL_URL": "https://nimbill.mblob.me"
      }
    }
  }
}

Files for agents

They describe the same API, made from the same source as these pages.