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: - Content-Type – application/json
Status Codes: - 201 Created – address created
- 401 Unauthorized – address and access token don’t match
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)
- account_index (int) – the index of wallet’s account for which the new address has to be
generated; default is
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: - Content-Type – application/json
Status Codes: - 200 OK – no error
- 401 Unauthorized – address and access token don’t match
- 404 Not Found – the wallet doesn’t contain specified subaddress
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: - Content-Type – application/json
Status Codes: - 200 OK – no error
- 401 Unauthorized – address and access token don’t match
- 404 Not Found – the wallet doesn’t contain specified subaddress
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)
- expires_in (int) – the address expiration time in seconds; negative value disables
expiration, while
Once you send a payment request with your freshly generated subaddress, expect a payment notification callback.