What we cover in this guide

In this guide, we will explain how to access your testnet assets, which you receive when you sign up with Venly, create your first user and wallet, and perform a crypto transaction. We will also walk you through several endpoints to help you get started with the Wallet API.

Wallet API Tutorial Video

Prerequisites

You need a Venly business account. If you don't have one, register in our Developer Portal or follow our step-by-step guide, Getting Started with Venly .
You need your Client ID and Client Secret, which can be obtained from the Portal as shown below.

📘

All the API calls for this guide run on a sandbox environment. You can test and experiment with API calls without causing any harm to the actual blockchain or data.

There are several ways to run API calls, but for this guide, you can use the API-Reference or Postman to execute the different endpoints.

1. Authenticating

You will need your access credentials (Client ID and Client Secret) to obtain a bearer token and authorize all API calls. These credentials are necessary for authentication purposes.

📘

Learn how to retrieve a bearer token and authenticate API calls.

Please note that the base path for all Wallet API endpoints in this guide specifically is https://api-wallet-sandbox.venly.io, which is the sandbox environment.

2. Accessing Testnet Assets

As soon as you sign up for a trial subscription with the Wallet-API, a MATIC testnet wallet is created automatically for you which includes the following testnet assets:

1 MATIC Token
100 Venly Test Tokens (ERC20)
1 NFT

These assets are automatically added to your wallet, and linked to a user (Initial Test User) for you to start testing and playing around with the API endpoints.

👍
123456 is the default PIN for your user that is used to access your wallet. More on this later in the guide.

2.1. Retrieve your `userId` and `signingMethodId`

