Skip to main content

​
Overview

This guide explains how to get started with using the Wallet-as-a-Service (WaaS) 2.0 API. By the end of this guide, you will be able to successfully call an API operation and receive a response.

​
Before you begin

If you choose to use a WaaS SDK instead of manually writing the API requests, you need to first install the right version of the corresponding programming language. For example, if you want to use the Python SDK, you need to have Python 3.7 or a newer version installed.

​
Set up an account

Follow the instructions in Set up your account and organization to set up your Cobo account and create your organization. If an organization has already been set up, ask your organization admin to invite you to join the organization.
This guide uses the development environment in all of its examples. Please create your organization in the development environment at https://portal.dev.cobo.com/.

​
Generate an API key and an API secret

Generate an Ed25519 key pair as the API key and API secret. This guide uses OpenSSL as an example. To learn other methods for generating an API key and an API secret, see Generate an API key and an API secret.
  1. In a terminal window, run the following OpenSSL commands:
# Generate a private key and save it in the `private.key.pem` file.
openssl genpkey -algorithm ed25519 -out private_key.pem

# Extract the public key from the private key and save it in the `public.key.pem` file.
openssl pkey -in private_key.pem -pubout -out public_key.pem
The private key is saved in the private.key.pem file, and the public key is saved in the public.key.pem file.
  1. You can print the keys by running the following commands:
# Export the private key in hexadecimal format.
openssl pkey -in private_key.pem -text | grep 'priv:' -A 3 | tail -n +2 | tr -d ':\n '

# Export the public key in hexadecimal format.
openssl pkey -pubin -in public_key.pem -text | grep 'pub:' -A 3 | tail -n +2 | tr -d ':\n '

​
Register the API key

Register your API key and configure related permissions on Cobo Portal. To learn more about registering an API key, see Register an API key.
  1. Log in to Cobo Portal (development environment).
  2. On the left navigation menu, click Developer > API Keys.
  3. Click Register API Key.
  4. Enter the API key name (maximum 30 characters).
  5. Enter the public key you have generated in the previous step.
  6. Under Role & Wallet Scope, set Viewer as the user role and All Wallets as the wallet scope. Each user role is permitted to call a specific set of operations, and the wallet scope determines the set of wallets this API key can access.
  7. Click Confirm to save the changes.
  8. Select Temporary as the key type.
    If you already have a static IP address, you can select Permanent as the key type instead and enter your IP address in IP Whitelist.
  9. Click Register.
  10. Notify your organization admins to approve the request on Cobo Guard.
    By default, it requires the approval of at least half of the admins to successfully register an API key.
You can only start using an API key after its status becomes Active.

​
Authenticate your requests

You can skip this step if you choose to use a WaaS SDK, which encapsulates the authentication mechanism.
To authenticate your API request, you need to provide your API key, a nonce, and the API signature as request headers. For more information, see Cobo Auth. 
headers = {
  "Biz-Api-Key": {YOUR_API_KEY}.hex(),
  "Biz-Api-Nonce": {Nonce},
  "Biz-Api-Signature": {YOUR_API_SIGNATURE}.hex(),
}
  • Biz-Api-Key: The API key. To learn how to generate an API key, see Generate an API key and an API secret.
  • Biz-Api-Nonce: A nonce is the current time in Unix timestamp format, measured in milliseconds.
  • Biz-Api-Signature: The API signature. To learn how to calculate an API signature, see Calculate an API Signature.

​
Send a request

You can skip this step if you choose to use a WaaS SDK, which offers ready-to-use functions that handle the API integration using the programming language of your project.
This guide uses the List supported chains operation as an example to demonstrate how to send an API request. This operation retrieves all chains supported by a specific wallet type or subtype. In the following example, we retrieve all chains supported by Custodial Wallets. 
curl --location --request GET 'https://api.dev.cobo.com/v2/wallets/chains?wallet_type=Custodial&wallet_subtype=&chain_ids=&limit=10&before=&after='
  
  # Replace the following with your own authentication information
  --header 'BIZ-API-KEY: {YOUR_API_KEY}' \
  --header 'Biz-Api-Nonce: {NONCE}' \
  --header 'Biz-Api-Signature: {YOUR_API_SIGNATURE}'
If the request is successful, you should receive the following response: 
{
    "data": [
        {
            "chain_id": "ARBITRUM_ETH",
            "symbol": "Arbitrum",
            "icon_url": "https://d.cobo.com/public/logos/ARB.png",
            "explorer_tx_url": "https://arbiscan.io/tx/{txn_id}",
            "explorer_address_url": "https://arbiscan.io/address/{address}",
            "require_memo": false
        },
        {
            "chain_id": "AVAXC",
            "symbol": "Avalanche C-Chain",
            "icon_url": "https://d.cobo.com/public/logos/AVAXC-logo.png",
            "explorer_tx_url": "https://avascan.info/blockchain/c/tx/{txn_id}",
            "explorer_address_url": "https://avascan.info/blockchain/c/address/{address}",
            "require_memo": false
        },
        ...
    ],
    "pagination": {
        "before": "",
        "after": "41KxruMakf",
        "total_count": 19
    }
}

​
Use a WaaS SDK

This section introduces how to use the Python SDK to call an API operation instead of manually writing the request. To learn how to install the Python SDK and complete the initial setup, refer to Get started with Python SDK. The following is the sample code for calling the List supported chains operation. When configuring the HTTP host, please use the URL of the development environment because you have registered the API key in the development environment in the previous step. 
import cobo_waas2
from pprint import pprint

configuration = cobo_waas2.Configuration(
   # Replace `<YOUR_API_SECRET>` with your API secret.
   api_private_key="<YOUR_API_SECRET>",
   # Use the development environment 
   host="https://api.dev.cobo.com/v2"
)

# Enter a context with an instance of the API client
with cobo_waas2.ApiClient(configuration) as api_client:
   # Create an instance of the API class
   api_instance = cobo_waas2.WalletsApi(api_client)
   try:
       # List all supported chains
       api_response = api_instance.list_supported_chains()
       print("The response of WalletsApi->list_supported_chains:\n")
       pprint(api_response)
   except Exception as e:
       print("Exception when calling WalletsApi->list_supported_chains: %s\n" % e)

​
What’s next

You have successfully sent an API request and received a response. However, there are still a few things to do before you can create a wallet, make a transaction, or implement other features.
  • To start using a wallet, you must purchase a pricing plan or activate a trial plan if it is available. To learn about pricing plans and bills and payments, refer to Introduction to Bills & Payments.
  • To withdraw tokens from your wallet, you must first set up a callback endpoint to receive and approve withdrawal requests. It is highly recommended that you also set up a webhook endpoint to receive real-time notifications regarding transaction status updates and other events of your concern. To learn how to set up and register webhook and callback endpoints, refer to Introduction to webhooks and callbacks.

​
See also