NimBillDocs

Reference

All 15 MCP tools

Complete tool & resource reference.

Every tool exposed by mcp/index.mjs over tools/list and tools/call, plus the nimbill://wallet resource.

nimbill://wallet resource

nimbill://walletMCP Resource

Read-only JSON resource exposing the agent's NQ… address, public key, live on-chain NIM balance, and signed-in NimBill profile so MCP hosts can attach wallet context automatically.

Wallet & Identity

wallet_status

Check the agent's NQ… address, live NIM balance, and @tag profile
Wallet & Identity

Signs in to NimBill automatically with the agent's Ed25519 keypair, queries the Nimiq blockchain for its live NIM balance, and returns the agent's address, public key, and NimBill profile.

Tool arguments
{}
Tool response
{
  "address": "NQ16 KRF9 5C6V 395Q AK21 CM01 P6HM HUE4 RPGS",
  "publicKey": "e26b57d8e5f86ec9dce235fd9da5b3b13ab5d7102bb8ae370de98bf8c104a668",
  "walletSource": "~/.nimbill/agent-wallet.json",
  "balance": {
    "nim": 250,
    "luna": "25000000",
    "formatted": "250 NIM"
  },
  "profile": {
    "name": "Ada AI Agent",
    "tag": "ada_agent",
    "handle": "ada_agent@nimbill",
    "boardUrl": "https://nimbill.app/pay/ada_agent",
    "displayCurrency": "USD"
  }
}

setup_profile

Set the agent's display name, bio, currency, and claim its @tag
Wallet & Identity

Configures the agent's NimBill merchant account and claims a public @tag (like ada_agent@nimbill) so people or other agents can pay it by tag or on its public board.

Arguments

name stringrequired
Display name shown on invoices, cheques, and your board.
tag string
NimBill tag to claim (3–20 lowercase letters, digits, or single underscores).
bio string
Short bio shown on the agent's public pay board (up to 160 chars).
defaultCurrency string
3-letter display currency code (e.g. USD, NGN, EUR).
Tool arguments
{
  "name": "Ada AI Agent",
  "tag": "ada_agent",
  "bio": "Autonomous design & billing assistant",
  "defaultCurrency": "USD"
}
Tool response
{
  "merchant": {
    "address": "NQ16 KRF9 5C6V 395Q AK21 CM01 P6HM HUE4 RPGS",
    "name": "Ada AI Agent",
    "tag": "ada_agent",
    "bio": "Autonomous design & billing assistant",
    "displayCurrency": "USD"
  },
  "handle": "ada_agent@nimbill",
  "boardUrl": "https://nimbill.app/pay/ada_agent"
}

lookup_tag

Resolve any @tag to its owner's name, Nimiq address, and avatar
Wallet & Identity

Checks who owns a NimBill tag before sending money, writing a tag-locked cheque, or paying a board.

Arguments

tag stringrequired
The NimBill tag to look up (e.g. 'ada' or 'ada@nimbill').
Tool arguments
{
  "tag": "ada@nimbill"
}
Tool response
{
  "owner": {
    "tag": "ada",
    "handle": "ada@nimbill",
    "name": "Ada Studio",
    "address": "NQ16 ADMA EM3A 32VA BTBJ SA58 B0FV 909J FQE4",
    "avatarUrl": "/api/avatars/ada?v=1"
  }
}

get_rates

Live NIM and USDT prices in 19 supported local currencies
Wallet & Identity

Fetches the current CoinGecko exchange rates used by NimBill quotes.

Arguments

currency string
3-letter fiat currency code (default: 'USD').
Tool arguments
{
  "currency": "NGN"
}
Tool response
{
  "currency": "NGN",
  "rates": {
    "NIM": 1.85,
    "USDT": 1610.5
  }
}

Paying & Sending

get_board

Read a merchant's public pay board (/pay/<tag>) and products
Paying & Sending

Returns the merchant's profile, listed products with prices, whether open amounts are accepted, and step-by-step payment instructions.

Arguments

tag stringrequired
The merchant's @tag.
Tool arguments
{
  "tag": "ada"
}
Tool response
{
  "merchant": {
    "tag": "ada",
    "handle": "ada@nimbill",
    "name": "Ada Studio",
    "address": "NQ16 ADMA EM3A 32VA BTBJ SA58 B0FV 909J FQE4",
    "openAmounts": true
  },
  "products": [
    {
      "id": "g3exvt33mh",
      "name": "Logo pack",
      "price": "120000.00",
      "currency": "NGN"
    }
  ]
}

buy_from_board

Create an order on /pay/<tag> and pay it on-chain in one step
Paying & Sending

Creates an invoice on a merchant's public board (either buying a product by productId or paying an open amount), locks a 5-minute NIM quote, signs and broadcasts the Extended Nimiq transaction with the 'NimBill <id>' memo, and verifies it on-chain.

