> ## Documentation Index
> Fetch the complete documentation index at: https://cobo.com/developers/llms.txt
> Use this file to discover all available pages before exploring further.
# Integrate MPC Wallets (Organization-Controlled Wallets)
Try [Cobo WaaS Skill](/v2/guides/overview/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 🚀
After you have familiarized yourself with MPC Wallets through the [Cobo Portal quick start guide](https://manuals.cobo.com/en/portal/quick-start-guide-mpc), this guide will help you seamlessly integrate the MPC Wallet (Organization-Controlled Wallets) functionality into your application using the WaaS 2.0 API.
Following this guide, you'll learn how to:
1. Create a wallet
2. Deposit and withdraw tokens
3. Query wallet balances
This guide uses the [development environment](/v2/guides/overview/environments) in all its code samples. It is recommended that you use the development environment to test your new features first before deploying them to the production environment.
## Technical architecture
Before you begin, it's helpful to understand the technical architecture of MPC Wallets, including the relationships between vaults, wallets, addresses, and key shares. The following diagram illustrates the components within a fully-functioning MPC vault:
* An Organization-Controlled Wallet is always associated with a vault. A vault is a collection of Organization-Controlled Wallets that share the same root extended public/private key pairs.
* Root extended public keys: A root extended public key is used in hierarchical deterministic (HD) wallets to derive multiple child public keys and addresses. Each vault has two root extended public keys, one derived from the Secp256k1 curve (used by chains such as Bitcoin and Ethereum) and the other derived from the EdDSA curve (used by chains such as Solona and TON). To learn more about root extended public keys, see [Key derivation](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki#specification-key-derivation).
* Key share holders: Each vault can have multiple types of key share holders, including Main Key, Signing Key, and Recovery Key. Each key share holder has a set of TSS Nodes storing the private key shares that can collectively sign a transaction or recover the root extended private key. For Main Key and Signing Key, one key share holder will always be Cobo. To learn more about key share holders, see [Key share holders overview](https://manuals.cobo.com/en/portal/mpc-wallets/ocw/holder-group-overview).
* TSS key share groups: Each TSS key share group consists of two or three private key shares, depending on the number of holders. Each key share group can form a key pair with the root extended public key derived from the same curve. Each key share is unique.
## Prerequisites
* Before you call the WaaS API to create a wallet, you must first follow the instructions in the [Cobo Portal quick start guide](https://manuals.cobo.com/en/portal/quick-start-guide-mpc#set-up-an-mpc-vault) to set up a vault.
* Follow the instructions in [Send your first request](/v2/guides/get-started/get-started-with-waas) to set up your account and send your first API request to the WaaS 2.0 service.
* If you choose to use a WaaS SDK instead of manually writing the API requests, refer to the SDK guide corresponding to the programming language of your choice ([Python](/v2/developer-tools/quickstart-python), [Java](https://github.com/CoboGlobal/cobo-waas2-java-sdk), [Go](/v2/developer-tools/quickstart-go), [JavaScript](https://github.com/CoboGlobal/cobo-waas2-js-sdk)) to integrate the SDK into your project.
## 1. Create a wallet
Once you have set up a vault, create a key share holder, and generate key shares, you can proceed to create a wallet. Call the [Create wallet](/v2/api-references/wallets/create-wallet) operation and specify the properties in the request body as follows:
* `name`: Your wallet name.
* `wallet_type`: `MPC`.
* `wallet_subtype`:`Org-Controlled`.
* `vault_id`: The ID of the vault you have just created.
Upon successful completion of the request, the response will include the wallet ID, which is the unique identifier of the wallet you have just created. Store this wallet ID as you will need it for subsequent steps.
```py theme={null}
import json
import cobo_waas2
from cobo_waas2.models.create_wallet_params import CreateWalletParams
from cobo_waas2.models.created_wallet_info import CreatedWalletInfo
from cobo_waas2.models.wallet_subtype import WalletSubtype
from cobo_waas2.models.wallet_type import WalletType
from cobo_waas2.rest import ApiException
from pprint import pprint
# Defining the host is optional and defaults to https://api.dev.cobo.com/v2
# See configuration.py for a list of all supported configuration parameters.
configuration = cobo_waas2.Configuration(
api_private_key="",
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)
create_wallet_params = cobo_waas2.CreateWalletParams(
actual_instance=cobo_waas2.CreateMpcWalletParams(
name="",
wallet_type=WalletType.MPC,
wallet_subtype=WalletSubtype.ORG_CONTROLLED,
vault_id=""
)
)
try:
# Create a wallet
api_response = api_instance.create_wallet(create_wallet_params=create_wallet_params)
print("The response of WalletsApi->create_wallet:\n")
print(json.dumps(api_response.to_dict(), indent=2))
except Exception as e:
print("Exception when calling WalletsApi->create_wallet: %s\n" % e)
```
```java theme={null}
import com.cobo.waas2.ApiClient;
import com.cobo.waas2.ApiException;
import com.cobo.waas2.Configuration;
import com.cobo.waas2.Env;
import com.cobo.waas2.api.WalletsApi;
import com.cobo.waas2.model.*;
public class CreateWalletExample {
public static void main(String[] args) {
ApiClient defaultClient = Configuration.getDefaultApiClient();
// Use the development environment
defaultClient.setEnv(Env.DEV);
// Replace `` with your API secret
defaultClient.setPrivKey("");
WalletsApi apiInstance = new WalletsApi();
try {
CreateMpcWalletParams params = new CreateMpcWalletParams()
.name("OCW Example Wallet Demo(Java)")
.walletType(WalletType.MPC)
.walletSubtype(WalletSubtype.ORG_CONTROLLED)
.vaultId("");
CreatedWalletInfo result = apiInstance.createWallet(new CreateWalletParams(params));
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling WalletsApi#createWallet");
System.err.println("Status code: " + e.getCode());
System.err.println("Reason: " + e.getResponseBody());
System.err.println("Response headers: " + e.getResponseHeaders());
e.printStackTrace();
}
}
}
```
## 2. Deposit and withdraw tokens
After setting up an Organization-Controlled Wallet, it is time to deposit some tokens into it and learn how to make withdrawals.
### Generate deposit addresses
To receive tokens, you need to generate deposit addresses within the wallet. To do so, call the [Create addresses in wallet](/v2/api-references/wallets/create-addresses-in-wallet) operation and specify the parameters and properties as follows:
* Path:
* `wallet_id`: The ID of the wallet you have just created.
* Request body:
* `chain_id`: The ID of the blockchain.
* `count`: Use this parameter to specify the number of addresses you want to create.
Upon successful completion of the request, the response will include the addresses you have just created. You can now proceed to deposit tokens into these addresses.
```py theme={null}
import json
import cobo_waas2
from cobo_waas2 import (
CreateAddressRequest,
AddressEncoding,
)
configuration = cobo_waas2.Configuration(
# Replace `` with your API secret
api_private_key="",
# 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
wallet_api_instance = cobo_waas2.WalletsApi(api_client)
try:
# Generate two addresses on the Bitcoin testnet3 (XTN) chain using P2TR encoding
api_response = wallet_api_instance.create_address(
wallet_id="",
create_address_request=CreateAddressRequest(
chain_id="XTN", count=2, encoding=AddressEncoding.ENCODING_P2_TR
),
)
print("The response of WalletsApi->create_address:")
for address_info in api_response:
print(json.dumps(address_info.to_dict(), indent=2))
except Exception as e:
print("Exception when calling WalletsApi->create_address, %s\n", e)
```
```java theme={null}
import com.cobo.waas2.ApiClient;
import com.cobo.waas2.ApiException;
import com.cobo.waas2.Configuration;
import com.cobo.waas2.Env;
import com.cobo.waas2.api.WalletsApi;
import com.cobo.waas2.model.AddressEncoding;
import com.cobo.waas2.model.AddressInfo;
import com.cobo.waas2.model.CreateAddressRequest;
import java.util.List;
import java.util.UUID;
public class CreateAddressExample {
public static void main(String[] args) {
ApiClient defaultClient = Configuration.getDefaultApiClient();
// Use the development environment
defaultClient.setEnv(Env.DEV);
// Replace `` with your API secret
defaultClient.setPrivKey("");
WalletsApi apiInstance = new WalletsApi();
try {
UUID wallet_id = UUID.fromString("");
CreateAddressRequest params = new CreateAddressRequest()
.chainId("XTN")
.count(2)
.encoding(AddressEncoding.BECH32);
List result = apiInstance.createAddress(wallet_id, params);
for (AddressInfo addressInfo : result)
System.out.println(addressInfo);
} catch (ApiException e) {
System.err.println("Exception when calling WalletsApi#createAddress");
System.err.println("Status code: " + e.getCode());
System.err.println("Reason: " + e.getResponseBody());
System.err.println("Response headers: " + e.getResponseHeaders());
e.printStackTrace();
}
}
}
```
### Process deposit
After depositing tokens to the addresses you have generated, you can track the status of your deposit using one of the following two options. Compared with using API to query the transaction status, webhooks can give you real-time notifications and are thus the recommended option.
#### Option 1: Use webhooks for real-time notifications
Webhook is an essential mechanism for the WaaS service to communicate with your application. After you register a webhook endpoint on Cobo Portal, the WaaS service sends push messages to the designated URL when an event occurs.
To learn how to set up a webhook endpoint and register it on Cobo Portal, refer to [Introduction to webhooks and callbacks](/v2/guides/webhooks-callbacks/introduction).
To track the status of your deposit, you can subscribe to the following webhook event types:
* wallets.transaction.created
* wallets.transaction.updated
* wallets.transaction.succeeded
* wallets.transaction.failed
To learn the trigger condition and data structure of each event type, refer to [Webhook event types and data types](/v2/guides/webhooks-callbacks/webhook-event-type).
#### Option 2: Get transaction status by API call
To query the status of a deposit transaction, call the [List all transactions](/v2/api-references/transactions/list-all-transactions) operation and set the query parameters as follows:
* `types`: `Deposit`.
* `statuses`: `Confirming, Completed`. If you are depositing from an external address, you will be able to query the transaction details when the transaction is waiting for the required number of confirmations or when it is successfully executed.
* `wallet_ids`: The ID of the wallet you have created in the first step.
```python theme={null}
import json
import uuid
import cobo_waas2
from cobo_waas2 import (
CreateAddressRequest,
AddressEncoding,
TransferParams,
TransferSource,
MpcTransferSource,
WalletSubtype,
TransferDestination, AddressTransferDestination, TransferDestinationType, AddressTransferDestinationAccountOutput,
)
configuration = cobo_waas2.Configuration(
# Replace `` with your API secret.
api_private_key="",
# 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
transaction_api_instance = cobo_waas2.TransactionsApi(api_client)
try:
# List deposit transactions
api_response = transaction_api_instance.list_transactions(
types="Deposit",
statuses="Confirming, Completed",
wallet_ids=""
)
print("The response of TransactionsApi->list_transactions:")
print(json.dumps(api_response.to_dict(), indent=2))
except Exception as e:
print("Exception when calling TransactionsApi->list_transactions, %s\n", e)
```
```java theme={null}
import com.cobo.waas2.ApiClient;
import com.cobo.waas2.ApiException;
import com.cobo.waas2.Configuration;
import com.cobo.waas2.Env;
import com.cobo.waas2.api.TransactionsApi;
import com.cobo.waas2.model.ListTransactions200Response;
import java.util.UUID;
public class ListTransactionsExample {
public static void main(String[] args) {
ApiClient defaultClient = Configuration.getDefaultApiClient();
// Use the development environment
defaultClient.setEnv(Env.DEV);
// Replace `` with your API secret
defaultClient.setPrivKey("");
TransactionsApi apiInstance = new TransactionsApi();
try {
String requestId = null;
String coboIds = null;
String transactionIds = null;
String transactionHashes = "";
String types = "Deposit";
String statuses = "Confirming, Completed";
String walletIds = "";
String chainIds = null;
String tokenIds = null;
String assetIds = null;
UUID vaultId = null;
UUID projectId = null;
Long minCreatedTimestamp = null;
Long maxCreatedTimestamp = null;
Integer limit = 50;
String before = null;
String after = null;
ListTransactions200Response result = apiInstance.listTransactions(
requestId, coboIds, transactionIds, transactionHashes, types, statuses, walletIds, chainIds,
tokenIds, assetIds, vaultId, projectId, minCreatedTimestamp, maxCreatedTimestamp, limit, before, after);
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling WalletsApi#createAddress");
System.err.println("Status code: " + e.getCode());
System.err.println("Reason: " + e.getResponseBody());
System.err.println("Response headers: " + e.getResponseHeaders());
e.printStackTrace();
}
}
}
```
### Withdraw tokens
Now that you have tokens in your wallet, let's walk through the withdrawal process. Before making your first withdrawal, there are two important things to understand:
1. **The withdrawal process**: A withdrawal involves multiple steps including initiation, double confirmation, risk control checks, and transaction signing. For a detailed overview of each step, see [Transfer from MPC Wallets (Organization-Controlled Wallets)](https://manuals.cobo.com/en/portal/transfers/from-mpc-wallets#withdrawal-process).
2. **Callback endpoint setup**: For enhanced security, you should set up a callback endpoint to double confirm withdrawal requests. When you initiate a withdrawal via the WaaS 2.0 API, this endpoint will receive the transaction details and must confirm them before the transaction proceeds. To set this up, follow our guide on [webhooks and callbacks](/v2/guides/webhooks-callbacks/introduction).
#### Initiate a withdrawal
Once you understand these concepts, you can initiate a withdrawal by calling the [Transfer token](/v2/api-references/transactions/transfer-token) operation. Set the properties in the request body as follows:
* `request_id`: Your request ID.
* `source.source_type`: `Org-Controlled`.
* `source.wallet_id`: The ID of the wallet you have just created.
* `token_id`: The ID of the token you want to withdraw.
* `destination.destination_type`: `Address`.
* `destination.account_output`: The receiving address and memo (if applicable), and the amount you want to withdraw.
* `category_names`: The custom category for you to identify your transactions.
* `description`: The description of the transfer.
```py theme={null}
import json
import uuid
import cobo_waas2
from cobo_waas2 import (
CreateAddressRequest,
AddressEncoding,
TransferParams,
TransferSource,
MpcTransferSource,
WalletSubtype,
TransferDestination, AddressTransferDestination, TransferDestinationType, AddressTransferDestinationAccountOutput,
)
configuration = cobo_waas2.Configuration(
# Replace `` with your API secret
api_private_key="",
# 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
transaction_api_instance = cobo_waas2.TransactionsApi(api_client)
try:
# Withdraw Bitcoin testnet3(XTN) tokens from the wallet
api_response = transaction_api_instance.create_transfer_transaction(
transfer_params=TransferParams(
request_id=str(uuid.uuid4()),
source=TransferSource(
actual_instance=MpcTransferSource
(
source_type=WalletSubtype.ORG_CONTROLLED,
wallet_id="",
)
),
token_id="XTN",
destination=TransferDestination(
actual_instance=AddressTransferDestination(
destination_type=TransferDestinationType.ADDRESS,
account_output=AddressTransferDestinationAccountOutput(
address="",
amount=""
)
)
),
category_names=[""],
description="",
)
)
print("The response of TransactionsApi->create_transfer_transaction:")
print(json.dumps(api_response.to_dict(), indent=2))
except Exception as e:
print("Exception when calling TransactionsApi->create_transfer_transaction, %s\n", e)
```
```java theme={null}
import com.cobo.waas2.ApiClient;
import com.cobo.waas2.ApiException;
import com.cobo.waas2.Configuration;
import com.cobo.waas2.Env;
import com.cobo.waas2.api.TransactionsApi;
import com.cobo.waas2.model.*;
import java.util.ArrayList;
import java.util.List;
import java.util.UUID;
public class TransferExample {
public static void main(String[] args) {
ApiClient defaultClient = Configuration.getDefaultApiClient();
// Use the development environment
defaultClient.setEnv(Env.DEV);
// Replace `` with your API secret
defaultClient.setPrivKey("");
TransactionsApi apiInstance = new TransactionsApi();
try {
UUID walletId = UUID.fromString("");
TransferParams params = new TransferParams();
params.setRequestId("Demo" + UUID.randomUUID());
MpcTransferSource transferSource = new MpcTransferSource().sourceType(WalletSubtype.ORG_CONTROLLED).walletId(walletId);
params.setSource(new TransferSource(transferSource));
params.setTokenId("XTN");
AddressTransferDestination addressTransferDestination = new AddressTransferDestination()
.destinationType(TransferDestinationType.ADDRESS)
.accountOutput(new AddressTransferDestinationAccountOutput()
.address("")
.amount(""));
params.setDestination(new TransferDestination(addressTransferDestination));
List categoryNames = new ArrayList<>();
categoryNames.add("");
params.categoryNames(categoryNames).description("");
CreateTransferTransaction201Response result = apiInstance.createTransferTransaction(params);
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling TransactionsApi#createTransferTransaction");
System.err.println("Status code: " + e.getCode());
System.err.println("Reason: " + e.getResponseBody());
System.err.println("Response headers: " + e.getResponseHeaders());
e.printStackTrace();
}
}
}
```
The response of the withdrawal request is as follows. Record the transaction ID as you will use it in the following steps.
```json theme={null}
{
"request_id": "",
"transaction_id": "",
"status": "Submitted"
}
```
#### Confirm withdrawal
After initiating a withdrawal, if you have configured a callback endpoint, the endpoint will receive a message containing the transaction details. Verify that the transaction matches your expectations, then approve it by responding with a success status code (200 or 201) and a response body containing 'ok'. For more information about handling callback messages, please refer to [
Implement handling logic](/v2/guides/webhooks-callbacks/set-up-endpoint#implement-handling-logic).
#### Sign the transaction
After the withdrawal is confirmed, it will be sent to the corresponding signers based on your signing mode and signer types. The transaction will remain pending until it receives the necessary signature.
* For mobile signers, please notify them to open the Cobo Guard app and sign the transaction.
* For server signers, you can check if a signer is online through Cobo Portal:
1. Log in to [Cobo Portal](https://portal.cobo.com/login).
2. Click 
> **MPC Wallets**.
3. Select your vault and then click the **Key Share Management** icon 
on the upper right hand corner.
4. In the **Key Share Management** page, locate your server signer, and check the status indicator:
* 🟢 Green dot: The signer is online and ready to sign transactions
* No dot: The signer is offline and cannot sign transactions.
#### Monitor the withdrawal status
In addition to webhook events, you can also call the [Get transaction information](/v2/api-references/transactions/get-transaction-information) operation to query the status of the transaction. Set the path parameter `transaction_id` to the transaction ID returned in the response of the previous withdrawal request.
```py theme={null}
import json
import uuid
import cobo_waas2
from cobo_waas2 import (
CreateAddressRequest,
AddressEncoding,
TransferParams,
TransferSource,
MpcTransferSource,
WalletSubtype,
TransferDestination, AddressTransferDestination, TransferDestinationType, AddressTransferDestinationAccountOutput,
)
configuration = cobo_waas2.Configuration(
# Replace `` with your API secret.
api_private_key="",
# 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
transaction_api_instance = cobo_waas2.TransactionsApi(api_client)
try:
# Get transaction by ID
api_response = transaction_api_instance.get_transaction_by_id(
transaction_id=""
)
print("The response of TransactionsApi->get_transaction_by_id:")
print(json.dumps(api_response.to_dict(), indent=2))
except Exception as e:
print("Exception when calling TransactionsApi->get_transaction_by_id, %s\n", e)
```
```java theme={null}
import com.cobo.waas2.ApiClient;
import com.cobo.waas2.ApiException;
import com.cobo.waas2.Configuration;
import com.cobo.waas2.Env;
import com.cobo.waas2.api.TransactionsApi;
import com.cobo.waas2.model.TransactionDetail;
import java.util.UUID;
public class GetTransactionExample {
public static void main(String[] args) {
ApiClient defaultClient = Configuration.getDefaultApiClient();
// Use the development environment
defaultClient.setEnv(Env.DEV);
// Replace `` with your API secret
defaultClient.setPrivKey("");
TransactionsApi apiInstance = new TransactionsApi();
try {
UUID transactionId = UUID.fromString("");
TransactionDetail result = apiInstance.getTransactionById(transactionId);
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling TransactionsApi#getTransactionById");
System.err.println("Status code: " + e.getCode());
System.err.println("Reason: " + e.getResponseBody());
System.err.println("Response headers: " + e.getResponseHeaders());
e.printStackTrace();
}
}
}
```
## 3. Query wallet balances
After successfully withdrawing tokens from your wallet, you can call [List token balances by wallet](/v2/api-references/wallets/list-token-balances-by-wallet) to query the wallet balances. Specify the path and query parameters as follows:
* `wallet_id`: The ID of the wallet you have just created.
* `token_ids`: You can leave it empty to query the balances of all tokens, or set it to the specific token you want to query.
```py theme={null}
import json
import cobo_waas2
from cobo_waas2 import (
WalletType,
WalletSubtype,
)
configuration = cobo_waas2.Configuration(
# Replace `` with your API secret.
api_private_key="",
# 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
wallet_api_instance = cobo_waas2.WalletsApi(api_client)
try:
# List token balances
api_response = wallet_api_instance.list_token_balances_for_wallet(
wallet_id="",
)
print(f"The response of WalletsApi->list_token_balances_for_wallet:")
print(json.dumps(api_response.to_dict(), indent=2))
except Exception as e:
print("Exception when calling WalletsApi->list_token_balances_for_wallet, %s\n", e)
```
```java theme={null}
import com.cobo.waas2.ApiClient;
import com.cobo.waas2.ApiException;
import com.cobo.waas2.Configuration;
import com.cobo.waas2.Env;
import com.cobo.waas2.api.WalletsApi;
import com.cobo.waas2.model.ListTokenBalancesForAddress200Response;
import java.util.UUID;
public class ListTokenBalancesExample {
public static void main(String[] args) {
ApiClient defaultClient = Configuration.getDefaultApiClient();
// Use the development environment
defaultClient.setEnv(Env.DEV);
// Replace `` with your API secret
defaultClient.setPrivKey("");
WalletsApi apiInstance = new WalletsApi();
try {
UUID wallet_id = UUID.fromString("");
String tokenIds = null;
Integer limit = 50;
String before = null;
String after = null;
ListTokenBalancesForAddress200Response result = apiInstance.listTokenBalancesForWallet(wallet_id, tokenIds, limit, before, after);
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling WalletsApi#listTokenBalancesForWallet");
System.err.println("Status code: " + e.getCode());
System.err.println("Reason: " + e.getResponseBody());
System.err.println("Response headers: " + e.getResponseHeaders());
e.printStackTrace();
}
}
}
```