Upgrade from WaaS 1.0 to 2.0

Try Cobo WaaS Skill in your AI coding assistant (Claude Code, Cursor, etc.). Describe your needs in natural language to auto-generate production-ready SDK code and debug faster 🚀

This article is targeted at WaaS 1.0 users who are considering upgrading to WaaS 2.0. It introduces the benefits of the upgrade and provides step-by-step instructions to successfully complete the upgrade process.

Key enhancements in WaaS 2.0

WaaS 2.0 is a major upgrade from WaaS 1.0, designed to support diverse Web3 scenarios such as payments, tokenization, and automated fund management. It enables enterprises and developers to build Web3 applications more efficiently and cost-effectively. The three core benefits of upgrading to WaaS 2.0 are:

Enhanced capabilities: Introduces new modules including Payment Solutions, Tokenization, Fee Station, Auto-sweep, Travel Rule, and more.
More efficient development: A unified API architecture reduces the number of API calls required to accomplish the same functionality, lowering integration and maintenance complexity.
Improved operations: Upgraded webhook functionality supports more event types and provides built-in tools such as logs, retries, and simulated testing, enhancing observability and debugging efficiency.

For a complete introduction to WaaS 2.0, see Introduction to WaaS 2.0. The following table summarizes the key enhancements introduced in WaaS 2.0 compared with WaaS 1.0:

Dimension	WaaS 1.0	WaaS 2.0
API Architecture	Wallet-type-based structure: The same business functionality required different API operations depending on wallet type. For example: Withdrawals for Custodial Wallets and MPC Wallets required separate API operations. Querying a transaction by different IDs (such as transaction hash, transaction ID, internal ID) also required separate API operations.	Scenario-driven structure: The same business functionality can now be completed with a single API operation. For example: The token transfer operation can handle deposits and withdrawals for all wallet types. Transaction queries are unified under a single API operation and support any type of ID.
New Feature Modules	N/A	Payment: A complete cryptocurrency payment solution. Tokenization: Issue and manage tokenized on-chain assets. Fee Station: Handle gas fees and manage unified cost settlements. Auto-sweep: Automatically consolidate token balances. Travel Rule: Meet more comprehensive regulatory compliance requirements. Cobo Portal Apps: Develop and manage apps within the Cobo Portal ecosystem.
Webhook Mechanism	Only supported transaction status notifications.	Support for more event types: Includes transaction, wallet, address, balance, and TSS-related events. Built-in debugging tools: Provides logs, automatic retries, and simulated event testing.
Developer Tools	Provided basic SDKs.	Expands the developer ecosystem with additional tools: Cobo CLI: A command-line tool for rapid testing and debugging. UI Toolkit: Pre-built UI components to accelerate app development.

Technical changes and migration reference

This section is intended for developers. It explains the key technical changes between WaaS 1.0 and WaaS 2.0 in areas such as API design, authentication, and callback mechanisms, and provides a comparison table of common API operations to help you migrate quickly.

Technical changes

The following table summarizes the key technical changes between WaaS 1.0 and WaaS 2.0, including API design, authentication, and callback mechanisms.

	WaaS 1.0	WaaS 2.0
API design	HTTP endpoints supporting the GET and POST methods.	RESTful API structured into distinct domains, such as wallets, transactions, and webhooks. The API follows resource-oriented design principles for endpoint definition and supports standard HTTP methods including GET, POST, PUT, and DELETE.
API key and authentication	The API key is wallet-specific, meaning it can only be used to access the associated wallet. An SECP256k1 signature is used for authenticating an API request.	The API key is organization-specific and can be used to access multiple wallets. For more information, refer to Register an API key. An ED25519 signature is used for authenticating an API request.
Transaction notification	Supports transaction status-related events only.	This feature is called “Webhook” in 2.0. Supports transaction status and TSS request-related events, and the list is still growing. The data structure of the webhook event differs from 1.0.
Withdrawal confirmation	A mechanism used for confirming withdrawals initiated through WaaS API.	This feature is called “Callback” in 2.0. The data structure of the callback message differs from 1.0.
Supported wallet types	Custodial Wallets MPC Wallets	Custodial Wallets MPC Wallets Exchange Wallets
Asset model	A coin is considered a unique asset type. A coin represents a specific pairing of a chain and a cryptocurrency, such as ETH_USDT.	A token is considered a unique asset type, except for Exchange Wallets, which consider an “asset” to be a unique asset type. A token represents a specific pairing of a chain and a cryptocurrency, such as ETH_USDT. An asset represents a cryptocurrency stored in your linked exchange account, such as USDT.
Balance model	[Custodial Wallets] Coin balances can be calculated for an entire wallet but not for each address. [MPC Wallets] Coin balances can be calculated for each address within the wallet, but not for an entire wallet.	[Custodial Wallets] Token balances can be calculated for the entire wallet but not for each address. [MPC Wallets] Token balances can be calculated for the entire wallet or each address.
Balances and amounts	Balances and amounts are denominated in the smallest units of the cryptocurrency. For example, Bitcoin balances and amounts are denominated in Satoshis. The parameters `abs_balance` and `abs_amount` are denominated in the primary unit of the cryptocurrency, such as BTC for Bitcoin.	Balances and amounts are denominated in the primary unit of the cryptocurrency, such as BTC for Bitcoin. As an example, for a deposit of 1.2 BTC, the deposit amount is recorded as `120,000,000` in 1.0 and `1.2` in 2.0.
Address generation	[Custodial Wallets] Addresses are generated based on a specified coin, such as ETH_USDT, and can then be used by all coins on the same chain. [MPC Wallets] Addresses are generated based on a specified chain, such as ETH, and can then be used by all coins on the same chain.	[Custodial Wallets / MPC Wallets] Addresses are generated based on a specified chain, such as ETH, and can then be used by all tokens on the same chain.
Transaction ID	The unique ID of a transaction.	The transaction ID in 2.0 follows the UUID format which differs from the format used in 1.0. The transaction ID in 1.0 is termed as “Cobo ID” in 2.0. You can continue to use Cobo ID to query a transaction.

