Getting started
Covering the basics from authentication to creating your first wallet
What we cover in this guide
In this guide we will explain how to authenticate to our API service, as well as creating your first wallet and performing a basic transaction. We will walk you through several endpoints to help you get started, we will cover the following topics:
- How to authenticate
- How to create a wallet
- How to top up your wallet
- Check your wallet balance
- Transfer funds from one wallet to another
- Check transaction status
Prerequisites
- You need a Venly business account, if you don't have one, click here to register in our Business Portal, or follow our step-by-step guide, Getting Started with Venly.
- You need an active trial or paid subscription of the Wallet-API. You can start a 30-day free trial for the Wallet-API as shown below.
- You need your Client ID and Client Secret which can be obtained from the Portal as shown below.

Starting a trial subscription and obtaining a Client ID and Client Secret
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 we will be using Swagger or Postman to execute the different endpoints.
1. Authenticating
In order to obtain a bearer token and authorize all API calls, you will need your Client ID and Client Secret. These credentials are necessary for authentication purposes.
- Click here to open Swagger for the Wallet API
- Click on the Authorize button
- Enter your
Client ID
andClient Secret
- Click the Authorize button on the bottom
Congratulations 🎉, you have authenticated successfully, and now you can run API calls.
Please note that the base path for all Wallet API endpoints is https://api-wallet-sandbox.venly.io
2. Creating a Wallet
Let's begin by creating a wallet. 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 our first wallet on the Polygon (MATIC) Blockchain.
Explore testnet chains further by clicking here.
Use the following endpoint to create your first wallet:
Request Endpoint: reference
POST /api/wallets
Request Body:
Parameter | Description | Type | Required |
---|---|---|---|
pincode | 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 | ✅ |
secretType | Specifies the blockchain on which you wish to create your wallet | String | ✅ |
{
"pincode": "123456",
"secretType": "MATIC"
}
Response Body:
Save the following parameters from the response body. They will be used later in the guide.
Parameter | Description |
---|---|
id | This id is utilized to uniquely identify your wallet. |
address | This is your public wallet address. You can provide this address to others to receive payments or initiate transfers to your wallet. |
secretType | This is the blockchain name on which your wallet is created. |
{
"success": true,
"result": {
"id": "f4bbe06f-012a-4ae3-97bf-fbdee97fe1c4",
"address": "0xfd551037D6eF400B8F01Dffc9858D5dD98899D86",
"walletType": "WHITE_LABEL",
"secretType": "MATIC",
"createdAt": "2023-07-19T09:06:13.714838114",
"archived": false,
"description": "Sample descriptive text",
"primary": false,
"hasCustomPin": true,
"balance": {
"available": true,
"secretType": "MATIC",
"balance": 0,
"gasBalance": 0,
"symbol": "MATIC",
"gasSymbol": "MATIC",
"rawBalance": "0",
"rawGasBalance": "0",
"decimals": 18
}
}
}
You have successfully created your first wallet 🎉.
Creating a second wallet
Next, let's move forward by creating a second wallet on the same blockchain, but this time with a different PIN Code. To do so, use the following endpoint and replicate the previous steps.
Request Endpoint: reference
POST /api/wallets
After creating your second wallet, save the id
and address
, we will use it later in the guide.
You now have two wallets on the Polygon (MATIC) testnet blockchain. Let's explore how you can add testnet tokens to your wallet using a Faucet.
Learn more about testnet coins and Faucets by clicking here.
3. Topping up Wallet
Now we will add testnet tokens to your first wallet. Testnet tokens are necessary for conducting experiments, testing applications, and simulating transactions on a blockchain network without using real or valuable cryptocurrencies.
- Copy the address of your first wallet.
- Go to the Polygon Faucet by clicking here.
- Paste the address of your first wallet (e.g :
0xfd551037D6eF400B8F01Dffc9858D5dD98899D86
) - Click Send me MATIC
- Testnet MATIC tokens will be sent to your wallet

Requesting MATIC testnet tokens using a Faucet
4. Check Wallet Balance
Now let's check the balance of your first wallet.
To check the balance of your first wallet, use the following endpoint. Enter the id
(walletId
) of your first wallet and execute the request. This will provide you with the current balance information.
Request Endpoint: reference
POST /api/wallets/{walletId}/balance
Response Body:
In the response body, locate the parameter called balance
. For this example, the value of balance
is 0.2. This indicates the amount of MATIC tokens currently held in your wallet.
{
"success": true,
"result": {
"available": true,
"secretType": "MATIC",
"balance": 0.2,
"gasBalance": 0.2,
"symbol": "MATIC",
"gasSymbol": "MATIC",
"rawBalance": "200000000000000000",
"rawGasBalance": "200000000000000000",
"decimals": 18
}
}
5. Transferring Funds
At this point, you should have the first wallet containing some funds, while the second wallet remains empty.
We will run another endpoint where we will transfer some funds from the first wallet to the second wallet.
Use the following endpoint to initiate a transfer:
Request Endpoint: reference
POST /api/transactions/execute
Request Body:
Parameter | Description | Type | Required |
---|---|---|---|
pincode | 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 TRANSFER | String | ✅ |
secretType | Specifies the blockchain on which you wish to create your wallet | String | ✅ |
walletId | Type of wallet you wish to create. WHITE_LABEL wallets, in this case, are recoverable wallets, meaning they can be restored if access is lost | String | ✅ |
to | The address of the destination wallet where the funds will be transferred to. In this case, it refers to the second wallet. | String | ✅ |
value | The amount mentioned here refers to the quantity of coins that you intend to transfer | Integer | ✅ |
{
"pincode" : "123456",
"transactionRequest": {
"type" : "TRANSFER",
"secretType" : "MATIC",
"walletId" : "f4bbe06f-012a-4ae3-97bf-fbdee97fe1c4",
"to" : "0xa1f04C769155195D83c7f16bC6B9540139C80b2A",
"value": 0.1
}
}
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": "9714aa64-4663-4b2f-abd5-3cdd7a347f93",
"transactionHash": "0xc1c636ba63759ea3c8080fee0bfb8bd09ee6bb5464cad30dee1323605a758d7e"
}
}
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.
To verify whether a transfer has been successfully 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.
6. 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": "0xc1c636ba63759ea3c8080fee0bfb8bd09ee6bb5464cad30dee1323605a758d7e",
"status": "SUCCEEDED",
"confirmations": 15,
"blockHash": "0x3c9a23764f52e8bff64a3435249fa0c22fd0090bb5838e20a2aebfa025377496",
"blockNumber": 38105564,
"hasReachedFinality": false,
"chain": "MATIC",
"nonce": 2,
"gas": 21000,
"gasUsed": 21000,
"gasPrice": 100000000000,
"from": "0xfd551037D6eF400B8F01Dffc9858D5dD98899D86",
"to": "0xa1f04C769155195D83c7f16bC6B9540139C80b2A",
"rawValue": 100000000000000000,
"value": 0.1,
"timestamp": "2023-07-19T09:37:09"
}
}
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.
GET /api/wallets/{walletId}/balance
Updated 7 days ago
Now that you've successfully finished basic operations such as creating wallets and transferring native tokens it is time to check out the rest of our guides for more advanced use cases.