Signing Methods API Flow

This guide will explain the Signing Methods flow including API calls.

Context
Throughout this guide, when we mention "Users," we are referring to the individuals who will be using your service as end-users.
Signing Methods Flow
1) Create a User
First let's see how we create a user. Normally, one user will correspond to one of your end users. This way each end user will have their own signing methods and wallets.
You can create one or multiple users and follow the same flow. If you create only one user and link all wallets to it, then all wallets will be accessible with the signing methods you create for this user.
You can create users without a specifying a signing method. The signingMethod object in body is optional.
For this example, we will create a signing method along with creating a user.
To create a user, call the following endpoint:
​POST /api/users 
Request Body Parameters:
Parameter
Type
Required
Description
reference
string
    ❌
You can provide a reference (can be whatever you want) to distinguish between users.
signingMethod
object
    ❌
This object contains the type of signing method and it’s value.
type
string
    ❌
This parameter indicates the type of signing method. (e.g., PIN, EMERGENCY_CODE, BIOMETRIC.)
The first signing method should always be a PIN.
value
string
    ❌
This is the value of your signing method. For example, the value for PIN can be “123456”.
Request Body: 
{
  "reference": "ABD User 1",
  "signingMethod": {
    "type": "PIN",
    "value": "123456"
  }
}
Response Body:
Save the following parameters from the response body. They will be used later in the guide.
result >> id: This is the User ID. Every user you create will have a unique user ID.
signingMethods >> id: This is the signing method ID and will be used for authentication purposes. Every signing method will have a different and unique ID. 
It is IMPORTANT to save the PIN signing method ID since it is used during the PIN reset process.
{
  "success": true,
  "result": {
    "id": "e85470a8-5deb-41f6-be6c-de693683a22c",
    "reference": "ABD User 1",
    "createdAt": "2023-08-02T07:18:58.624685414",
    "signingMethods": [
      {
        "id": "4658c064-05b9-4bbd-9f0e-68a9588c7bc3",
        "type": "PIN",
        "incorrectAttempts": 0,
        "remainingAttempts": 10,
        "hasMasterSecret": true
      }
    ]
  }
}
2) Create Signing Methods
When creating a signing method for a user for the first time, you don’t have to provide another one. 
When creating additional signing methods, you will have to provide an existing valid signing method in the header.
In this example, we will create an additional emergency code signing method.
Call the following endpoint to create a signing method:
​POST /api/users/{userId}/signing-methods​
Path Parameters:
{userId} : This is the User ID whose signing method you want to create. Paste the previously saved User ID here.
Header Parameters:
For this example, the user already has an existing PIN signing method, that's why we are providing the PIN signing method in the header request to authenticate the call.
Parameter
Value
Description
Signing-Method
id:value
​
id: This is the ID of the signing method
value: This is the value of the signing method
Request Body Parameters:
Parameter
Type
Description
type
string
This parameter indicates the type of signing method. (e.g., PIN, EMERGENCY_CODE, BIOMETRIC.)
value
string
This is the value of your signing method. For example, the value for EMERGENCY_CODE can be “w2v7yertaad21lhudqghzwcg4”.
To autogenerate the emergency code, this can be removed.
For this example, we will create the emergency code signing method.
The body does not contain the value property because we want to autogenerate the emergency code.
{
  "type": "EMERGENCY_CODE"
}
Response Body:
It is IMPORTANT to save the PIN signing method ID since it is used during the PIN reset process.
Description of parameters under the result object:
id: This is the signing method ID
value: This is the value of the generated emergency code
{
  "success": true,
  "result": {
    "id": "3eccfcef-467a-42a6-8b6b-6ffce3b3b115",
    "type": "EMERGENCY_CODE",
    "incorrectAttempts": 0,
    "remainingAttempts": 10,
    "value": "taif7dxjikhtb82zm7u93tn26",
    "hasMasterSecret": true
  }
}
3) Link wallets to the User
Once a wallet is linked to a user, it will be accessible with the user’s signing methods only.
You can either create a new wallet, import a wallet, or link an already existing one.
3.1) Create new Wallet and Link to User
To create a new wallet for a user, you should use the following endpoint:
​POST /api/wallets​
You need to specify a userId in the request body. You should also provide this user’s PIN signing method as pincode. This way the wallet will be created and immediately linked to the specified user.
Request Body
{
  "pincode": "123456",
  "description": "WALLET#1",
  "secretType": "AETERNITY",
  "userId": "cc931c57-9ff0-47c2-a0ab-acf2cb5cf1de"
}
Response Body
{
  "success": true,
  "result": {
    "id": "fce92b11-d18f-4577-b7f8-7dccfd131abf",
    "address": "ak_2DPcLNVUNiJ5msLdUcvLzvPEb981khy7tN62xP6jZSnyMva4fT",
    "walletType": "WHITE_LABEL",
    "secretType": "AETERNITY",
    "createdAt": "2023-08-02T12:08:38.064870232",
    "archived": false,
    "description": "WALLET#1",
    "primary": false,
    "hasCustomPin": false,
    "userId": "e85470a8-5deb-41f6-be6c-de693683a22c",
    "balance": {
      "available": true,
      "secretType": "AETERNITY",
      "balance": 0,
      "gasBalance": 0,
      "symbol": "AE",
      "gasSymbol": "AE",
      "rawBalance": "0",
      "rawGasBalance": "0",
      "decimals": 18
    }
  }
}
You have successfully created a wallet and linked the User.
3.2) Import a Wallet and Link User
To import a new wallet and link it to a user, you should use the endpoint:
​POST /api/wallets/import​
Specify a userId in the request body. You should also provide this user’s PIN signing method as pincode. This way the wallet will be imported and immediately linked to the specified user.
Request Body
{
  "importWalletType": "AETERNITY_KEYSTORE",
  "pincode": "123456",
  "keystore": "Enter_Your_Keystore_Here",
  "password": "Enter_Password_For_Keystore_Here"
}
3.3) Link Existing Wallet to User
To link an existing wallet to a user, you should use the endpoint:
​PUT /api/wallets/{id}/user​
Path Parameters:
{id} : This is the wallet ID of the wallet you want to link with a User.
Header Parameters:
Provide the User's Signing-Method in the header request to authenticate the call.
Parameter
Value
Description
Signing-Method
id:value
​
id: This is the ID of the signing method
value: This is the value of the signing method
Request Body Parameters:
In the request body you should provide:
1.pincode of the existing wallet
2.userId of the user you want to link the wallet to
This way the wallet’s PIN will be updated to match the user’s PIN signing method and the wallet will be linked to the specified user.
Request Body
{
  "pincode": "123456",
  "userId": "e85470a8-5deb-41f6-be6c-de693683a22c"
}
That’s it! Once everything is set up, the users you’ve created can start using their signing methods. 
4) Recovering Signing Methods
The main goal of the signing methods is for users to have different means to recover their wallets. In case a signing method’s value is lost, it can be updated by providing another valid signing method.
For example, if a user forgets their PIN, the endpoint can be called using the PIN signing method ID and the user's ID within the URL path. To authenticate, include a header that holds a valid alternate Signing-Method, which could be an emergency code or biometric.
The request body will contain the new PIN, indicated by the value parameter.
That’s done through the endpoint 
​PUT /api/users/{userId}/signing-methods/{signingMethodId}​
Path Parameters:
{userId} : This is the ID of the User whose PIN you want to reset
{signingMethodId} : This is the ID of the User's PIN signing method
Header Parameters:
Provide the User's Signing-Method in the header request to authenticate the call. In this case we are resetting the PIN, so you need to provide either the emergency code or biometric signing method here.
Parameter
Value
Description
Signing-Method
id:value
​
id: This is the ID of the signing method
value: This is the value of the signing method
Request Body
value: This will be your new PIN code
{
  "value": "987654"
}
Response Body
{
  "success": true,
  "result": {
    "id": "4658c064-05b9-4bbd-9f0e-68a9588c7bc3",
    "type": "PIN",
    "incorrectAttempts": 0,
    "remainingAttempts": 10,
    "lastUsedSuccess": "2023-08-02T12:34:57.63061",
    "hasMasterSecret": true
  }
}
You have successfully reset your PIN code!
5) Deleting a Signing Method
Call the following endpoint to delete a signing method:
​DELETE /api/users/{userId}/signing-methods/{signingMethodId}​
Path Parameters:
{userId} : This is the User ID whose signing method you want to delete. 
{signingMethodId} : This is the ID of the signing method you want to delete.
Header Parameters:
Provide a valid signing method (other than the one you want to delete) in the header request to authenticate the call.
Parameter
Value
Description
Signing-Method
id:value
​
id: This is the ID of the signing method
value: This is the value of the signing method
You will get a 200 OK response indicating the signing method has been deleted.
6) Signing Transaction and Signature Requests
6.1) In the Request Body
You can still use the pincode for any signing request or executing transactions. If the request is to be signed by a wallet linked to a user, we will automatically verify that the specified pincode is the same as the PIN signing method for the user. 
Use the pincode property in the request body.
This applies only to the PIN signing method.
Example:
{
  "pincode" : "123456",
  "transactionRequest": 
    {
    "type" : "TRANSFER",
    "secretType" : "MATIC",
    "walletId" : "1f578c44-32cd-11ee-be56-0242ac120002",
    "to" : "0x49765De8772d810Eb76F4j8E6E5AEE0032f73AC8",
    "value": 0.1 
    }
}
6.2) In the Header
Apart from the pincode, a Signing-Method parameter can also be passed in the header.
So when calling the endpoints for signing a signature request or executing a transaction, pass the Signing-Method parameter through the header with value: id:value
The Signing-Method in header is used for authentication.
Parameter
Value
Description
Signing-Method
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 (f43744a8-32c4-11ee-be56-0242ac120002), separated by a colon is used with it's value (654321)
In the header request, the Signing-Method parameter is passed with the value:
f43744a8-32c4-11ee-be56-0242ac120002:654321
​

Parameter	Type	Required	Description
`reference`	string	❌	You can provide a reference (can be whatever you want) to distinguish between users.
`signingMethod`	object	❌	This object contains the type of signing method and it’s value.
`type`	string	❌	This parameter indicates the type of signing method. (e.g., PIN, EMERGENCY_CODE, BIOMETRIC.) The first signing method should always be a PIN.
`value`	string	❌	This is the value of your signing method. For example, the value for PIN can be “123456”.

Parameter	Value	Description
`Signing-Method`	`id:value`	`id`: This is the ID of the signing method `value`: This is the value of the signing method

Parameter	Type	Description
`type`	string	This parameter indicates the type of signing method. (e.g., PIN, EMERGENCY_CODE, BIOMETRIC.)
`value`	string	This is the value of your signing method. For example, the value for EMERGENCY_CODE can be “w2v7yertaad21lhudqghzwcg4”. To autogenerate the emergency code, this can be removed.

Parameter	Value	Description
`Signing-Method`	`id:value`	`id`: This is the ID of the signing method `value`: This is the value of the signing method

Parameter	Value	Description
`Signing-Method`	`id:value`	`id`: This is the ID of the signing method `value`: This is the value of the signing method

Parameter	Value	Description
`Signing-Method`	`id:value`	`id`: This is the ID of the signing method `value`: This is the value of the signing method