In this first API call, we will retrieve all users. A user can have multiple wallets linked to them. As explained at the start, the MATIC wallet, which is created automatically with the assets is also linked to a user. When you call this endpoint it will only return one user (let's call this User #1 or First User).

Firstly, we want to retrieve the userId, which is the unique ID of your user.
Secondly, we want to retrieve the signingMethodId, which is used to access the wallets linked to the user.

📘
Read more about User Management and Signing Methods.

Call the following endpoint to retrieve all users:

Request Endpoint: reference

GET /api/users

Parameter	Param Type	Description	Data Type	Value
`includeSigningMethods`	Query	Flag that indicates to show the signing method details of the users or not.	Boolean	true

Response Body:

📘
Save the following params for later use:

result.id which is the userId

result.signingMethods.id which is the signingMethodId

{
    "success": true,
    "result": [
        {
            "id": "8fa1ac9e-618c-43a2-8241-eb75bbb8a021",
            "reference": "Initial test user",
            "createdAt": "2024-04-05T07:11:42.14671",
            "signingMethods": [
                {
                    "id": "c992826c-6311-4896-9c74-8a5f1644f9c7",
                    "type": "PIN",
                    "incorrectAttempts": 0,
                    "remainingAttempts": 10,
                    "lastUsedSuccess": "2024-04-05T07:11:42.646531",
                    "hasMasterSecret": true
                }
            ]
        }
    ]
}

2.2. Retrieve your `walletId` and wallet `address`

Next, we will retrieve all wallets linked to a specific user. When you call this endpoint it will only return one wallet, which is your MATIC wallet.

Call the following endpoint to retrieve all wallets:

Request Endpoint: reference

GET /api/wallets

Parameter	Param Type	Description	Data Type
`userId`	Query	Filter wallets by user ID. Add your `userId` which you got from the previous endpoint.	String

Response Body

👍
The response body shows the balance param as 1, indicating you have one MATIC token.

📘
Save the following params for later use:

result.id which is the walletId

result.address which is the wallet address

{
    "success": true,
    "result": [
        {
            "id": "71116253-e401-4b6c-9b3b-d23d93b5c663",
            "address": "0xc8a14eEe713887B4ad2E53DA45a52332b982FBa6",
            "walletType": "API_WALLET",
            "secretType": "MATIC",
            "createdAt": "2024-04-05T07:11:43.438044",
            "archived": false,
            "description": "Initial test Wallet",
            "primary": false,
            "hasCustomPin": false,
            "userId": "8fa1ac9e-618c-43a2-8241-eb75bbb8a021",
            "custodial": false,
            "balance": {
                "available": true,
                "secretType": "MATIC",
                "balance": 1,
                "gasBalance": 1,
                "symbol": "MATIC",
                "gasSymbol": "MATIC",
                "rawBalance": "1000000000000000000",
                "rawGasBalance": "1000000000000000000",
                "decimals": 18
            }
        }
    ]
}

2.3. Retreive ERC20 token balance

Next, we will call the following endpoint to receive the ERC20 token balance of your wallet:

Request Endpoint: reference

GET /api/wallets/{walletId}/balance/tokens

Parameter	Param Type	Description	Data Type	Mandatory
`{walletId}`	Path	The `ID` of your wallet, which you got from the previous endpoint.	String	✅

Request Example

GET /api/wallets/c4c97f87-8e00-4f3a-8647-2f24ac9b73cb/balance/tokens

Response Body

👍
The response body shows the balance param as 100, indicating you have 100 ERC20 tokens.

{
    "success": true,
    "result": [
        {
            "tokenAddress": "0x681941526dcf9f263c37af2050e68b6a71989924",
            "rawBalance": "100000000000000000000",
            "balance": 100,
            "decimals": 18,
            "symbol": "VTT",
            "type": "ERC20",
            "transferable": true,
            "name": "Venly Test Token",
            "possibleSpam": false
        }
    ]
}

2.4. Retrieve NFTs

Next, we will call the following endpoint to get NFTs in your wallet:

Request Endpoint: reference

GET /api/wallets/{walletId}/nonfungibles

Parameter	Param Type	Description	Data Type	Mandatory
`{walletId}`	Path	The `ID` of the wallet, which you got from the previous endpoint.	String	✅

Response Body

👍
The response body will show your NFT.

{
    "success": true,
    "result": [
        {
            "id": "1",
            "name": "Venly Pioneer's Pass",
            "description": "This Dummy NFT symbolizes forging new paths in the digital wilderness and serves as a badge of honor for developers who are pioneering groundbreaking technologies and applications in blockchain. Ready to use while exploring the Venly Platform.",
            "url": "https://venly.io",
            "imageUrl": "https://cdn.simplehash.com/assets/48ba4f08142c55680eb9c9e03b484ef8798e9601604f92d4d4dc198873d4d33c.png",
            "imagePreviewUrl": "https://lh3.googleusercontent.com/CKlfDioHpKdphp6Zu69HMTVF5LAaI2bivII_eTa-XUESK3VVekqvGeTaK4zDxmF3QaGHh99lNi1nxwwKpVMaadJe3B6G8GwehV_2",
            "imageThumbnailUrl": "https://lh3.googleusercontent.com/CKlfDioHpKdphp6Zu69HMTVF5LAaI2bivII_eTa-XUESK3VVekqvGeTaK4zDxmF3QaGHh99lNi1nxwwKpVMaadJe3B6G8GwehV_2=s250",
            "animationUrls": [],
            "fungible": true,
            "contract": {
                "name": "Venly Pioneer's Pass",
                "description": "This Dummy NFT symbolizes forging new paths in the digital wilderness and serves as a badge of honor for developers who are pioneering groundbreaking technologies and applications in blockchain. Ready to use while exploring the Venly Platform.",
                "address": "0x3ccae80c81ea3c778321b9af9f213fa5facb40e8",
                "symbol": "VPP",
                "media": [
                    {
                        "type": "image",
                        "value": "https://lh3.googleusercontent.com/tKfAo5vzldUZUC357aGDsSzaKLMfjMaddTo5vd24WJ6G1-7iA_sQz5zQcHIHhv9lN--1bKK5f3MHuVC17fKCCxUA1EkjTH7W-g"
                    }
                ],
                "type": "ERC_1155",
                "verified": false,
                "premium": false,
                "isNsfw": false,
                "categories": [],
                "url": "https://venly.io",
                "imageUrl": "https://lh3.googleusercontent.com/tKfAo5vzldUZUC357aGDsSzaKLMfjMaddTo5vd24WJ6G1-7iA_sQz5zQcHIHhv9lN--1bKK5f3MHuVC17fKCCxUA1EkjTH7W-g"
            },
            "attributes": [
                {
                    "type": "property",
                    "name": "Brand",
                    "value": "Venly"
                },
                {
                    "type": "property",
                    "name": "Year",
                    "value": "2024"
                },
                {
                    "type": "property",
                    "name": "Destination",
                    "value": "Devportal"
                },
                {
                    "type": "property",
                    "name": "Gem",
                    "value": "Purple crystal"
                },
                {
                    "type": "property",
                    "name": "Token Type ID",
                    "value": "1"
                }
            ],
            "balance": 1,
            "finalBalance": 1,
            "transferFees": false
        }
    ]
}

👍

Now that you have accesed your user, wallet, and it's funds, the next part will talk about the basics of how you can actually create users, signing methods, and wallets from scratch.

Keep in mind that after completing Steps 3-5, you will have:

Two users

Two wallets

3. Creating a User

The next thing you need to do is create a second user. Each user created can represent one of your end-users.

📘
Read more about User Management.

Use the following endpoint to create a user:

Request Endpoint: reference

 POST /api/users

Parameter	Param Type	Description	Data Type	Mandatory
`reference`	Body	A free-form text to specify a reference for the user you create. It can help group specific users.	String	❌

Request Body:

{
  "reference": "Second Test User"
}

Response Body:

📘

result.id : This is the User ID, of your second user.

{
    "success": true,
    "result": {
        "id": "6a5a9020-e969-4d9a-ae4b-fcd91a75769d",
        "reference": "Second Test User",
        "createdAt": "2023-12-06T12:11:12.702586449"
    }
}

4. Creating a signing method for your user

Next, we're going to create a PIN signing method for the user we just created. There are other signing methods as well, but the very first one should be PIN. Signing methods allow your users to access and interact with their wallets and perform transactions. Each user can access their wallets using their own signing method.

📘
Read more about Signing Methods.

Use the following endpoint to create a signing method for your user.

Request Endpoint: reference

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

Parameter	Param Type	Description	Data Type	Mandatory
`{userId}`	Path	The ID of the user for whom to create the signing method for	String	✅
`type`	Body	The type of signing method to create for this user. Allowed values: `PIN, BIOMETRIC, EMERGENCY_CODE`	String	✅
`value`	Body	The value of the signing method. For `PIN`, the value should be 6 digits. For `EMERGENCY_CODE`, the value should be 25 characters, or you can leave it blank to autogenerate the code with the correct entropy.	String	❌

Request Body:

{
  "type": "PIN",
  "value": "123456"
}

Response Body:

📘

result.id : This is the Signing Method ID, of your second user.

Each user has a unique signing method ID

{
    "success": true,
    "result": {
        "id": "bf1200ce-d117-4a06-a029-6d99080c6358",
        "type": "PIN",
        "incorrectAttempts": 0,
        "remainingAttempts": 10,
        "hasMasterSecret": true
    }
}

5. Creating a Wallet

The next step is creating a wallet for your user. We will include the userId in the request body, and this way the wallet will be created and linked to the specific user. The user can then access the wallet with their signing method.

Since you are currently using the API calls in a sandbox environment, the wallets will be created on a testnet chain. In this example, we will create the wallet on the Polygon (MATIC) Blockchain.

📘
Explore testnet chains further.

Use the following endpoint to create a wallet for your second user:

Request Endpoint: reference

 POST /api/wallets

Parameter	Param Type	Value	Description	Example Value
`Signing-Method`	Header	`id:value`	`id`: This is the ID of the user's signing method `value`: This is the value of the user's signing method	`c992826c-6311-4896-9c74-8a5f1644f9c7:123456`

Parameter	Description	Type	Required
`secretType`	Specifies the blockchain on which you wish to create your wallet	String	✅
`userId`	The ID of the user you want to link to this wallet.	String	❌
`pincode` (deprecated)	Serves as the password to access your wallet. Please remember it and keep it secure to ensure the protection of your wallet and its contents.	String	❌

Request Body:

{
  "secretType": "MATIC",
  "userId": "ddf04a49-9c38-4326-acc7-02529ba05a78"
}

Response Body:

Save the following parameters from the response body. They will be used later in the guide.

Parameter	Description
result.`id`	This ID is utilized to uniquely identify the wallet.
result.`address`	This is the public wallet address. You can provide this address to others to receive payments or initiate transfers to this wallet.
result.`secretType`	This is the blockchain name on which your wallet is created.

{
    "success": true,
    "result": {
        "id": "19590dc9-28af-417b-bc66-549e726bf91f",
        "address": "0xa1f04C769155195D83c7f16bC6B9540139C80b2A",
        "walletType": "API_WALLET",
        "secretType": "MATIC",
        "createdAt": "2023-12-07T10:21:25.114751052",
        "archived": false,
        "description": "Wise Iguana",
        "primary": false,
        "hasCustomPin": false,
        "userId": "ddf04a49-9c38-4326-acc7-02529ba05a78",
        "custodial": false,
        "balance": {
            "available": true,
            "secretType": "MATIC",
            "balance": 0,
            "gasBalance": 0,
            "symbol": "MATIC",
            "gasSymbol": "MATIC",
            "rawBalance": "0",
            "rawGasBalance": "0",
            "decimals": 18
        }
    }
}

👍
You have successfully created a wallet 🎉.

The first wallet with testnet assets is linked to the first user (Initial test user), and the second wallet that you created is linked to the second user (Second Test User).

The PIN code of the first user (123456) will be used to access the first wallet with testnet assets.

The PIN code of your second user will be used to access the second wallet, which is empty.

Testnet Assets Wallet & Newly Created Wallet

Next, we will transfer the testnet funds from your first wallet (which has testnet assets) to your second wallet (which is empty).

6. Transferring Funds

At this point, you should have the first wallet containing testnet funds, while the second wallet remains empty.
We will run another endpoint to transfer some funds (20 ERC20 tokens) from the first wallet to the second one.

Use the following endpoint to initiate an ERC20 token transfer:

Request Endpoint: reference

 POST /api/transactions/execute

Parameter	Param Type	Value	Description	Example Value
`Signing-Method`	Header	`id:value`	`id`: This is the ID of the first user's signing method `value`: This is the value of the first user's signing method	`c992826c-6311-4896-9c74-8a5f1644f9c7:123456`

Request Body:

Parameter	Description	Type	Required
`pincode` (Deprecated)	Serves as the password to access your wallet. Please remember it and keep it secure to ensure the protection of your wallet and its contents.	String	❌
`transactionRequest`	The JSON object for the transaction request data	Object	✅
`type`	Type of transfer. In the example a normal `TOKEN_TRANSFER`	String	✅
`walletId`	The wallet ID of the first wallet (The wallet that is initiating the transfer)	String	✅
`to`	The `address` of the destination wallet where the funds will be transferred to. In this case, it refers to the `address` of the second wallet.	String	✅
`value`	The amount mentioned here refers to the quantity of ERC20 tokens that you intend to transfer	Integer	✅
`secretType`	Specifies the blockchain of the transaction	String	✅
`tokenAddress`	The token address of the ERC20 token that you want to transfer	String	✅

{   
  "transactionRequest": {  
    "type" : "TOKEN_TRANSFER",
    "walletId" : "71116253-e401-4b6c-9b3b-d23d93b5c663",
    "to" : "0xa1f04C769155195D83c7f16bC6B9540139C80b2A",
    "value": 20
    "secretType" : "MATIC",     
    "tokenAddress": "0x54d71694bf8869a50d04b0a859484b3f94c738aa"
    }  
  }

Response Body:

In the response, you will find a tranasactionHash, which can be used to follow up on the status of that specific transaction.

📘
Save the transactionHash for later use in this guide.

{
    "success": true,
    "result": {
        "id": "2addea45-1f82-40c2-a59b-f4c3ec463a3d",
        "transactionHash": "0x3eab1a14783c9b155c9ae15e684a56b8bee85aa4dcea2178dd194efd8139e9c6"
    }
}

The "success": true in response body indicates that the transfer request was submitted successfully. It does not mean the fund transfer was completed. Since this transfer call is being made on a sandbox environment and testnet blockchain, it's important to note that the funds may arrive instantly. This may not be the case with mainnet blockchain transactions as they can take some time.

To verify whether a transfer has been completed, it is necessary to check the transaction status. This status will provide information on whether the transfer was successful or if it encountered any issues, resulting in a failure.

📘
Mainnet Blockchain transactions are never immediate. They require time for processing, and the duration can vary depending on the specific blockchain network.

7. Check transaction status

To confirm whether a specific transaction was successful or not, you can check its status using the provided endpoint. To obtain the status of the transaction, please provide the required information. Set the secretType as "MATIC" and enter the transactionHash that you had saved earlier.

Request Endpoint: reference

 GET /api/transactions/{secretType}/{transactionHash}/status

Response Body:

From the response body, you can see that the status is "SUCCEEDED" . This indicates that the transaction was successfully executed and completed.

✅
Funds have been sent from the first wallet to the second.

{
    "success": true,
    "result": {
        "hash": "0x3eab1a14783c9b155c9ae15e684a56b8bee85aa4dcea2178dd194efd8139e9c6",
        "status": "SUCCEEDED",
        "confirmations": 342,
        "blockHash": "0x0f510f3581446ab3f5d4d4652b8ba77b9ec81f435857b9fac8c7f98bbe1d8d15",
        "blockNumber": 5977443,
        "hasReachedFinality": true,
        "chain": "MATIC",
        "nonce": 0,
        "gas": 200000,
        "gasUsed": 52172,
        "gasPrice": 30000000015,
        "logs": [
            {
                "logIndex": 4,
                "data": "0x000000000000000000000000000000000000000000000001158e460913d00000",
                "topics": [
                    "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
                    "0x000000000000000000000000e11dbbe2460745b44f17d5234c29f02f0e18aa67",
                    "0x000000000000000000000000a80b7e3360386c495ed24476522c1b37a79f9917"
                ]
            },
            {
                "logIndex": 5,
                "data": "0x00000000000000000000000000000000000000000000000000058f8135d110000000000000000000000000000000000000000000000000000de0b6b3a764000000000000000000000000000000000000000000000000006c955c1a037403e4520000000000000000000000000000000000000000000000000ddb27327192f00000000000000000000000000000000000000000000000006c9561a984a9d4f452",
                "topics": [
                    "0x4dfe1bbbcf077ddc3e01291eea2d5c70c2b422b415d95645b9adcfd678cb1d63",
                    "0x0000000000000000000000000000000000000000000000000000000000001010",
                    "0x000000000000000000000000e11dbbe2460745b44f17d5234c29f02f0e18aa67",
                    "0x00000000000000000000000004ba3ef4c023c1006019a0f9baf6e70455e41fcf"
                ]
            }
        ],
        "from": "0xc8a14eEe713887B4ad2E53DA45a52332b982FBa6",
        "to": "0xa1f04C769155195D83c7f16bC6B9540139C80b2A",
        "rawValue": 0,
        "value": 0,
        "timestamp": "2024-04-17T15:51:46"
    }
}

Check balance after transfer

Let's use the same endpoint once again to check the balance of your second wallet. Please provide the id (walletId) of your second wallet to retrieve the updated balance information.

Request Endpoint: reference

GET /api/wallets/{walletId}/balance/tokens

Response Body:

👍
The response body shows the balance as 20, indicating it has 20 ERC20 tokens.

{
    "success": true,
    "result": [
        {
            "tokenAddress": "0x54d71694bf8869a50d04b0a859484b3f94c738aa",
            "rawBalance": "20000000000000000000",
            "balance": 20,
            "decimals": 18,
            "symbol": "VTT",
            "type": "ERC20",
            "transferable": true,
            "name": "Venly Test Token",
            "possibleSpam": false
        }
    ]
}

Next Steps

👍
Following are a few basic guides that you should try next to experiment with your testnet assets:

How to transfer a native token

How to transfer an NFT

Schedule a demo with our team to explore tailored solutions or dive in and start building right away on our portal.

What we cover in this guide

Wallet API Tutorial Video

Prerequisites

📘

1. Authenticating

📘

2. Accessing Testnet Assets

👍

2.1. Retrieve your userId and signingMethodId

📘

Request Endpoint: reference

Response Body:

📘

2.2. Retrieve your walletId and wallet address

Request Endpoint: reference

Response Body

👍

📘

2.3. Retreive ERC20 token balance

Request Endpoint: reference

Request Example

Response Body

👍

2.4. Retrieve NFTs

Request Endpoint: reference

Response Body

👍

👍

3. Creating a User

📘

Request Endpoint: reference

Request Body:

Response Body:

📘

4. Creating a signing method for your user

📘

Request Endpoint: reference

Request Body:

Response Body:

📘

5. Creating a Wallet

📘

Request Endpoint: reference

Request Body:

Response Body:

👍

6. Transferring Funds

Request Endpoint: reference

Request Body:

Response Body:

📘

📘

7. Check transaction status

Request Endpoint: reference

Response Body:

✅

Check balance after transfer

Request Endpoint: reference

Response Body:

👍

Next Steps

👍

2.1. Retrieve your `userId` and `signingMethodId`

2.2. Retrieve your `walletId` and wallet `address`