NAV Navbar
shell ruby python javascript

Introduction

Welcome to the Nanotify Docs. You can use the documentation to learn more about how to best use Nanotify for receiving notifications.

We have language bindings in Shell, Ruby, Python, and JavaScript! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Networks

Nanotify supports the below list of networks to receive notifications for:

Nano

The live Nano network.

Endpoint

nano

Pricing

The Nano network incurs the following costs:

The first 100 emails are free and then charged at $1.00 per 100 emails ($0.01 per event).

The first 1000 webhooks are free and then charged at $1.00 per 1000 events ($0.001 per event).

All current API calls are free to use with potential rate limiting applied.

Nano Beta

The Nano Beta network, can be accessed via nano-beta.

Endpoint

nano-beta

Pricing

The Nano beta network incurs the following costs:

The first 100 emails are free and then charged at $1.00 per 100 emails ($0.01 per event).

All webhook events are free from cost.

All current API calls are free to use with potential rate limiting applied.

Watchers

Watchers are the main component of Nanotify's notification system. Clients can create watchers to receive notifications for differente events in the Nano network.

Watchers can be created in two different ways, via the GUI on the Nanotify website, or through the API. To create via the Nanotify API, please ensure that your client has a valid authentication token.

Email

Email watchers will send an email notification for the specified event on the nano network. Emails will be sent from noreply@nanotify.dev and will contain nanotify branding. Emails should be used for personal notifications or buisness notifications such as emails about funds changing from cold storage wallets.

If you wish to have a custom branding featurefor emails in order to send directly to customers then please contact us at support@nanotify.io

Webhook

Webhook watchers will perform a request to a URL given by the client when registering the watcher. These requests will also contain a signed hash of the message to give proof that the request was called by an entity that owns the Nanotify secret key. For more information, see webhooks

Events

Events are what a watcher will respond to. These events consist of discrete actions that take place on the Nano (and Nano Beta) network. Currently Nanotify supports registeration for the following event types:

Receives (Pending)

Pending receives events occur when an account is the recipient of a send block.

Receives (Block)

Receive block events occur when an account sends a receive block to the network in response to a send block.

Send

Send block events occur when a watched account creates and publishes a send block to the network.

Webhooks

The webhook payload

{
  "event": "send",
  "block": "C980D70593B21F09CC8A268B32CEBD9A9960BC4AF9B2CCC13E07FFA795F97104",
  "amount": "783302473000000000000000000000000",
  "address": "nano_185ficg7491tjefanc4753bocqr587z7deau15jrn4g1qew83h9ad3dr1g9s",
  "timestamp": "2020-04-26T12:42:13.123Z",
  "webhook_id": "748165ee-bc71-4ad8-aa8b-ad0bfd1ea793"
}

Nanotify webhook notifications are sent as an HTTP POST request to the callback url given when creating the watcher.

Once you have configured your notification endpoint you’ll receive notifications instantly as events are created according to the setup. You might use notifications to:

Webhook data

Each webhook notification contains the following information in a JSON string under the field data.

This request body is sent as a JSON string so as to allow verification of the signature. For more information see webhook signature.

Webhook signature

Install the relevant package

$ npm install sodium-signatures
$ gem install rbnacl

Code to verify the signature

const publicKey = require('./nanotify-pk.pem')
const signatures = require('sodium-signatures')

function verifyNotification (request) {
  const message = Buffer.from(request.body, 'utf8');
  const signature = Buffer.from(request.headers['Nanotify-Signature'], 'hex');
  const verified = signatures.verify(message, signature, publicKey)
  if (!verified) {
    throw new Error('Message is not signed correctly, treat as malicious')
  }
}
require 'rbnacl'

def verify_notification(request) do
  message = request.body.read
  signature = request.env['HTTP_NANOTIFY_SIGNATURE']
  file_path = '/Path/To/Nanotify/Key.txt'
  nanotify_key = File.read(file_path)
  # Create a VerifyKey object from a public key
  verify_key = RbNaCl::VerifyKey.new(nanotify_key)

  # Check the validity of a message's signature
  # Will raise RbNaCl::BadSignatureError if the signature check fails
  verify_key.verify(signature, message)
end

Each webhook also has a signature associated with the data. The signature is a way to improve the security of the notification by guaranteeing that the payload came from Nanotify and not a malicious third party.

The signature for each request can be found in the requests header Nanotify-Signature.

You can download the Nanotify public key from here: Nanotify public key

