Create Organizational Wallets

Once you have a Wallet Set, you can derive individual wallets for any of Planbok's supported blockchains. This guide covers the process for both Trustless and Standard MPC security models.

How Wallet Derivation Works

When you "create" a wallet in Planbok, you are mathematically deriving a unique address from your organization's master key shards.

• HD Path Construction: m/44'/coin_type'/wallet_set_index'/0/address_index
• Wallet Sets: Each set provides a unique wallet_set_index.
• Address Index: Every time you call the create endpoint for a specific Wallet Set, the system increments the address_index for those new wallets.

[!NOTE] You can derive wallets for multiple blockchains (e.g., Ethereum, Solana, and Bitcoin) simultaneously for a single user/reference ID. They will all share the same address_index across their respective coin types.

Quickstart: Creating Wallets

1. Standard MPC Flow

In Standard MPC, the nodes use your registered organization secret to perform the derivation. You only need your API key.

Endpoint: POST /v2/wallets

Request Body:

Code
{
  "idempotencyKey": "<unique_uuid_v4>",
  "walletSetId": "<your_wallet_set_id>",
  "blockchains": ["ETH", "SOL", "NEAR"],
  "count": 1,
  "metadata": [
    {
      "name": "Treasury Wallet",
      "refId": "dept_finance_01"
    }
  ]
}

2. Trustless MPC Flow

In Trustless MPC, you must provide your encryptedOrganizationSecret with the sign context to authorize the derivation math.

Step 1: Generate the Encrypted Secret

Code
node generate-encrypted-organization-secret.js sign

Step 2: Create the Wallet Endpoint: POST /v2/wallets

Request Body:

Code
{
  "idempotencyKey": "<unique_uuid_v4>",
  "walletSetId": "<your_wallet_set_id>",
  "blockchains": ["ETH", "POLYGON"],
  "count": 1,
  "metadata": [
    {
      "name": "User 123 Wallets",
      "refId": "user_123"
    }
  ],
  "encryptedOrganizationSecret": "BASE64_ENCRYPTED_DATA_HERE"
}

Key Parameters Explained

Next Steps

Now that your wallets are created, you can:

• Check Balances: Retrieve real-time asset data.
• Perform Transfers: Move assets using MPC signing.
• Export Keys: If using Trustless MPC, only the organization owner can export the private key for full portability.