Introduction

As an API user, you can create only non-custodial wallet from Venly's perspective. If you wish to create custodial wallets then you need to take ownership of the PIN code required to access wallets. This way you can be the custodial while your end-users will be non-custodial.

If you are creating wallets for your users, you can provide them with additional means of recovery called “signing methods”. Signing methods are used to unlock the wallet.

Signing methods are created per user, meaning that you have to create a user (normally one for each end user you have) and then make sure that the signing methods and the wallets created in the future are linked to this user.

The signing methods will allow users to:

1. Access the wallets linked to them
2. Recover their PIN, if lost
3. Sign signature requests
4. Execute transactions

Types of Signing Methods

There are currently three types of signing methods available - PIN, emergency code, and biometric signing method.

PIN

The PIN should always be the first signing method when you create a wallet. After that, you can create other signing methods that can be used for recovery of PIN, signing transactions, etc.

The user will be able to use other signing methods to recover their PIN, or the other way round - each of the signing methods can be updated with another valid signing method.

The PIN signing method should contain 6 digits. A user can have only one PIN signing method.

Once it’s set up, it can be used by providing the PIN code:

• In the header with the Signing-Method parameter as id:value
• In the request body with the pincode parameter (DEPRECATED)

Emergency Code

The EMERGENCY_CODE signing method should be 25 characters long and have at least 128 bits of entropy. A user can have only one emergency code.

When creating it, you can specify the value (25 characters), or you can leave it out of the request body. If you don’t specify it, we will generate a code with the required entropy and you’ll receive it in the response.

When creating the emergency code, you can specify it as follows or just specify the type to autogenerate an emergency code.

{
    "type": "EMERGENCY_CODE",
    "value": "w2v7yertaad21lhudqghzwcg4"
}  

📘

Emergency code should be 25 characters long. If you remove the value parameter, the API will auto generate the code for you.

Once it’s set up, it can be used by providing the emergency code:

• In the header with the Signing-Method parameter as id:value

Biometric

When creating the BIOMETRIC signing method, it should contain:

• The value of the biometrics you want to set up (for example, Face ID or Touch ID)
• The physicalDeviceId which is the unique ID of the user's device

When creating the biometric signing method, you can specify it as:

{
    "type": "BIOMETRIC",
    "value": "2f08ae38-b3b9-4857-b46e-3b20e1a936f8",
    "physicalDeviceId": "312b26a0-e6de-4d33-a011-c17cd5fb5e7f"
}    

Once it’s set up, it can be used:

• In the header with the Signing-Method parameter as id:value

🚧

Once the signing methods are set up, there is no way for their value to be retrieved again through the Venly API. That’s why you should make sure that your end users have stored them securely (unless you’re building a custodial solution where you’re storing them).

Where and How to Use Signing Methods?

The signing methods, which are PIN, EMERGENCY_CODE, and BIOMETRIC, can be used as shown below.

Request Body (DEPRECATED)

In the body, with the pincode property

🚧

This applies only to the PIN signing method. (DEPRECATED)

{
  "pincode": "123456", //deprecated
  "description": "string",
  "secretType": "AETERNITY"

Header

Passing the Signing-Method parameter through the header with value: id:value

• id: This is the ID of the signing method
• value: This is the value of the signing method

Example:

In this example, a PIN signing method ID (6d345e8a-8286-40bb-90bd-90b305ec0c58), separated by a colon is used with it's value (123456)

In the header request, the Signing-Method parameter is passed with the value:

6d345e8a-8286-40bb-90bd-90b305ec0c58:123456

Postman:

In Postman, you can add the Signing-Method in the header with it's value.

👍

Continue to read about the Signing Method API Flows.