Create your first developer wallet

Create a developer wallet and transfer native tokens to and from wallet

Planbok wallets offer a comprehensive developer solution for securely storing, sending, and managing digital assets on the blockchain. Our all-in-one experience takes care of intricate aspects such as security, transaction monitoring, account recovery flows, and more, ensuring that you or your users can seamlessly handle digital assets without any complications.

Note: The guide below utilises the Ethereum Sepolia Testnet for illustrative purposes, and there will be no transfer of real-world funds. In a production environment, you can create and utilize wallets that support digital assets on the following blockchains and standards:

• Ethereum (ETH), Binance Smart Chain (BSC), Polygon (MATIC), Lisk (LSK) and Graphite (@G), both Testnet and Mainnet

• ERC-20 tokens

• ERC-721 and ERC-1155 NFTs (non-fungible tokens)

Prerequisites

• Create a Developer Account and acquire an API key in the Dashboard.

Please note that you can not repeat idempotencyKey, except the initial transaction failed as it will raise a 401 error.

1. Create Wallet Set

A wallet set encompasses a cohesive collection of wallets, all under the management of a single cryptographic private key. This allows for the coexistence of wallets from diverse blockchains while sharing a common address.

To establish a wallet set, initiate a request to POST /wallet-sets/developer/create. Upon creating a wallet set, you will receive a distinctive wallet set secret cipher text, which is used for generating users' wallets and facilitating your users' blockchain transactions.

curl --request POST \
     --url 'https://api.planbok.io/v1/wallet-sets/developer/create' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'planbok-x-api-key: <API_KEY>' \
     --data '
     {
          "idempotencyKey": "1681b219-b430-48f5-8c93-50dd2d4139b5",
          "name": "Test Wallet Set"
     }'

Response Body

{
    "status": 201,
    "walletSet": {
        "id": "6519c5d92b8a095cb141ca0f",
        "name": "Test Wallet Set",
        "custodyType": "DEVELOPER",
        "userId": "650875cf2de8864ba34d2d8c",
        "createAt": "2023-10-01T09:11:46.325Z",
        "updatedAt": "2023-10-01T09:11:46.325Z"
    },
    "walletSetSecretCipherText": "<WALLET_SET_SECRET_CIPHER_TEXT>",
    "message": "Wallet set created successfully"
}

2. Create Wallet

In the world of Web3, a wallet serves as more than just a storage facility for digital assets; it serves as the foundational framework for all user interactions within the blockchain ecosystem. A wallet consists of a distinctive address and associated metadata that are stored on the blockchain.

To create a wallet, make a request to POST /wallets/developer/create using the walletSet.id and walletSetSecretCipherText from step 1.

curl --request POST \
     --url 'https://api.planbok.io/v1/wallets/developer/create' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'planbok-x-api-key: <API_KEY>' \
     --data '
     {
          "idempotencyKey": "bdcb308f-179e-4786-b870-4b6177c9e246",
          "blockchains": ["ETH-SEPOLIA"],
          "username": "john_doe",
          "userRefId": "8b9b8143-b580-4173-a742-f5ee2fe45c1f",
          "walletSetId": "6519c5d92b8a095cb141ca0f",
          "walletSetSecretCipherText": "<WALLET_SET_SECRET_CIPHER_TEXT>"
     }'

Response body

{
    "status": 201,
    "wallets": [{
        "id": "651c2d6981e7406eca0ac139",
        "accountType": "EOA",
        "address": "0xa0780f1403419ad992cA0420AAb81a4562e179dd",
        "blockchain": "ETH-SEPOLIA",
        "custodyType": "DEVELOPER",
        "username": "john_doe",
        "userRefId": "8b9b8143-b580-4173-a742-f5ee2fe45c1f",
        "walletSetId": "6519c5d92b8a095cb141ca0f",
        "userId": "659235cf2de7864ba34d2d8d"
    }],
    "message": "Wallet created successfully"
}

3. Acquire Gas Tokens

In web3 and blockchain technology, "gas" refers to a unit of measurement for the computational work required to execute a transaction or perform an operation on the blockchain. Gas is used to quantify the amount of resources a transaction consumes, including computational power and network bandwidth, and it also determines the fees a user must pay to miners or validators to have their transaction included in the blockchain and is always paid in the native currency of that blockchain. For instance, when sending a BEP-20 token on the Binance Smart Chain, the transaction fee would be paid in BNB. Likewise, on the Ethereum network, the fee is denominated in ETH, and the same applies to its Sepolia Testnet, which is the one we are currently utilising. It's essential to have a certain quantity of the native token in your wallet to ensure the seamless processing of transactions.

Acquire Sepolia ETH tokens through the Alchemy Sepolia Faucet and proceed to transfer them to the wallet address provided in the response body from running the previous step.

4. Check Wallet Balance

Make sure the wallet successfully received the Sepolia ETH tokens, before proceeding.

Check the wallet balance by making a request to GET /wallets/{id}/developer/balances.

curl --request GET \
     --url 'https://api.planbok.io/v1/wallets/651c2d6981e7406eca0ac139/developer/balances' \
     --header 'accept: application/json' \
     --header 'planbok-x-api-key: <API_KEY>'

{
    "status": 200,
    "tokenBalances": [
        {
            "amount": "0.02",
            "token": {
                "id": "6619cd4c5ad2007ede6f8ff4",
                "name": "SEPOLIA ETH",
                "standard": "NATIVE",
                "blockchain": "ETH-SEPOLIA",
                "symbol": "sETH",
                "createdAt": "2023-10-01T19:59:06.007Z",
                "updatedAt": "2023-10-01T19:59:06.007Z"
            },
            "updatedAt": "2023-10-06T10:37:32.955Z"
        }
    ],
    "message": "Token balances found"
}

5. Transfer Tokens

Make a request to POST /transactions/transfer/developer with Sepolia ETH's token.id, created wallet's wallets[0].id, your destination wallet address, as well as some predefined values for amount, and gas related request parameters.

curl --request POST \
     --url 'https://api.planbok.io/v1/transactions/transfer/developer' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'planbok-x-api-key: <API_KEY>' \
     --data '
     {
          "idempotencyKey": "f710e18f-b4e7-477a-9f13-e08b856b0944",
          "destinationAddress": "0x9f5E5288bD3329838F51536DC94F3F2b837EB578",
          "walletId": "651c2d6981e7406eca0ac139",
          "tokenId": "6619cd4c5ad2007ede6f8ff4",
          "amount": 0.001,
          "feeLevel": "LOW",
          "walletSetSecretCipherText": "<WALLET_SET_SECRET_CIPHER_TEXT>"
     }'

Response body

{
    "status": 201,
    "data": {
        "id": "651cb86e43e7856f778da99f",
        "state": "PENDING"
    }
}

6. Check Transaction State

Make a request to GET /transactions/{id}/developer?walletId={walletId} to return the specific transaction details using the id from previous step response body.

curl --request GET \
     --url 'https://api.planbok.io/v1/transactions/651cb86e43e7856f778da99f/developer?walletId=651c2d6981e7406eca0ac139' \
     --header 'accept: application/json' \
     --header 'planbok-x-api-key: <API_KEY>'

{
    "status": 200,
    "data": {
        "id": "651cb86e43e7856f778da99f",
        "amount": "0.001",
        "sourceAddress": "0xa0780f1403419ad992cA0420AAb81a4562e179dd",
        "destinationAddress": "0x9f5E5288bD3329838F51536DC94F3F2b837EB578",
        "nonce": 0,
        "walletId": "651c2d6981e7406eca0ac139",
        "blockchain": "ETH-SEPOLIA",
        "transferType": "OUTBOUND",
        "state": "COMPLETE",
        "txHash": "0x778297960e09ff889da8c8e322e450a3b26874c496b5080be28eeaa8dbdc33a9",
        "blockHash": "0x949ddb4f19ba8da5260719d521113ca7009bd33666d76907e183aba01de07ccd",
        "blockHeight": 9809524,
        "operation": "TRANSFER",
        "abiParameters": [],
        "token": "6619cd4c5ad2007ede6f8ff4",
        "firstConfirmDate": "2023-10-07T19:10:13.375Z",
        "networkFee": "0.000189 sETH",
        "createdAt": "2023-10-07T15:08:56.422Z",
        "updatedAt": "2023-10-07T15:10:18.675Z"
    }
}

When the transaction.state is COMPLETE, this means that the token has sent from the your wallet to the destination wallet.

You can also check the transaction using the txHash on Sepolia Etherscan, inspect the balance of each wallet and compare with their previous balances.