Using the Nanotify public key, you can verify the contents of the block using any Nacl library. The signature is derived from the stringified request body. We've provided some simple examples on how to do this with various platforms.

Outage Recovery

A webhook expects to receive a response with an HTTP status code of 200 from the callback URL. If this does not occur then the webhook will operate in outage mode.

In the case of an outage, failure or non 200 code response on the webhook API callback, the Nanotify service will perform further callbacks every 60 seconds, up to a total of 4 additional callbacks or until a 200 status code is received. If, after the 5th attempt, a failure is still reported then a webhook failure event will be logged.

Failed webhooks are priced as one webhook event, even if a call was attempted fives times. Therefore users won't have unexpected charges if their own systems have had an error. In the future, an endpoint will be provided to obtain any failed events that have not been seen by the user so as to allow clients to perform disaster recovery.

Authentication

curl -H "x-api-key: bf839cc2780aba1f2b73ed411fa0c25751abaaef412764e5cae0b45a1228fbc5" \
https://api.nanotify.dev/v1/nano-beta/accounts/nano_1ahd431asgdodw6cdkeaqjxbnku1rnmcmx84mxzr8s843rccicphrti86458/info

Authentication with the Nanotify API takes place using an HTTP header and an API token. To generate the API token, head to the API section in the www.nanotify.dev website whilst logged in. There you will find the API section on the left hand side where you can manage API tokens for your account.

Once you've generated a token and given it a name, make sure you keep it safe and secret. For security reasons, we only show the token the first time you generate it.

To use the token, you must add it as a HTTP header to any requests made to the Nanotify API. This header is the x-api-key header. Please see the examples on how to use for various languages.

Failure to correct apply the authentication token will result in an HTTP response status code of 401

API

The REST API has endpoints for the Nanotify watcher management as well as endpoints for the Nano network data.

Rest API Endpoint URL

Requests

All requests and responses are application/json content type and follow typical HTTP response status codes for success and failure.

In order to interface with the below endpoints, please ensure you have followed the instructions found in authentication.

All api endpoints contain both an API version and a network. The current API version is v1 and the available networks are listed in networks

Request paths are structured like so:

/:version/:network/:endpoint

for example:

/v1/nano-beta/blocks/count

Errors

The Nanotify API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is incorrect.
404 Not Found
500 Internal Server Error -- We had a problem with our server. Try again later.

Success

A successful response is indicated by HTTP status code 200 and may contain an optional body. If the response has a body it will be documented under each resource below.

Pagination

Pagination is not yet implemented in Nanotify, please check back here to see updates.

Rate limits

When a rate limit is exceeded, a status of 429 Too Many Requests will be returned.

REST API

Endpoints

We throttle endpoints by account: 5 requests per second.

Nanotify endpoints

Nanotify management endpoints are available for watcher management, and account management. Every request must include the authentication token for the account as described in authentication.

Email watchers

The below endpoints allow for creating, reading and deactivation of email web watchers.

Create a new email watcher

{
  "account": "nano_116z87m6kd3bn7f7q1h7k87ra9uoq88nw8hw8tt6njq399ph5frmpqac4bep",
  "email": "test@nanotify.dev",
  "event": "pending_receive"
}
curl -X POST \
  -H "x-api-key: <api-key>" \
  -H "content-type: application/json" \
  -d '{"account":"nano_116z87m6kd3bn7f7q1h7k87ra9uoq88nw8hw8tt6njq399ph5frmpqac4bep","email":"test@nanotify.dev","event":"pending_receive"}' \
  https://api.nanotify.dev/v1/nano-beta/emails

Response

{
  "id": "6ece5801-a513-48e8-ae68-8c051ab8ec9b",
  "account": "nano_116z87m6kd3bn7f7q1h7k87ra9uoq88nw8hw8tt6njq399ph5frmpqac4bep",
  "network": "nano-beta",
  "email": "test@nanotify.dev",
  "event": "pending_receive",
  "inserted_at": "2020-04-16T14:41:33.423239Z"
}

Create a new email watcher for the account.

HTTP Request

POST /emails

Request body

Field Description
account The Nano account this watcher is associated with
email The email address to receive any observation notifications
event The event type this watcher is looking for

Response fields

Field Description
id The watcher's internal ID.
account The Nano account this watcher is associated with
network The network that this watcher will watch on.
email The email address to receive any observation notifications
event The event type this watcher is looking for
inserted_at A UTC ISO8601 datetime that this watcher was created at

List active email watchers