Arguments

tag stringrequired
The merchant's @tag.
payerName stringrequired
Who is paying (e.g. 'Agent for Tunde').
productId string
Product ID from get_board when buying a product.
quantity integer
Quantity of the product (1–100, default 1).
amount number
Amount when paying an open amount.
currency string
Currency code for an open amount (e.g. USD, NGN).
description string
What the open amount is for.
payNow string
Boolean (default false): only create the invoice. Set true to pay it on-chain right away (spending limits apply).
Tool arguments
{
  "tag": "ada",
  "productId": "g3exvt33mh",
  "quantity": 1,
  "payerName": "Agent for Tunde"
}
Tool response
{
  "invoice": {
    "id": "89mwch33sp",
    "number": "NMN-89MWC-H33SP",
    "total": "120000.00",
    "currency": "NGN"
  },
  "payment": {
    "txHash": "73e7ca24ac6645601c7c13a03f81d942a0489950018ea5074be41c6ed4a59201",
    "explorerUrl": "https://nimiq.watch/#73e7ca24ac6645601c7c13a03f81d942a0489950018ea5074be41c6ed4a59201",
    "amountNim": 648.65,
    "verificationStatus": "confirmed",
    "receiptUrl": "https://nimbill.app/i/89mwch33sp/receipt"
  }
}

get_invoice

Read any NimBill invoice by ID, link, or NMN-… number
Paying & Sending

Fetches the full public details of an invoice (merchant, line items, total, status, and payment receipt if paid).

Arguments

invoiceId stringrequired
Invoice ID, URL, or NMN-XXXXX-XXXXX number.
Tool arguments
{
  "invoiceId": "NMN-89MWC-H33SP"
}
Tool response
{
  "invoice": {
    "id": "89mwch33sp",
    "number": "INV-0004",
    "nimbillNumber": "NMN-89MWC-H33SP",
    "merchantName": "Ada Studio",
    "total": "120000.00",
    "currency": "NGN",
    "status": "unpaid"
  },
  "url": "https://nimbill.app/i/89mwch33sp"
}

pay_invoice

Pay an unpaid NimBill invoice on-chain from the agent's wallet
Paying & Sending

Locks a 5-minute NIM price quote on the invoice, builds and signs a Nimiq Albatross Extended transaction with the 'NimBill <id>' memo, broadcasts it to the Nimiq network, and verifies the payment with NimBill.

Arguments

invoiceId stringrequired
Invoice ID, URL, or NMN-… number.
tip number
Optional tip in the invoice's currency.
dryRun string
Boolean. If true, locks the quote and signs the transaction locally without broadcasting.
Tool arguments
{
  "invoiceId": "NMN-89MWC-H33SP"
}
Tool response
{
  "txHash": "73e7ca24ac6645601c7c13a03f81d942a0489950018ea5074be41c6ed4a59201",
  "explorerUrl": "https://nimiq.watch/#73e7ca24ac6645601c7c13a03f81d942a0489950018ea5074be41c6ed4a59201",
  "amountNim": 648.65,
  "verificationStatus": "confirmed",
  "invoiceUrl": "https://nimbill.app/i/89mwch33sp",
  "receiptUrl": "https://nimbill.app/i/89mwch33sp/receipt"
}

send_to_tag

Send NIM to someone's @tag and verify on-chain
Paying & Sending

Creates a tag transfer (denominated in NIM or any supported fiat currency), signs and broadcasts the on-chain Nimiq transaction with the 'NimBill TX <id>' memo, and verifies it.

Arguments

to stringrequired
Recipient's @tag (e.g. 'ada' or 'ada@nimbill').
amount numberrequired
Amount to send.
currency stringrequired
'NIM' or a 3-letter fiat currency code like 'USD' or 'NGN'.
note string
Optional short note (up to 80 characters).
Tool arguments
{
  "to": "ada@nimbill",
  "amount": 50,
  "currency": "NIM",
  "note": "Thanks for the icons"
}
Tool response
{
  "txHash": "a2b08ef31b57c8d90123456789abcdef0123456789abcdef0123456789abcdef",
  "explorerUrl": "https://nimiq.watch/#a2b08ef31b57c8d90123456789abcdef0123456789abcdef0123456789abcdef",
  "verificationStatus": "paid"
}

Cheques

write_cheque

Write and fund a non-custodial 2-of-2 cheque (free or locked to a @tag)
Cheques

Generates a 24-character cheque secret locally, derives the client half of the 2-of-2 Ed25519 key, registers the cheque on NimBill, funds the combined cheque address on-chain from the agent's wallet, and returns the shareable claim link and CHQ-… code.

Arguments

amount numberrequired
Cheque amount.
currency string
'NIM' or a 3-letter fiat currency code (default: 'NIM').
recipientTag string
Optional @tag to lock the cheque to. Omit for a free cheque anyone can claim.
note string
Optional note shown on the face of the cheque.
Tool arguments
{
  "amount": 25,
  "currency": "NIM",
  "recipientTag": "tunde",
  "note": "Bounty reward"
}
Tool response
{
  "cheque": {
    "id": "hs8dufwz47",
    "number": "CHQ-HS8DU-FWZ47",
    "chequeAddress": "NQ42 8B1C 9K2M 7P4Q 3R5S 6T8V 1X2Y 4A5B 9C0D",
    "amount": "2500000",
    "status": "funded"
  },
  "claimUrl": "https://nimbill.app/c/hs8dufwz47#ea6crpymwjmgr7pzgak2mjnd",
  "chequeCode": "CHQ-HS8DU-FWZ47-EA6CRP-YMWJMG-R7PZGA-K2MJND",
  "funding": {
    "fundedOnChain": true,
    "status": "funded"
  }
}

cash_cheque

Cash a cheque link or CHQ-… code on-chain into the agent's wallet or any @tag
Cheques

Completes the 2-of-2 Ed25519 threshold signature with the NimBill server and broadcasts the 139-byte Basic transaction sweeping the cheque's NIM straight to the destination wallet. Works even when the agent's own wallet has 0 NIM!

Arguments

cheque stringrequired
Full cheque URL (with #<secret>) or full CHQ-XXXXX-XXXXX-XXXXXX-… code.
toTagOrAddress string
Optional @tag or NQ… address to receive the funds (defaults to the agent's wallet).
claimerName string
Optional name shown to the cheque writer.
Tool arguments
{
  "cheque": "CHQ-HS8DU-FWZ47-EA6CRP-YMWJMG-R7PZGA-K2MJND"
}
Tool response
{
  "cheque": {
    "number": "CHQ-HS8DU-FWZ47",
    "status": "cashed"
  },
  "txHash": "6ea82e8a926cd8e3babb8f696e0cacf0c8df18ff5f0a25cee50e5d374284739a",
  "explorerUrl": "https://nimiq.watch/#6ea82e8a926cd8e3babb8f696e0cacf0c8df18ff5f0a25cee50e5d374284739a",
  "recipientAddress": "NQ16 KRF9 5C6V 395Q AK21 CM01 P6HM HUE4 RPGS"
}

cancel_cheque

Cancel an uncashed cheque written by the agent and reclaim the NIM
Cheques

Co-signs a cancellation transaction returning the cheque's full NIM balance back to the agent's wallet.

Arguments

cheque stringrequired
Full cheque URL (with #<secret>) or full CHQ-… code.
Tool arguments
{
  "cheque": "CHQ-HS8DU-FWZ47-EA6CRP-YMWJMG-R7PZGA-K2MJND"
}
Tool response
{
  "cheque": {
    "number": "CHQ-HS8DU-FWZ47",
    "status": "cancelled"
  },
  "txHash": "9f8e7d6c5b4a32109f8e7d6c5b4a32109f8e7d6c5b4a32109f8e7d6c5b4a3210"
}

list_cheques

List all cheques written by the agent
Cheques

Returns the status (pending, funded, cashed, cancelled) of cheques written by the agent.

Tool arguments
{}
Tool response
{
  "cheques": [
    {
      "id": "hs8dufwz47",
      "number": "CHQ-HS8DU-FWZ47",
      "status": "funded",
      "amount": "2500000"
    }
  ]
}

Invoicing

create_invoice

Create a new invoice so a client or another agent can pay you
Invoicing

Creates an invoice in any of NimBill's 19 supported currencies and returns the shareable link and NMN-… number.

Arguments

clientName stringrequired
Client's name.
currency stringrequired
3-letter currency code (e.g. USD, NGN, EUR).
items stringrequired
Array of { description, quantity, unitPrice } line items.
dueDate string
Optional due date (YYYY-MM-DD).
note string
Optional note on the invoice.
Tool arguments
{
  "clientName": "Acme Corp",
  "currency": "USD",
  "items": [
    {
      "description": "Automated code review",
      "quantity": 1,
      "unitPrice": 25
    }
  ]
}
Tool response
{
  "invoice": {
    "id": "rcj9442gkh",
    "number": "INV-0001",
    "nimbillNumber": "NMN-RCJ94-42GKH",
    "total": "25.00",
    "currency": "USD"
  },
  "url": "https://nimbill.app/i/rcj9442gkh"
}

list_invoices

List all invoices created by the agent
Invoicing

Returns the agent's invoices and their current on-chain payment status.

Tool arguments
{}
Tool response
{
  "invoices": [
    {
      "id": "rcj9442gkh",
      "number": "INV-0001",
      "clientName": "Acme Corp",
      "total": "25.00",
      "currency": "USD",
      "status": "unpaid"
    }
  ]
}