Generating addresses for payments

One of the basic services of Vigla is address generation. The idea is to generate a new one-time address for each expected payment. It makes accounting easier and elevates privacy. Without access to wallet keys it’s impossible to figure out if two addresses belong to the same wallet.

Basics

Monero wallets can be divided into separate accounts and each account may have multiple addresses. Up to 2^23 accounts are allowed, each containing up to 2^32 addresses.

Accounts and addresses are indexed by integer numbers. Account number is sometimes called major index and address index within the account a minor index.

The first address you see just after having created a new wallet is often called main or master address. It has (major, minor) index equivalent to (0,0). All further addresses are usually called subaddresses although for most uses these terms are interchangeable.

Expiration time

Each subaddress generated by Vigla may have expiration time. It doesn’t affect flow of funds, only describes for how long Vigla should monitor it for incoming payments.

Note

Because checking every active address for incoming funds requires constant computational effort at our servers, it is very likely that after the Beta phase we will charge additional fee for wallets with high volume of active addresses.

Requesting an address

A new address is requested by calling the following endpoint. Account index, as well as expiration time may be specified.

POST /address/new/

Generates a new subaddress and starts monitoring it immediately

Example request:

requests.post(
    "https://api.vigla.biz/address/new/",
    auth=HTTPBasicAuth(
        "56eDKfprZtQGfB4y6gVLZx5naKVHw6KEKLDoq2WWtLng9ANuBvsw67wfqyhQECoLmjQN4cKAdvMp2WsC5fnw9seKLcCSfjj",
        "b690d2d2-80cf-41f1-a2c8-29972c076d24"))

Example response:

{
  "account_index": 0,
  "active": true,
  "active_until": null,
  "address": "79qwF2b6r5VA9oCJwwX5TdPeGtUqkWfBTfivzQ5yRrWDiGNAnCPWc98dhufqonDjMce65HMrajDV94QPk4frvCGaKJqEVpD",
  "subaddr_index": 257
}
Request JSON Object:
 
  • account_index (int) – the index of wallet’s account for which the new address has to be generated; default is 0, the main account
  • expires_in (int) – the address expiration time in seconds; default is null which means no expiration
Response Headers:
 
Status Codes:
Response JSON Object:
 
  • account_index (int) – the index of wallet’s account the address belongs to (also known as major index)
  • active (boolean) – flag indicating whether the address is being actively monitored for incoming payments
  • active_until (datetime) – the time when address becomes inactive (in UTC) or null when it has no expiration time
  • address (string) – the newly generated address itself
  • subaddr_index (int) – the index of the subaddress within the wallet’s account (also known as minor index)

Warning

Vigla monitors only those subaddresses which have been generated through the API. You are still free to run a copy of the wallet and generate more addresses there, but you won’t be notified about the incoming payments.

Monitoring the master address

Each time you spend funds from the wallet, a change output is generated. If the change is non-zero, it is directed back to your wallet’s master address.

By default, the master address is not being monitored by Vigla. You may change that behavior in wallet settings but please be aware of the implications. Also, with the principle of one-time addresses (which we strongly recommend), you should never receive any funds from your customers to the master address.

Address check and update

You may always check the status of existing subaddress. The result is very similar to that described above. It is also possible to modify the expiration time of a subaddress.

GET /address/(string: address)/

Returns the status of existing subaddress

Example request:

requests.get(
    "https://api.vigla.biz/address/75KLTYoKwsTFGBMSHg8AhD8MTxP4oz9JK2YgSF8RAhPsFgnkrJFbqEpRVdFwceyVtUhq1xHagUyqBAFEXJ4oBGRvDc54YXa/",
    auth=HTTPBasicAuth(
        "56eDKfprZtQGfB4y6gVLZx5naKVHw6KEKLDoq2WWtLng9ANuBvsw67wfqyhQECoLmjQN4cKAdvMp2WsC5fnw9seKLcCSfjj",
        "b690d2d2-80cf-41f1-a2c8-29972c076d24"))

Example response:

{
  "account_index": 0,
  "active": true,
  "active_until": null,
  "address": "75KLTYoKwsTFGBMSHg8AhD8MTxP4oz9JK2YgSF8RAhPsFgnkrJFbqEpRVdFwceyVtUhq1xHagUyqBAFEXJ4oBGRvDc54YXa",
  "subaddr_index": 265
}
Response Headers:
 
Status Codes:
Response JSON Object:
 
  • account_index (int) – the index of wallet’s account the address belongs to (also known as major index)
  • active (boolean) – flag indicating whether the address is being actively monitored for incoming payments
  • active_until (datetime) – the time when address becomes inactive (in UTC) or null when it has no expiration time
  • address (string) – the subaddress itself
  • subaddr_index (int) – the index of the subaddress within the wallet’s account (also known as minor index)
PUT /address/(string: address)/

Modifies existing subaddress. Currently it’s only possible to modify the expiration time or to disable the expiration completely.

Example request:

requests.put(
    "https://api.vigla.biz/address/75KLTYoKwsTFGBMSHg8AhD8MTxP4oz9JK2YgSF8RAhPsFgnkrJFbqEpRVdFwceyVtUhq1xHagUyqBAFEXJ4oBGRvDc54YXa",
    data={"expires_in": 60*60*24,
    auth=HTTPBasicAuth(
        "56eDKfprZtQGfB4y6gVLZx5naKVHw6KEKLDoq2WWtLng9ANuBvsw67wfqyhQECoLmjQN4cKAdvMp2WsC5fnw9seKLcCSfjj",
        "b690d2d2-80cf-41f1-a2c8-29972c076d24"))

Example response:

{
  "account_index": 0,
  "active": true,
  "active_until": "2020-02-22T14:29:22.277227",
  "address": "75KLTYoKwsTFGBMSHg8AhD8MTxP4oz9JK2YgSF8RAhPsFgnkrJFbqEpRVdFwceyVtUhq1xHagUyqBAFEXJ4oBGRvDc54YXa",
  "subaddr_index": 265
}
Request JSON Object:
 
  • expires_in (int) – the address expiration time in seconds; negative value disables expiration, while 0 makes the address expire immediately
Response Headers:
 
Status Codes:
Response JSON Object:
 
  • account_index (int) – the index of wallet’s account the address belongs to (also known as major index)
  • active (boolean) – flag indicating whether the address is being actively monitored for incoming payments
  • active_until (datetime) – the time when address becomes inactive (in UTC) or null when it has no expiration time
  • address (string) – the subaddress itself
  • subaddr_index (int) – the index of the subaddress within the wallet’s account (also known as minor index)

Once you send a payment request with your freshly generated subaddress, expect a payment notification callback.