curl -H "x-api-key: <api-key>" \
  https://api.develop.nanotify.dev/v1/nano-beta/emails

Response json [ { "id": "6ece5801-a513-48e8-ae68-8c051ab8ec9b", "account": "nano_116z87m6kd3bn7f7q1h7k87ra9uoq88nw8hw8tt6njq399ph5frmpqac4bep", "network": "nano-beta", "email": "test@nanotify.dev", "event": "pending_receive", "inserted_at": "2020-04-16T14:41:33.423239Z" } ]

Get a list of active email watchers for the account.

HTTP Request

GET /emails

Response fields

Field Description
id The watcher's internal ID.
account The Nano account this watcher is associated with
network The network that this watcher will watch on.
email The email address to receive any observation notifications
event The event type this watcher is looking for
inserted_at A UTC ISO8601 datetime that this watcher was created at

Get details of an email watcher

curl -H "x-api-key: <api-key>" \
  https://api.develop.nanotify.dev/v1/nano-beta/emails/6ece5801-a513-48e8-ae68-8c051ab8ec9b

Response

{
  "id": "6ece5801-a513-48e8-ae68-8c051ab8ec9b",
  "account": "nano_116z87m6kd3bn7f7q1h7k87ra9uoq88nw8hw8tt6njq399ph5frmpqac4bep",
  "network": "nano-beta",
  "email": "test@nanotify.dev",
  "event": "pending_receive",
  "inserted_at": "2020-04-16T14:41:33.423239Z"
}

Get an individual email watcher by id for the account.

HTTP Request

GET /emails/:id

Response fields

Field Description
id The watcher's internal ID.
account The Nano account this watcher is associated with
network The network that this watcher will watch on.
email The email address to receive any observation notifications
event The event type this watcher is looking for
inserted_at A UTC ISO8601 datetime that this watcher was created at

Deactivate an email watcher

curl -X DELETE
  -H "x-api-key: <api-key>" \
  https://api.develop.nanotify.dev/v1/nano-beta/emails/6ece5801-a513-48e8-ae68-8c051ab8ec9b

Deactivates an email watcher by id for the account.

HTTP Request

DELETE /emails/:id

Response

OK

Webhook watchers

The below endpoints allow for creating, reading and deactivation of webhook web watchers.

Create a new webhook watcher

{
  "account": "nano_116z87m6kd3bn7f7q1h7k87ra9uoq88nw8hw8tt6njq399ph5frmpqac4bep",
  "url": "https://callback.nanotify.dev/event",
  "event": "pending_receive"
}
curl -X POST \
  -H "x-api-key: <api-key>" \
  -H "content-type: application/json" \
  -d '{"account":"nano_116z87m6kd3bn7f7q1h7k87ra9uoq88nw8hw8tt6njq399ph5frmpqac4bep","url":"https://callback.nanotify.dev/event","event":"pending_receive"}' \
  https://api.nanotify.dev/v1/nano-beta/webhooks

Response

{
  "id": "15d1ba50-6bd1-4239-bafe-4ae7a189543b",
  "account": "nano_116z87m6kd3bn7f7q1h7k87ra9uoq88nw8hw8tt6njq399ph5frmpqac4bep",
  "network": "nano-beta",
  "url": "https://callback.nanotify.dev/event",
  "event": "pending_receive",
  "inserted_at": "2020-04-16T14:41:33.423239Z"
}

Create a new webhook watcher for the account.

HTTP Request

POST /webhooks

Request body

Field Description
account The Nano account this watcher is associated with
url The webhook url to receive any observation notifications
event The event type this watcher is looking for

Response fields

Field Description
id The watcher's internal ID.
account The Nano account this watcher is associated with
network The network that this watcher will watch on.
url The webhook url to receive any observation notifications
event The event type this watcher is looking for
inserted_at A UTC ISO8601 datetime that this watcher was created at

List active webhook watchers

curl -H "x-api-key: <api-key>" \
  https://api.develop.nanotify.dev/v1/nano-beta/webooks

Response json [ { "id": "15d1ba50-6bd1-4239-bafe-4ae7a189543b", "account": "nano_116z87m6kd3bn7f7q1h7k87ra9uoq88nw8hw8tt6njq399ph5frmpqac4bep", "network": "nano-beta", "url": "https://callback.nanotify.dev/event", "event": "pending_receive", "inserted_at": "2020-04-16T14:41:33.423239Z" } ]

Get a list of active webhook watchers for the account for the API key.

HTTP Request

GET /webhooks