Parameter	Value	Description
`Signing-Method`	`id:value`	`id`: This is the ID of the signing method `value`: This is the value of the signing method

Signing Methods

SWAP Token Pairs

Last modified 15d ago

Signing Methods API Flow

Context

Signing Methods Flow

1) Create a User

​POST /api/users

Request Body Parameters:

Request Body:

Response Body:

2) Create Signing Methods

​POST /api/users/{userId}/signing-methods​

Path Parameters:

Header Parameters:

Request Body Parameters:

Response Body:

3) Link wallets to the User

3.1) Create new Wallet and Link to User

​POST /api/wallets​

Request Body

Response Body

3.2) Import a Wallet and Link User

​POST /api/wallets/import​

Request Body

3.3) Link Existing Wallet to User

​PUT /api/wallets/{id}/user​

Path Parameters:

Header Parameters:

Request Body Parameters:

Request Body

4) Recovering Signing Methods

​PUT /api/users/{userId}/signing-methods/{signingMethodId}​

Path Parameters:

Header Parameters:

Request Body

Response Body

5) Deleting a Signing Method

​DELETE /api/users/{userId}/signing-methods/{signingMethodId}​

Path Parameters:

Header Parameters:

6) Signing Transaction and Signature Requests

6.1) In the Request Body

6.2) In the Header

POST /api/users

POST /api/users/{userId}/signing-methods

POST /api/wallets

POST /api/wallets/import

PUT /api/wallets/{id}/user

PUT /api/users/{userId}/signing-methods/{signingMethodId}

DELETE /api/users/{userId}/signing-methods/{signingMethodId}