Quickstart#

In this chapter, we will introduce how to quickly use the Wallet API. In just three steps, you will become familiar with the essential steps of using OKX WaaS services and use JavaScript to quickly build a program example for creating a wallet account.

Step 1: Preparation#

Create a project and generate an API key. Before using the Wallet API, you need to create a project and generate an API key on the developer management platform. Here are the detailed steps and related resources:

Log in to the developer management platform.
Create a new project.
Generate an API key in the project settings.

We have prepared a detailed guide to help you complete these steps. You can read the Developer Management Platform Guide to get started quickly.

Additionally, you need to do some basic configuration for making calls.

REST Request Authentication Configuration#

When sending REST requests, you need to authenticate. We provide a detailed REST Request Authentication Guide to help you understand and implement this process.

Node.js Environment Setup#

Import the necessary Node.js libraries, set up your environment variables, and define helper functions and assemble parameters Node.js Environment Setup.

Step 2: Generate Wallet Private Key and Address#

Next, we introduce how to use the WaaS Wallet SDK to create a wallet mnemonic and address. If you have already generated the wallet private key and address yourself, you can skip this step and go directly to the next step.

This quick start uses the JavaScript SDK js-wallet-sdk as an example. For SDKs in other languages, refer to OKX WaaS Wallet SDK Details.

npm install#

To use the SDK, you first need to install it. You can use npm to install the latest version.

Our SDK supports two types of packages: public packages and single-coin modules.

Public packages for all coins:

npm install @okxweb3/crypto-lib
npm install @okxweb3/coin-base

Single-coin packages, usually for single-chain coins, e.g., for ETH:

npm install @okxweb3/coin-ethereum

To learn how to build JavaScript SDKs for other chains, please see the SDK reference for details. This chapter continues with ETH for subsequent operations.

Local Build#

Download the project source code

git clone https://github.com/okx/js-wallet-sdk.git

Run the build script

sh build.sh

Using the EVM network as an example, you can create an EVM wallet object with the SDK and derive the corresponding address with the following code.

import { bip39, BigNumber } from "@okxweb3/crypto-lib";
import { EthWallet } from "@okxweb3/coin-ethereum";

// eth wallet
let wallet = new EthWallet();

// get mnemonic
let mnemonic = await bip39.generateMnemonic();
console.log("generate mnemonic:", mnemonic);

// get derived key
const hdPath = await wallet.getDerivedPath({ index: 0 });
let derivePrivateKey = await wallet.getDerivedPrivateKey({ mnemonic: mnemonic, hdPath: hdPath });
console.log("generate derived private key:", derivePrivateKey, ",derived path: ", hdPath);

// get new address
let newAddress = await wallet.getNewAddress({ privateKey: derivePrivateKey });
console.log("generate new address:", newAddress.address);

// get the public key
let publicKey = newAddress.publicKey;
console.log("the corresponding public key:", publicKey);

Demo Program#

We have prepared an open-source demo program to showcase the functionalities involved in the SDK above. Get the demo program source code here.

Step 3: Create a Wallet Account#

Unlike the general single-address query mode, OKX WaaS provides a structured subscription query for multiple addresses. You can associate multiple addresses with one wallet account, efficiently querying asset statuses and transaction histories across multiple chains. We offer two types of wallet accounts: user wallet accounts and watch-only wallet accounts.

User Wallet Account: Requires message signature for authentication, allows adding custom tokens, and can send transactions.
Watch-only Wallet Account: Does not require message signature, displays all tokens listed on the OKX platform by default, and cannot send transactions.

In the following steps, we use the user wallet account as an example.

Generate a UNIX Timestamp Message Signature#

let now = new Date();

let timestamp = now.getTime();

let timestampString = timestamp.toString();

console.log(timestampString);

let signParams = {
  privateKey: derivePrivateKey,
  data: timestampString
}

let signature = await wallet.signMessage(signParams);
console.log(signature);

Call the Create Account API#

Use the obtained address, publicKey, signature, signMessage, and chainIndex information to call the POST /api/v5/waas/account/create-account API to create a user wallet.

// Define your parameters
const addresses = [
    {
      "chainIndex":"1",
      "address":"0x561815e02bac6128bbbbc551005ddfd92a5c24db",
      "publicKey":"02012db63bf0380294a6ecf87615fe869384b0510cb910a094254b6844af023ee2",
      "signature":"62acda5e471d9bf0099add50f4845256868d980821c161095651a918d3ef8a6b2286f512028172eabbe46ec2c9c2c20e5c40ff1fb23e1cdfdbed033ad924ce521b"
    },
    {
      "chainIndex":"10",
      "address":"0x561815e02bac6128bbbbc551005ddfd92a5c24db",
      "publicKey":"02012db63bf0380294a6ecf87615fe869384b0510cb910a094254b6844af023ee2",
      "signature":"62acda5e471d9bf0099add50f4845256868d980821c161095651a918d3ef8a6b2286f512028172eabbe46ec2c9c2c20e5c40ff1fb23e1cdfdbed033ad924ce521b"
    }
];

const getCreateAccountBody = {
    addresses: addresses,
    signMessage: '1717062864123', // UNIX Timestamp in millisecond
};

// Define helper function
const getCreateAccountData = async () => {
    const apiRequestUrl = getRequestUrl(
      apiBaseUrl,
      '/api/v5/waas/account/create-account'
    );
    return fetch(apiRequestUrl, {
      method: 'post',
      headers: headersParams,
      body: JSON.stringify(getCreateAccountBody),
    })
      .then((res) => res.json())
      .then((res) => {
        return res;
      });
  };

const { data: createAccountData } = await getCreateAccountData();

To create a watch-only wallet, call the POST /api/v5/waas/account/create-watch-only-account API.

// Define your parameters
const addresses = [
    {
      "chainIndex":"1",
      "address":"0x561815e02bac6128bbbbc551005ddfd92a5c24db",
    },
    {
      "chainIndex":"10",
      "address":"0x561815e02bac6128bbbbc551005ddfd92a5c24db",
    }
];

const getCreateWatchOnlyAccountBody = {
    addresses: addresses,
};

// Define helper function
const getCreateWatchOnlyAccountData = async () => {
    const apiRequestUrl = getRequestUrl(
      apiBaseUrl,
      '/api/v5/waas/account/create-watch-only-account'
    );
    return fetch(apiRequestUrl, {
      method: 'post',
      headers: headersParams,
      body: JSON.stringify(getCreateWatchOnlyAccountBody),
    })
      .then((res) => res.json())
      .then((res) => {
        return res;
      });
  };

const { data: createWatchOnlyAccountData } = await getCreateWatchOnlyAccountData();

Upon a successful call, you will receive the following response:

{
    "code": 0,
    "data": [{
            "accountId": "13886e05-1265-4b79-8ac3-b7ab46217655"
    }],
    "msg": "success"
}

Next, you can implement asset queries, transaction sending, and other functionalities around accountId by calling the API.

Feel free to check out the API Reference and SDK Referencee.

Table of contents

Step 2: Generate Wallet Private Key and Address

Step 3: Create a Wallet Account