Status ProductionStatus SandboxSupportDeveloper Portal

Getting started

Covering the basics from authentication to creating your first wallet

Suggest Edits

What we cover in this guide

In this guide, we will explain how to access your testnet assets that you receive when you sign up for the trial of Wallet-API, as well as creating your first user and wallet, and performing a crypto transaction. We will walk you through several endpoints to help you get started with the Wallet-API.

We will cover the following topics:

  1. How to authenticate
  2. How to access testnet assets
  3. How to create a user
  4. How to create a user's signing method
  5. How to create a wallet
  6. Transfer funds from one wallet to another
  7. Check transaction status

Prerequisites

  1. You need a Venly business account, if you don't have one, click here to register in our Developer Portal, or follow our step-by-step guide, Getting Started with Venly.
  2. 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.
  3. 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 App Secret

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, you can use the API-Reference or Postman to execute the different endpoints.

1. Authenticating

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

📘

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.

Testnet Assets

Testnet Assets

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).

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

📘

Read more about users and signing methods.

Call the following endpoint to retrieve all users:

Request Endpoint: reference

GET /api/users
ParameterParam TypeDescriptionData TypeValue
includeSigningMethodsQueryFlag that indicates to show the signing method details of the users or not.Booleantrue

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
ParameterParam TypeDescriptionData Type
userIdQueryFilter 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
ParameterParam TypeDescriptionData TypeMandatory
{walletId}PathThe 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
ParameterParam TypeDescriptionData TypeMandatory
{walletId}PathThe 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 following Steps 3-5, you will have two users and 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.

📘

Learn more about user management by clicking here.

Use the following endpoint to create a user:

Request Endpoint: reference

 POST /api/users
ParameterParam TypeDescriptionData TypeMandatory
referenceBodyA 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.

📘

Click here to learn about signing method.

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

Request Endpoint: reference

 POST /api/users/{userId}/signing-methods
ParameterParam TypeDescriptionData TypeMandatory
{userId}PathThe ID of the user for whom to create the signing method forString✅
typeBodyThe type of signing method to create for this user. Allowed values: PIN, BIOMETRIC, EMERGENCY_CODEString✅
valueBodyThe 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 by clicking here.

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

Request Endpoint: reference

 POST /api/wallets
ParameterParam TypeValueDescriptionExample Value
Signing-MethodHeaderid:valueid: 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
ParameterDescriptionTypeRequired
secretTypeSpecifies the blockchain on which you wish to create your walletString✅
userIdThe 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.

ParameterDescription
result.idThis ID is utilized to uniquely identify the wallet.
result.addressThis is the public wallet address. You can provide this address to others to receive payments or initiate transfers to this wallet.
result.secretTypeThis 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 assests 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

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.

Transferring 20 ERC20 Tokens

Transferring 20 ERC20 Tokens

Use the following endpoint to initiate an ERC20 token transfer:

Request Endpoint: reference

 POST /api/transactions/execute
ParameterParam TypeValueDescriptionExample Value
Signing-MethodHeaderid:valueid: 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:

ParameterDescriptionTypeRequired
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❌
transactionRequestThe JSON object for the transaction request dataObject✅
typeType of transfer. In the example a normal TOKEN_TRANSFERString✅
walletIdThe wallet ID of the first wallet (The wallet that is initiating the transfer)String✅
toThe 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✅
valueThe amount mentioned here refers to the quantity of ERC20 tokens that you intend to transferInteger✅
secretTypeSpecifies the blockchain of the transactionString✅
tokenAddressThe token address of the ERC20 token that you want to transferString✅
{   
  "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
        }
    ]
}
Balance after Transfer of ERC20 Tokens

Balance after Transfer of ERC20 Tokens

Next Steps

👍

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

Updated 8 days ago

What’s Next

Now that you've successfully finished basic operations such as creating users, signing methods, wallets, and transferring native tokens it is time to check out the rest of our guides for more advanced use cases.