Skip to content

Integrating with Nano

If you're looking for details about how to integrate your application or service with Nano, you've come to the right place! There are a variety of ways to do integrations and this documentation is focused on situations requiring custom development. If you are looking for a more plug-and-play option to accept Nano payments or donations, we recommend heading to https://nano.org/accept-nano for some simpler options.

What is needed to integrate?

The most basic integration with Nano will require:

  1. Access to make RPC calls to a Nano node
  2. A method of doing work generation for any blocks created
  3. Some form of a wallet to manage the private/public keys for your accounts

But before jumping in to setup, there are a few best practices and concepts you should be familiar with first:

How transactions work and block specs

Transactions function differently in Nano compared to other blockchains due to the block lattice design. The What is Nano? page gives a quick explanation on how send and receive transactions are related in Nano. As you get into your integration, it is best to be familiar with the block specifications in order to understand how different block subtypes are built and relate to each other.

Account, Key, Seed and Wallet IDs

Knowing how private and public keys are related to seeds and accounts is critical to building a safe and secure integration. With the internal node wallet, there is also a unique wallet ID that adds further security and must be considered if using that wallet for development/testing (see the wallets section below for details). Review the Account, Key, Seed and Wallet IDs section for some additional details.

If you need to generate or manage seeds or mnemonic phrases, see the seeds section for some key information about options as they may differ from other existing projects and standards.

Units

There are two main units used: nano and raw. The ratio is: $$ 1 nano = 10^{30} raw $$

All QR code setups and RPC calls use raw for the amounts, while any human interaction with units is done at the Nano level.

Other concepts

The above concepts capture a minimum understanding to begin your integration journey, and although additional resources will be called out further in the various guides, don't be afraid to check out other resources throughout the documentation here.

Accessing RPC calls

Most integrations send and receive funds by making RPC calls to a Nano node. This requires either access to a public API or running your own node on one of the available networks. Depending on your goals, both are valid approaches with many options and levels of engagement.

Running your own node

Running a node involves installing, configuring and maintaining software on a server, preferably on a stable cloud service for the best performance and uptime. This approach gives you more control at the cost of additional effort.

If going this route, we encourage use of the existing test network for initial integrations. Head over to the Running a node guide and make your way through the overview and security pages before stepping through the node setup guide. Make sure you have "Test network" selected in all the example commands.

Production integration node should be non-voting

When moving to production with a node on the main network, we recommend running dedicated, non-voting node for your integration. If you are interested in running a representative node to help further decentralize the network consensus, please setup a separate node for this purpose to ensure both operate as effectively as possible. See the Voting as a Representative guide for further details.

Public APIs

Access to public APIs for the main network is also available via third-party vendors and community members. These are only available for the main network and are great for quickly testing out a proof-of-concept or prototype using small amounts. If using for production applications caution should be taken when evaluating SLAs and uptime in general.

Wallet

In order to manage private and public keys, accounts, seeds, etc. you will need wallet software. A few potential options are included below, with more user-focused and backend options listed at nanowallets.guide.

Node internal wallet

Node wallet not for production use

The node wallet is not supported for use in production environments. Use third-party or custom key management for production applications.

The official binaries, builds and Docker containers for the Nano node published by the Nano Foundation have an internal wallet available for use in development and testing. This is Qt based wallet with both a GUI and related RPC commands. The following features are available via the GUI:

  • Import wallet and adhoc keys
  • Export seed (automatically generated on startup)
  • Change representatives
  • Send and automatically receive
  • Automatic work generation for transactions (via CPU by default)
  • Manual options for block creation, block processing and initiation of bootstrapping
  • Various advanced options for viewing the ledger, peers, blocks, accounts and statistics

This wallet requires running the node, so after getting your node setup you can follow the wallet setup guide to get started. If building the node yourself, see the Qt wallet notes on the build options guide for how to build the nano_wallet binary in addition to the node.

Pippin

This community built wallet is a production-ready, high performance developer wallet that is setup to be a drop-in replacement for the internal node wallet. Built in Python and optimized for fast response times, this is a good option to explore for any integration. With an open source license, you are encouraged to contribute to its development as well.

Pippin

Nault

This community built wallet is more end-user focused with a robust GUI full of various options. It can be useful in development and testing as it supports setting the custom backend to your own node and can function as a basic account/block explorer. If you use this wallet, it also has an open source license so contributions are encouraged.

Nault

Additional tools

There are plenty of additional libraries and tools worth exploring to help with your integration. Head over the the Developer Tools page on nano.org for a list of commonly used options. Other resources can be explored at the community built nanolinks.info site.

Next steps

If you've made it this far you may have a node running with a wallet setup and have started playing around on the test network. The next steps from here are understanding more about how to handle the various operations most integration require, such as: