Provisioning Customer Wallets

Once a customer has set up their PIN, they can begin creating wallets for any supported blockchain. Unlike Organizational wallets, customer wallet creation must be explicitly verified by the user's PIN to authorize the key shard generation.

Prerequisites

Before a customer can provision wallets, they must have completed:

1. PIN Setup: Established their primary security shard.
2. Recovery Setup: Configured a recovery method. Wallet creation will fail or be blocked if the hasRecovery flag is false.

The Provisioning Flow

Provisioning follows the standard Challenge-Response pattern. Even though the user has a PIN, the system requires them to "unlock" their shard once more to derive a new set of addresses.

1. Request a Provisioning Challenge

Initiate the creation of one or more wallets for the customer.

Endpoint: POST /v2/customers/{id}/wallet/create
Headers:

• PLANBOK-X-API-KEY: <your_api_key>

Request Body:

Code
{
  "blockchains": ["ETH", "SOL", "NEAR", "BTC"],
  "redirectUrl": "https://yourapp.com/dashboard/wallets/created",
  "accountType": "eoa"
}

• blockchains: An array of chains you want to enable for this user.
• accountType: Currently only eoa (Externally Owned Account) is supported.

The Response

Planbok returns a challenge that requires PIN verification:

Code
{
  "data": {
    "challengeId": "69a5368e969f8c8adc76af4e",
    "redirectUrl": "https://gateway.planbok.io/pin/verify?...",
    "status": "pending"
  }
}

2. User PIN Verification

Redirect the user to the redirectUrl.

1. Verification Interface: The user is asked to enter their PIN to "Provision New Wallets".
2. MPC Derivation: The Gateway uses the user's unlocked shard to trigger the Distributed Key Generation (DKG) for the selected chains.
3. Completion: The user is redirected back to your redirectUrl.

Once the challenge is successful, you can retrieve the customer's new wallet addresses. There are two ways to do this:

Option A: From the Challenge Result (Recommended)

The fastest way is to fetch the specific challenge. Planbok stores the derived wallets directly in the challenge's result field upon successful completion.

[!IMPORTANT] Challenges have a short lifespan (15 minutes). Your application must verify challenge status, retrieve the required data (like wallet addresses) and store it for your own use immediately after completion. Once a challenge is pruned or expires, its result data will no longer be accessible via this endpoint.

Endpoint: GET /v2/customers/{id}/challenges/{challengeId}

Response Example:

Code
{
  "data": {
    "status": "verified",
    "result": {
      "success": true,
      "wallets": [
        {
          "id": "69a53d10969f8c8adc76af6a",
          "blockchain": "ETH-SEPOLIA",
          "address": "0x123..."
        },
        {
          "id": "69a53d10969f8c8adc76af6b",
          "blockchain": "SOL-TESTNET",
          "address": "GvH..."
        }
      ]
    }
  }
}

Option B: Listing All Customer Wallets

You can also list all wallets associated with the customer ID.

Endpoint: GET /v2/wallets?customerIds={id}

Option C: Webhooks (Asynchronous)

You can receive real-time notifications when new wallets are successfully derived via webhooks.

Relevant Event:

• wallet.created: Sent immediately after the Gateway challenge is resolved and the MPC derivation is finished.

[!TIP] Webhooks are the most reliable way to sync Planbok state with your own database.

Response Example:

Code
{
  "data": [
    {
      "blockchain": "ETH-SEPOLIA",
      "address": "0x123...",
      "publicKey": "0xabc...",
      "custodyType": "customer"
    },
    {
      "blockchain": "SOL-TESTNET",
      "address": "GvH...",
      "custodyType": "customer"
    }
  ]
}

[!NOTE] All wallets created for a single customer share the same underlying root shard, derived using the standard BIP-44 account index defined by their customer profile.

Next Steps

With wallets provisioned, your customer can now Authorize Transactions.