Response fields

Field Description
id The watcher's internal ID.
account The Nano account this watcher is associated with
network The network that this watcher will watch on.
url The webhook url to receive any observation notifications
event The event type this watcher is looking for
inserted_at A UTC ISO8601 datetime that this watcher was created at

Get the details of a webhook watcher

curl -H "x-api-key: <api-key>" \
  https://api.develop.nanotify.dev/v1/nano-beta/webhooks/15d1ba50-6bd1-4239-bafe-4ae7a189543b

Response

{
  "id": "15d1ba50-6bd1-4239-bafe-4ae7a189543b",
  "account": "nano_116z87m6kd3bn7f7q1h7k87ra9uoq88nw8hw8tt6njq399ph5frmpqac4bep",
  "network": "nano-beta",
  "url": "https://callback.nanotify.dev/event",
  "event": "pending_receive",
  "inserted_at": "2020-04-16T14:41:33.423239Z"
}

Get an individual webhook watcher by id for the account.

HTTP Request

GET /webhooks/:id

Response fields

Field Description
id The watcher's internal ID.
account The Nano account this watcher is associated with
network The network that this watcher will watch on.
url The webhook url to receive any observation notifications
event The event type this watcher is looking for
inserted_at A UTC ISO8601 datetime that this watcher was created at

Deactivate a webhook watcher

curl -X DELETE
  -H "x-api-key: <api-key>" \
  https://api.develop.nanotify.dev/v1/nano-beta/webhooks/15d1ba50-6bd1-4239-bafe-4ae7a189543b

Deactivates an webhook watcher by id for the account.

HTTP Request

DELETE /webhooks/:id

Response

OK

Network endpoints

Nano network endpoints are available for watcher management, and account management. Every request must include the authentication token for the account as described in authentication.

Accounts

The below endpoints allow for obtaining information about network accounts. Using these methods, once can simulate the read capabilities of a wallet. If you require more endpoints, please email us at support@nanotify.dev

Get account information

curl -H "x-api-key: <api-key>" \
  https://api.develop.nanotify.dev/v1/nano-beta/accounts/nano_1ahd431asgdodw6cdkeaqjxbnku1rnmcmx84mxzr8s843rccicphrti86458/info

Response

{
  "account_version":"2",
  "balance":"122395801037124483159024855697977",
  "block_count":"2527",
  "confirmation_height":"2527",
  "confirmation_height_frontier":"7CAA2805F57CEF4B4785169B1F43C06C04D42044638A323EBE0DF8AB70952736",
  "frontier":"7CAA2805F57CEF4B4785169B1F43C06C04D42044638A323EBE0DF8AB70952736",
  "modified_timestamp":"1587566664",
  "open_block":"C194CB7CE85903BD567C84D2F098B1445C0C14D7E091443D860F4FAECFE0D062",
  "representative_block":"7CAA2805F57CEF4B4785169B1F43C06C04D42044638A323EBE0DF8AB70952736"
}

Obtain information for an account, such as balance, frontier and delegate.

HTTP Request

GET /accounts/:account/info

Response Fields

See Nano RPC documentation

Get account balance

curl -H "x-api-key: <api-key>" \
  https://api.develop.nanotify.dev/v1/nano-beta/accounts/nano_1ahd431asgdodw6cdkeaqjxbnku1rnmcmx84mxzr8s843rccicphrti86458/balance

Response

{
  "balance":"3402744367640054945811236425001",
  "pending":"581459330899809035564071389737976"
}

Returns the current balance for the account.

HTTP Request

GET /accounts/:account/balance

Response Fields

See Nano RPC documentation

Get account pending blocks

curl -H "x-api-key: <api-key>" \
  https://api.develop.nanotify.dev/v1/nano-beta/accounts/nano_1ahd431asgdodw6cdkeaqjxbnku1rnmcmx84mxzr8s843rccicphrti86458/pending

Response

{
  "blocks":[
    "BA0390B5F24A51E8A27835602B795D9BC0E6055661E6D4436E953AD782DD3203",
    "BAACFC4A5791311800616BE96AB995ED33FDB289AD07889A0883234C26DCD1B6"
  ]
}

Returns the confirmed pending blocks for the account.

HTTP Request

GET /accounts/:account/pending

Request Params

All request params should be added as a query string to the request. They are all optional

Param Description
count Number. Determines limit of number of blocks to return.
threshold Number (128 bit, decimal). Returns a list of pending block hashes with amount more or equal to

Response Fields

