NanoBrowserQuest — Technical guide for accepting nano payments

4 min readMar 6, 2022

A lot of community members are building projects and want to start accepting nano payments but are unsure where to start. NBQ is using custom code but there are a handful of open source libraries out there written by nano enthusiasts to inspire your architecture decisions. The reason behind going custom was to have a simple system and granular control over the process without being forced to fork or open PRs on other projects. It took about 2 days to implement the NBQ payment solution so it is far from perfect but does the job for a small scale project or a POC. As the saying goes “use the right tool for the right job”.

NBQ’s tech stack was recently updated to use Typescript and Webpack on both backend and frontend (BQ being a ~2012 game there were no good tool to provide static analysis back then). Having such tools for validating your code is essential to prevent you from doing rookie mistakes and sometimes bug hunting for hours because the wrong value type was passed through your functions.

  • Database: Redis
  • Server: Nodejs & Typescript
  • Client: jQuery, Typescript & Webpack

When a player creates a new NBQ account, an increasing global index that started at 0 is associated and a derived account used for deposits from the deposit seed is created based on the index using the nanocurrency-web-js library from numsu. E.g. the 100th new account will be assigned the index 99 and will have its own deposit account. To re-assemble the transferred funds of the player deposit accounts you can automate a wallet sweeper to reach for certain derived account indexes that received a payment.

A single seed can contain 4,294,967,295 nano_ accounts

A few things to consider:

  • If you peg your items prices to fiat, you’ll have to poll a pricing API (like CoinGecko) at regular intervals and handle the case where the API is not responding or having a fallback solution. Like displaying a “Shop not available” to your users or try a second API like CMC
  • Websocket disconnects, re-add listeners for the ongoing payment sessions
  • You could consider adding a manual “Verify transaction” button in your interface that does a RPC call on the deposit account for the last transaction history in case the socket was disconnected at the exact time the transaction was recorded on the nano node
  • Logging the customer journey though your payment flow is very important for successes and failures handling to keep improving robustness
  • If you are building for the long term, an automated and complete test suite is vital to preserve functionality in-between releases. Don’t only aim for 90–100% coverage but also testing all the possible outcomes. Most of the time you’ll end up finding bugs while writing tests
  • Reporting and monitoring tools for medium to large scale projects. You want to be alerted as soon as the payment system emits a failure to be able to display a notification to your players and provide a fix when possible

NBQ payment service architecture

Most of the complexity comes from handling the socket connection. Nano has a great documentation here so I would recommend getting familiar with it.

When your server connects to a nano node socket you want to be re-subscribing any nano_ accounts for pending payment sessions.

What I refer as a payment session is simply an object stored in memory on the server in the Purchase class.

The player purchase journey (client-side flow)

Fig. 1 — List the items stored in database
Fig. 2 — An item is selected by the player
Fig.3 — Item is purchased

As you can see integrating nano payments into a game or a platform is fairly easy. For larger scale applications you’d want to consider a more complex system with fallbacks on any step that is susceptible of giving intermittent results to have better reliability because after all you want to be giving your users the full benefit of instant payments. In-app cues for new users or people that are not very familiar with sending crypto payments also has to be considered.

Happy coding!