API operation comparison

The following table lists the API operations needed for common wallet operations in WaaS 1.0 and 2.0 respectively. You can refer to this table when migrating your code from 1.0 to 2.0.

	WaaS 1.0	WaaS 2.0
Create a wallet	Not supported since the API key is wallet-specific	Create wallet
Create an address	[Custodial Wallets] Get New Deposit Address [MPC Wallets] Generate Addresses and Generate Address Memos	Create addresses in wallet
Withdraw tokens	[Custodial Wallets] New withdraw request [MPC Wallets] Create Transaction	Transfer token
RBF transaction (Speed up)	[MPC Wallets] Speedup Transaction	Speed up transaction
RBF transaction (Drop)	[MPC Wallets] Drop Transaction	Drop transaction
Cancel transaction	Not supported	Cancel transaction
Call a contract	Not supported	Call smart contract
Sign a message	Not supported	Sign message
Query a transaction	[Custodial Wallets] Transaction history [MPC Wallets] Get Transactions List	List all transactions Get transaction information

WaaS 2.0 list endpoints, such as List all transactions, return results in pages. By default each page returns 10 records, and the maximum page size is 50, set with the limit parameter. This differs from WaaS 1.0, where a single response could return all results. A single WaaS 2.0 page therefore omits later results. To retrieve every record, iterate through all pages using the cursor parameters before and after.

Upgrade to 2.0

This section introduces the detailed steps to upgrade from WaaS 1.0 to 2.0.

Prerequisites

Reach out to our support team at help@cobo.com to migrate from Cobo Custody to Cobo Portal.

Get started with WaaS 2.0

Follow the instructions in Send your first request to set up your account, create and register your API key, integrate a WaaS SDK if necessary, and send your first API request to the WaaS 2.0 service.

Rewrite your code

Once you complete the initial setup, it is time to rewrite your code by replacing the 1.0 API operations with 2.0 operations. Refer to API operation comparison for a detailed comparison between 1.0 and 2.0 API operations. You can also refer to Get started with Custodial Wallets (Asset Wallets) for a step-by-step guide on how to create a Custodial Wallet (Asset Wallet), generate wallet addresses, and receive and withdraw tokens. Guides for other wallet types will be available in the future.

Set up webhook and callback endpoints

Set up the webhook and callback endpoints and register them in Cobo Portal. To understand webhook events, callback messages, and the differences in webhook/callback mechanisms between WaaS 1.0 and WaaS 2.0, refer to Introduction to webhooks and callbacks. To learn the detailed steps of the setup, see Set up a callback or webhook endpoint. To register the endpoint, see Register a webhook endpoint and Register a callback endpoint.

The endpoints you set up for WaaS 1.0 will not receive any messages from the WaaS 2.0 service.

Overview

Get started

Webhooks and callbacks

Transactions

MPC Wallets

Resources

Upgrade from WaaS 1.0 to 2.0

Key enhancements in WaaS 2.0

Technical changes and migration reference

Technical changes

API operation comparison

Upgrade to 2.0

Prerequisites

Get started with WaaS 2.0

Rewrite your code

Set up webhook and callback endpoints

​Key enhancements in WaaS 2.0

​Technical changes and migration reference

​Technical changes

​API operation comparison

​Upgrade to 2.0

​Prerequisites

​Get started with WaaS 2.0

​Rewrite your code

​Set up webhook and callback endpoints

Key enhancements in WaaS 2.0

Technical changes and migration reference

Technical changes

API operation comparison

Upgrade to 2.0

Prerequisites

Get started with WaaS 2.0

Rewrite your code

Set up webhook and callback endpoints