See Nano RPC documentation

Blocks

Get the network block count

curl -H "x-api-key: <api-key>" \
  https://api.develop.nanotify.dev/v1/nano-beta/blocks/count

Response

{
  "cemented":"24609336",
  "count":"24609336"
}

Gets the current block count on the network.

HTTP Request

GET /blocks/count

Response Fields

See Nano RPC documentation

Get a block by hash

curl -H "x-api-key: <api-key>" \
  https://api.develop.nanotify.dev/v1/nano-beta/blocks/65CF484DFD401ED1D415A9E99871247870B33DE082174AE81F0A33A0445B0FB8

Response

{
  "amount":"19348087035704408511797723417327",
  "balance":"980651912964295591488202276582673",
  "block_account":"nano_1ahd431asgdodw6cdkeaqjxbnku1rnmcmx84mxzr8s843rccicphrti86458",
  "confirmed":"true",
  "contents":"{\n    \"type\": \"state\",\n    \"account\": \"nano_1ahd431asgdodw6cdkeaqjxbnku1rnmcmx84mxzr8s843rccicphrti86458\",\n    \"previous\": \"AC5909937408B4F81FD7C5A1E473245190E9257AAFD068567B637611469F4258\",\n    \"representative\": \"nano_1beta1ayfkpj1tfbhi3e9ihkocjkqi6ms5e4xrbmbybqnkza1e5jrake8wai\",\n    \"balance\": \"980651912964295591488202276582673\",\n    \"link\": \"732D0BDB1F037AB669CB721D83872593FB260CAC4F91AFDCB368868EA0D2B8D6\",\n    \"link_as_account\": \"nano_1wsf3hfjy1utpsnwpwixig5kd6zu6r8crmwjozgd8t68jtif7g8pgbsmg5a6\",\n    \"signature\": \"4D5974E11079CB38A5B676B008490733FE8657259D996B8929C20978B2C13D3D04016BCA8FC69EEBFD76D7F0E77DADFA7405AC6DD87C068A282B402487C13705\",\n    \"work\": \"00000000051563a3\"\n}\n",
  "height":"3518",
  "subtype":"send"
}

Returns a block details by it's hash.

HTTP Request

GET /blocks/:hash

Response Fields

See Nano RPC documentation

Submit a block to the network

curl -H "x-api-key: <api-key>" \
  -H 'Content-Type: application/json' \
  -d '{"subtype":"open","block":{"type":"state","account":"xrb_1ahd431asgdodw6cdkeaqjxbnku1rnmcmx84mxzr8s843rccicphrti86458","previous":"0000000000000000000000000000000000000000000000000000000000000000","representative":"nano_3faucet4t1nnru6yra9iioia76jddur6zqg6d3fp7h1soyyd8qhgx6tizrsy","balance":"1000000000000000000000000000000000","link":"0DA86F52FD9BE3B7F37DBA9CEEFC82EB0508DA5982C9E8D2E6C52A55742C1E7F","link_as_account":"xrb_15fafxbhu8z5pzsqugnwxuya7tr735f7m1pbx5bgfjbccot4r9mzzg1byjmk","work":"0000000002af512c","signature":"AB26229ED94F47CD67DB7216A2B22B3A2854834708BAA0525EE7CB1F12777EB9AD3F217228F1D0AD54F5CA2E3CC89157442D063CD7941F2D34E7574156B35B0E"}}' \
  https://api.develop.nanotify.dev/v1/nano-beta/blocks/process

Response

{
  "hash": "C194CB7CE85903BD567C84D2F098B1445C0C14D7E091443D860F4FAECFE0D062"
}

Submits a block to the network

HTTP Request

POST /blocks/process

Request fields

All request params should be added as a query string to the request. They are all optional

Param Description
subtype String. The subtype of block this is. Helps to prevent accidentally submitting the wrong block type.
block Object. The block data object
Subtypes
Block fields

Below is a description of the fields required for the block data structure for more information please check the nano docs.

Field Description
type String - The block type, typically "state" following the block upgrade epoch
account String - The account address that this block belongs to
previous String - The previous block before this one in the chain
representative String - The representative account that the block account delegates to.
balance String - The balance in raw that this block account will have following confirmation to the network.
link String - A hash of either an account or block that this block is associated with.
link_as_account String - The link hash encoded as base32
work String - A hex encoded string of the proof of work nonce
signature String - The signature of the block hash using the private key of the account

Response fields

Field Description
type String - The hash of the block that was submitted