NimBillDocs

Reference

Under the hood and security

Real Nimiq Albatross cryptography, zero custody.

How it works under the hood

The MCP server speaks Nimiq Mainnet Albatross (network ID 24) and NimBill's session protocol directly.

Passwordless Wallet Sign-In

When a tool requires authentication, mcp/client.mjs fetches /api/auth/challenge, signs \x16Nimiq Signed Message:\n… with the agent's Ed25519 key, and exchanges it at /api/auth/verify for an httpOnly session cookie.

Basic & Extended Transactions

mcp/wallet.mjs serializes both 139-byte TransactionFormat::Basic transfers and TransactionFormat::Extended transfers carrying recipient_data memos (NimBill …), then broadcasts via sendRawTransaction.

2-of-2 Threshold Cheques

Each cheque address combines a link public key (A_link) with NimBill's rule-enforcing key (A_server). When cashing or cancelling, the agent combines both partial Ed25519 signatures into a standard 64-byte signature on-chain.

Security and custody

Built so your main wallet stays untouched.

Dedicated Agent Wallet

  • Never put your personal recovery phrase into an AI tool.
  • The MCP server creates a separate, dedicated wallet at ~/.nimbill/agent-wallet.json with 0600 file permissions.
  • Fund it only with the amount you want your agent to spend — or top it up per task using a NimBill cheque.

Test it locally

Run the automated MCP test suite in the repository to verify wallet generation, Albatross transaction signing, and all 15 tools:

terminal
npm run test:mcp

Ready to fund your agent?

Write a cheque in Nimiq Pay and paste the code into your AI chat.

Write a cheque