Accepting Loki

Instructions for the Command-Line Interface

The Basics

Loki works a little differently to what you may have become accustomed to from other cryptocurrencies. In the case of a digital currency like Bitcoin and its many derivatives merchant payment systems will usually create a new recipient address for each payment or user.

However, because Loki has stealth addresses there is no need to have separate recipient addresses for each payment or user, and a single account address can be published. Instead, when receiving payments a merchant will provide the person paying with a payment ID.

A payment ID is a hexadecimal string that is 64 characters long, and is normally randomly created by the merchant. An example of a payment ID is:

326d381588ae509bcf35fc8ae05abd31ba1ef885ced2e5c1f2180f28845d1f6f

To generate a payment ID in loki-wallet-cli run the command:

payment_id

Checking for a Payment in loki-wallet-cli

If you want to check for a payment using loki-wallet-cli you can use the payments command followed by the payment ID or payment IDs you want to check:

payments <PID_1> [<PID_2> ... <PID_N>]

For example:

[wallet L6k67F]: payments 4c746dff9f666d6275a60eb6ecbe5078970d5207bc104032f5afa4878eb414e6
                                                             payment                                                         transaction      height               amount     unlock time      addr index
  <4c746dff9f666d6275a60eb6ecbe5078970d5207bc104032f5afa4878eb414e6>  <3fc266d4167060613fba401c65e22e7f01e00045070009b99dd15134b60b47e9>      191878          1.000000000               0               0
[wallet L6k67F]:

If you need to check for payments programmatically, then follow the next section.

Receiving a Payment Step-by-Step

  • Generate a random 64 character hexadecimal string for the payment

  • Communicate the payment ID and Loki address to the individual who is making payment

  • Check for the payment using the "payments" command in loki-wallet-cli

Checking for a Payment Programmatically

In order to check for a payment programmatically you can use the get_payments or get_bulk_payments JSON RPC API calls.

get_payments: this requires a payment_id parameter with a single payment ID.

get_bulk_payments: this is the preferred method, and requires two parameters, payment_ids - a JSON array of payment IDs - and an optional min_block_height - the block height to scan from.

get_payments

Get a list of incoming payments using a given payment id.

Alias: None.

Inputs:

  • payment_id - string; Payment ID used to find the payments (16 characters hex).

Outputs:

  • payments - list of:
    • payment_id - string; Payment ID matching the input parameter.
    • tx_hash - string; Transaction hash used as the transaction ID.
    • amount - unsigned int; Amount for this payment.
    • block_height - unsigned int; Height of the block that first confirmed this payment.
    • unlock_time - unsigned int; Time (in block height) until this payment is safe to spend.
    • subaddr_index - subaddress index:
      • major - unsigned int; Account index for the subaddress.
      • minor - unsigned int; Index of the subaddress in the account.
    • address - string; Address receiving the payment; Base58 representation of the public keys.

Example:

$ curl -X POST http://127.0.0.1:18082/json_rpc -d '{"jsonrpc":"2.0","id":"0","method":"get_payments","params":{"payment_id":"4c746dff9f666d6275a60eb6ecbe5078970d5207bc104032f5afa4878eb414e6"}}' -H 'Content-Type: application/json'
{
  "id": "0",
  "jsonrpc": "2.0",
  "result": {
    "payments": [{
      "address": "LTyHcisBFCGQ6nU3D8wtMj5nr9yZfVBqE5pzrKQak5abBPFMx21r5V57UT33hzzzyLA8yaJFyrcj7iJwiQ8Z1zPeK1a7tpo",
      "amount": 1000000000000,
      "block_height": 127606,
      "payment_id": "4c746dff9f666d6275a60eb6ecbe5078970d5207bc104032f5afa4878eb414e6",
      "subaddr_index": {
        "major": 0,
        "minor": 0
      },
      "tx_hash": "3fc266d4167060613fba401c65e22e7f01e00045070009b99dd15134b60b47e9",
      "unlock_time": 0
    }]
  }
}

get_bulk_payments

Get a list of incoming payments using a given payment id, or a list of payments ids, from a given height. This method is the preferred method over get_payments because it has the same functionality but is more extendable. Either is fine for looking up transactions by a single payment ID.

Alias: None.

Inputs:

  • payment_ids - array of: string; Payment IDs used to find the payments (16 characters hex).
  • min_block_height - unsigned int; The block height at which to start looking for payments.

Outputs:

  • payments - list of:
    • payment_id - string; Payment ID matching one of the input IDs.
    • tx_hash - string; Transaction hash used as the transaction ID.
    • amount - unsigned int; Amount for this payment.
    • block_height - unsigned int; Height of the block that first confirmed this payment.
    • unlock_time - unsigned int; Time (in block height) until this payment is safe to spend.
    • subaddr_index - subaddress index:
      • major - unsigned int; Account index for the subaddress.
      • minor - unsigned int; Index of the subaddress in the account.
    • address - string; Address receiving the payment; Base58 representation of the public keys.

Example:

$ curl -X POST http://127.0.0.1:18082/json_rpc -d '{"jsonrpc":"2.0","id":"0","method":"get_bulk_payments","params":{"payment_ids":["60900e5603bf96e3"],"min_block_height":"120000"}}' -H 'Content-Type: application/json'
{
  "id": "0",
  "jsonrpc": "2.0",
  "result": {
    "payments": [{
      "address": "LTyHcisBFCGQ6nU3D8wtMj5nr9yZfVBqE5pzrKQak5abBPFMx21r5V57UT33hzzzyLA8yaJFyrcj7iJwiQ8Z1zPeK1a7tpo",
      "amount": 1000000000000,
      "block_height": 127606,
      "payment_id": "4c746dff9f666d6275a60eb6ecbe5078970d5207bc104032f5afa4878eb414e6",
      "subaddr_index": {
        "major": 0,
        "minor": 0
      },
      "tx_hash": "3fc266d4167060613fba401c65e22e7f01e00045070009b99dd15134b60b47e9",
      "unlock_time": 0
    }]
  }
}

It is important to note that the amounts returned are in base Loki units and not in the display units normally used in end-user applications. Also, since a transaction will typically have multiple outputs that add up to the total required for the payment, the amounts should be grouped by the tx_hash or the payment_id and added together. Additionally, as multiple outputs can have the same amount, it is imperative not to try and filter out the returned data from a single get_bulk_payments call.

Before scanning for payments it is useful to check against the daemon RPC API (the get_info RPC call) to see if additional blocks have been received. Typically you would want to then scan only from that received block on by specifying it as the min_block_height to get_bulk_payments.

Programatically Scanning for Payments

  • Get the current block height from the daemon, only proceed if it has increased since our last scan.

  • Call the get_bulk_payments RPC API call with our last scanned height and the list of all payment IDs in our system

  • Store the current block height as our last scanned height

  • Remove duplicates based on transaction hashes we have already received and processed

Sources

https://ww.getmonero.org/get-started/accepting/

https://src.getmonero.org/resources/developer-guides/wallet-rpc.html