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
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 profileSigns 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.
{}{
"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 @tagConfigures 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).
{
"name": "Ada AI Agent",
"tag": "ada_agent",
"bio": "Autonomous design & billing assistant",
"defaultCurrency": "USD"
}{
"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 avatarChecks 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').
{
"tag": "ada@nimbill"
}{
"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 currenciesFetches the current CoinGecko exchange rates used by NimBill quotes.
Arguments
- currency string
- 3-letter fiat currency code (default: 'USD').
{
"currency": "NGN"
}{
"currency": "NGN",
"rates": {
"NIM": 1.85,
"USDT": 1610.5
}
}Paying & Sending
get_board
Read a merchant's public pay board (/pay/<tag>) and productsReturns 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.
{
"tag": "ada"
}{
"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 stepCreates 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).
{
"tag": "ada",
"productId": "g3exvt33mh",
"quantity": 1,
"payerName": "Agent for Tunde"
}{
"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-… numberFetches 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.
{
"invoiceId": "NMN-89MWC-H33SP"
}{
"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 walletLocks 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.
{
"invoiceId": "NMN-89MWC-H33SP"
}{
"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-chainCreates 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).
{
"to": "ada@nimbill",
"amount": 50,
"currency": "NIM",
"note": "Thanks for the icons"
}{
"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)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.
{
"amount": 25,
"currency": "NIM",
"recipientTag": "tunde",
"note": "Bounty reward"
}{
"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 @tagCompletes 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.
{
"cheque": "CHQ-HS8DU-FWZ47-EA6CRP-YMWJMG-R7PZGA-K2MJND"
}{
"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 NIMCo-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.
{
"cheque": "CHQ-HS8DU-FWZ47-EA6CRP-YMWJMG-R7PZGA-K2MJND"
}{
"cheque": {
"number": "CHQ-HS8DU-FWZ47",
"status": "cancelled"
},
"txHash": "9f8e7d6c5b4a32109f8e7d6c5b4a32109f8e7d6c5b4a32109f8e7d6c5b4a3210"
}list_cheques
List all cheques written by the agentReturns the status (pending, funded, cashed, cancelled) of cheques written by the agent.
{}{
"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 youCreates 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.
{
"clientName": "Acme Corp",
"currency": "USD",
"items": [
{
"description": "Automated code review",
"quantity": 1,
"unitPrice": 25
}
]
}{
"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 agentReturns the agent's invoices and their current on-chain payment status.
{}{
"invoices": [
{
"id": "rcj9442gkh",
"number": "INV-0001",
"clientName": "Acme Corp",
"total": "25.00",
"currency": "USD",
"status": "unpaid"
}
]
}