csleary/nem-payments

Returns an object including a list of confirmed NEM payments made using an identifying message/ID string for a particular address, as well as a payment total and the NEM node used.

nem-payments

NEM payments is an easy to use module that returns an object (via a promise) containing a list of confirmed NEM transactions for a given NEM address. Only transactions that make use of a given message string in the transactions' 'message' field will be returned. A combined total of all payments made to the address using this message is also included (useful for payment confirmation and order fulfilment).

Installation

First install the module as you would any other:

$ npm i nem-payments

Import the module:

const nemPayments = require('nem-payments');

Usage

In its simplest form, your argument takes the form of three string parameters: a NEM address, a text message to look for, and optionally the node you wish to use for the query. If you don't specify a node URL it will carry out the query using the node http://62.75.163.236 (i.e. Alice3, chosen for no particular reason) by default. Note: you need to include the protocol in the node address.

The NEM address will automatically have have its dashes removed.

(async () => {
  const payments = await nemPayments(
    'NAER66-DXCNYE-BNMTWA-PKG7CU-27CMUP-TQQDSM-2KL6',
    'Hello World!',
    'http://62.75.163.236'
  ).catch(err => console.error(err));

  console.log(payments);
})();

For more control over the results, you may instead use an options object in place of the node string. This options object features a NEM node address string, and additional integer parameters to limit either/both of the numbers of transactions searched, and the number of positive results to return, respectively.

By default nem-payments will page through the entire history of an address's incoming transactions, so for accounts with a large number of transactions this might take a while. For payment/checkout flows you would typical only be interested in recent payments, and so might initially elect to limit the results of a search.

For example, if we needed to search through an exchange address for recent depositors who have forgotten to include their ID message, we can search for an empty string and limit the scope of our query with the searchLimit and maxResults parameters (here we haven't specified a node, so the default is used):

const options = {
  searchLimit: 250,
  maxResults: 10
};

const payments = await nemPayments(
  'NC64UF-OWRO6A-VMWFV2-BFX2NT-6W2GUR-K2EOX6-FFMZ',
  '',
  options
).catch(err => console.error(err));

Finally, you can also return a number of the most recent transactions by passing a non-string argument for the message parameter, bypassing the message filter entirely (for the sake of brevity, here we've limited the amount of transactions to search through):

const options = {
  searchLimit: 200
};

const payments = await nemPayments(
  'NC64UF-OWRO6A-VMWFV2-BFX2NT-6W2GUR-K2EOX6-FFMZ',
  null,
  options
);

Dependencies

nem-payments makes use of the NEM SDK (nem-sdk) to fetch incoming transactions.

There are also a couple of utility functions included to return a sum total of payments and filter out transactions that are either non-transfer transactions, or do not contain the message we're searching for. This filter transaction supports both standard and multisignature transactions, as the transaction objects for these differ in structure.