Skip to main content
POST
/
v1
/
wallets
Create Wallet
curl --request POST \
  --url https://api.hedgepayments.com/v1/v1/wallets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "userId": "<string>",
  "currency": "<string>",
  "label": "<string>",
  "initialBalance": 123
}
'
{
  "id": "<string>",
  "userId": "<string>",
  "currency": "<string>",
  "balance": {
    "available": 123,
    "pending": 123,
    "reserved": 123,
    "total": 123
  },
  "status": "<string>",
  "label": "<string>",
  "limits": {
    "daily": 123,
    "monthly": 123,
    "transaction": 123
  },
  "createdAt": "<string>",
  "updatedAt": "<string>"
}

​
Overview

Create a new digital wallet for storing and managing user funds. Each wallet is tied to a specific user and currency, supporting both fiat currencies (USD, EUR, GBP) and cryptocurrencies (BTC, ETH, SOL, USDC). Use Cases:
  • Onboarding new users with their first wallet
  • Creating multi-currency wallets for international users
  • Setting up merchant settlement wallets
  • Establishing escrow or custody wallets

​
Authentication

curl -X POST https://api.hedgepayments.com/v1/wallets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

​
Request Body

​
userId
string
required
The unique identifier of the user who will own this wallet. Must be a valid user ID from your system.Example: "user_1a2b3c4d5e"
​
currency
string
required
The currency code for this wallet. Supports ISO 4217 codes for fiat currencies and standard crypto ticker symbols.Supported Fiat: USD, EUR, GBP, CAD, AUD, JPY, CHF, CNY, INR, BRL, MXNSupported Crypto: BTC, ETH, SOL, USDC, USDT, MATIC, AVAX, NEARExample: "USD" or "USDC"
​
label
string
A human-readable label for the wallet to help users identify it. Maximum 50 characters.Examples:
  • "Primary Wallet"
  • "Savings Account"
  • "Business Operations"
​
initialBalance
number
Optional initial balance to credit to the wallet in the smallest currency unit (cents for USD, wei for ETH, etc.). Only available for sandbox environments or with special permissions.Example: 10000 (represents $100.00 for USD)

​
Request Examples

{
  "userId": "user_1a2b3c4d5e",
  "currency": "USD",
  "label": "Primary Wallet"
}

​
Response

​
id
string
Unique identifier for the wallet
​
userId
string
The user who owns this wallet
​
currency
string
The wallet’s currency code
​
balance
object
Current balance information
​
status
string
Current wallet status: pending_verification, active, suspended, frozen, or closed
​
label
string
Human-readable wallet label
​
limits
object
Transaction limits for this wallet
​
createdAt
string
ISO 8601 timestamp of wallet creation
​
updatedAt
string
ISO 8601 timestamp of last update

​
Response Examples

{
  "id": "wallet_9x8y7z6a5b",
  "userId": "user_1a2b3c4d5e",
  "currency": "USD",
  "balance": {
    "available": 0,
    "pending": 0,
    "reserved": 0,
    "total": 0,
    "currency": "USD"
  },
  "status": "active",
  "label": "Primary Wallet",
  "limits": {
    "daily": 1000000,
    "monthly": 5000000,
    "transaction": 100000
  },
  "createdAt": "2025-11-18T22:30:00Z",
  "updatedAt": "2025-11-18T22:30:00Z"
}

​
Code Examples

import { HedgePayments } from '@hedgepayments/sdk';

const hedge = new HedgePayments(process.env.HEDGE_API_KEY);

async function createUserWallet() {
  try {
    const wallet = await hedge.wallets.create({
      userId: 'user_1a2b3c4d5e',
      currency: 'USD',
      label: 'Primary Wallet'
    });

    console.log('Wallet created:', wallet.id);
    console.log('Current balance:', wallet.balance.available);

    return wallet;
  } catch (error) {
    if (error.code === 'WALLET_EXISTS') {
      console.log('User already has a USD wallet');
      // Retrieve existing wallet
      const existing = await hedge.wallets.list({
        userId: 'user_1a2b3c4d5e',
        currency: 'USD'
      });
      return existing.wallets[0];
    }
    throw error;
  }
}

​
Error Handling

Error CodeHTTP StatusDescriptionResolution
INVALID_CURRENCY400Unsupported currency codeUse a supported currency from the list
INVALID_USER_ID400User ID not foundVerify the user exists in your system
WALLET_EXISTS409User already has wallet in this currencyRetrieve the existing wallet instead
INVALID_API_KEY401Authentication failedCheck your API key is valid
RATE_LIMIT_EXCEEDED429Too many requestsImplement exponential backoff
INSUFFICIENT_PERMISSIONS403API key lacks permissionsUse a key with wallet creation permissions

​
Best Practices

​
1. One Wallet Per Currency Per User

Users should have only one wallet per currency. Always check for existing wallets before creating new ones: 
// Good: Check first
const existing = await hedge.wallets.list({ userId, currency: 'USD' });
const wallet = existing.wallets[0] || await hedge.wallets.create({ userId, currency: 'USD' });

// Bad: Always create
const wallet = await hedge.wallets.create({ userId, currency: 'USD' }); // May fail

​
2. Use Descriptive Labels

Help users identify their wallets with clear labels: 
// Good
{ label: 'Business Operations' }
{ label: 'Personal Savings' }
{ label: 'Crypto Holdings' }

// Bad
{ label: 'Wallet 1' }
{ label: 'Account' }

​
3. Handle Errors Gracefully

Always implement proper error handling: 
try {
  const wallet = await createWallet(userId, 'USD');
} catch (error) {
  if (error.code === 'WALLET_EXISTS') {
    // Use existing wallet
  } else if (error.code === 'INVALID_USER_ID') {
    // Create user first
  } else {
    // Log and notify
    logger.error('Wallet creation failed', { error, userId });
  }
}

​
4. Implement Idempotency

Use idempotency keys for safe retries: 
const wallet = await hedge.wallets.create({
  userId: 'user_123',
  currency: 'USD',
  idempotencyKey: `wallet-creation-${userId}-${Date.now()}`
});

​
Webhooks

When a wallet is created, the following webhook event is triggered: 
{
  "event": "wallet.created",
  "data": {
    "id": "wallet_9x8y7z6a5b",
    "userId": "user_1a2b3c4d5e",
    "currency": "USD",
    "status": "active",
    "createdAt": "2025-11-18T22:30:00Z"
  },
  "timestamp": "2025-11-18T22:30:00Z"
}
Learn more about webhooks →

​
Rate Limits

  • 100 requests per minute per API key
  • 1000 wallet creations per day per merchant

​
Support

Need help? Contact us: