Create Wallet

Create a new HD (Hierarchical Deterministic) wallet for a customer with BIP-39 mnemonic seed phrase.

Plan Limits

Plan	Max Customer Wallets
Starter	5
Professional	50
Business	Unlimited
Enterprise	Unlimited

This endpoint returns 403 WALLET_LIMIT_EXCEEDED when the plan cap is reached and 402 if the subscription is expired. Check your current usage with GET /api/v1/subscription/current.

Endpoint

POST /api/v1/wallet/customers

Authentication

Requires API key authentication via X-API-Key header.

Request Body

Field	Type	Required	Description
customer_id	string	Yes	Unique identifier for your customer
word_count	integer	No	Mnemonic word count: 12 or 24 (default: 12)

Example Request

JavaScript

const response = await fetch('https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/create', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    customer_id: 'user_12345',
    word_count: 12
  })
});

const wallet = await response.json();
console.log('Wallet ID:', wallet.wallet_id);
console.log('Mnemonic:', wallet.mnemonic);

Python

import requests

response = requests.post(
    'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/create',
    headers={
        'X-API-Key': 'your-api-key',
        'Content-Type': 'application/json'
    },
    json={
        'customer_id': 'user_12345',
        'word_count': 12
    }
)

wallet = response.json()
print(f"Wallet ID: {wallet['wallet_id']}")
print(f"Mnemonic: {wallet['mnemonic']}")

cURL

curl -X POST https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/create \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "user_12345",
    "word_count": 12
  }'

Response

Success Response (200 OK)

Field	Type	Description
customer_id	string	Customer identifier
wallet_id	integer	Wallet database ID
mnemonic	array	BIP-39 mnemonic phrase (array of words)
created_at	string	ISO 8601 timestamp

{
  "customer_id": "user_12345",
  "wallet_id": 42,
  "mnemonic": [
    "abandon", "ability", "able", "about", "above", "absent",
    "absorb", "abstract", "absurd", "abuse", "access", "accident"
  ],
  "created_at": "2026-01-03T04:00:00Z"
}

CAUTION

Critical Security Notice: The mnemonic is ONLY returned once during wallet creation. It is NEVER accessible again through any API endpoint. You must either:

• Save it securely in your database (encrypted)
• Display it to your user for backup
• Both

Loss of the mnemonic means permanent loss of access to all derived wallets.

Error Responses

402 Subscription Expired

{
  "error": "subscription expired — please renew your plan to continue"
}

403 Wallet Limit Reached

{
  "error": "Wallet address limit reached for your current plan. Please upgrade to add more customer wallets.",
  "code": "WALLET_LIMIT_EXCEEDED"
}

When you receive a 403 with code: "WALLET_LIMIT_EXCEEDED", check GET /api/v1/subscription/current to see your current usage and available upgrade options.

400 Bad Request

{
  "error": "invalid word count: must be 12 or 24"
}

409 Conflict

{
  "error": "customer user_12345 already has a wallet"
}

401 Unauthorized

{
  "error": "invalid API key"
}

500 Internal Server Error

{
  "error": "failed to create wallet: database error"
}

Best Practices

Wallet Management

• Create one wallet per customer - wallets are reusable across all blockchain networks
• Store the wallet_id in your database linked to the customer
• Securely handle the mnemonic - encrypt before storage or prompt user to back it up
• Use 24 words for enhanced security (256-bit entropy vs 128-bit)
• Never log or transmit mnemonics through insecure channels

Next Steps

After creating a wallet:

1. Derive addresses for specific blockchain networks
2. Enable deposit monitoring for webhook notifications
3. Display derived addresses to your users for deposits

Related Endpoints

• Get Seed Phrase - Retrieve mnemonic (requires authentication)
• Derive Address - Generate blockchain addresses
• List Addresses - View all derived addresses