Skip to main content
POST
/
wallets
Create wallet (merchant or customer)
curl --request POST \
  --url https://api-staging.stablestack.com/api/wallets \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '
{
  "currency": "USDC",
  "description": "My wallet",
  "customer_id": "85b148ab-3f6b-4d55-917f-3c8de668a48e",
  "network": "erc20"
}
'
{
  "status": "success",
  "data": {
    "id": "49468947-4006-4b9a-bd96-f6b0d0210ad3",
    "asset_type": "STABLECOIN",
    "currency": "USDC",
    "balance": "0.00000000",
    "description": "my erc account",
    "status": "active",
    "created_at": "2025-05-01T21:04:31.928Z",
    "updated_at": "2025-05-01T21:04:31.928Z",
    "customer_id": "85b148ab-3f6b-4d55-917f-3c8de668a48e",
    "addresses": [
      {
        "id": "2381eeac-a592-4992-8bb9-4286634a0e94",
        "crypto_wallet_id": "49468947-4006-4b9a-bd96-f6b0d0210ad3",
        "address": "0xDt541923E23DcE32d1A346e96558dA89f87WD1aB",
        "network": "erc20",
        "created_at": "2025-05-01T21:04:32.179Z"
      }
    ]
  }
}
Creates a new wallet for either merchant or customer.

​
Key Features:

  • Supports both STABLECOIN (with network) and FIAT wallets
  • customer_id is optional (null for merchant wallets)
  • Automatic network validation based on currency type
  • Returns complete wallet details with addresses (for crypto)

​
Request Body:

Customer STABLECOIN Wallet: 
{
  "customer_id": "85b148ab-3f6b-4d55-917f-3c8de668a48e",
  "currency": "USDC",
  "network": "erc20",
  "description": "my USDC account"
}
Customer FIAT Wallet: 
{
  "customer_id": "85b148ab-3f6b-4d55-917f-3c8de668a48e",
  "currency": "CAD",
  "description": "my cad account"
}
Merchant STABLECOIN Wallet: 
{
  "currency": "USDC",
  "network": "polygon",
  "description": "merchant USDC account"
}
Merchant FIAT Wallet: 
{
  "currency": "CAD",
  "description": "merchant CAD account"
}

Headers

​
x-api-key
string
required

Body

application/json
​
currency
enum<string>
required

Currency code

Available options:
USDC,
ZAR
Example:

"USDC"

​
description
string
required

Optional description (Recommended)

Maximum string length: 255
Example:

"My wallet"

​
customer_id
string<uuid> | null

Required for customer wallets, omit for merchant wallets

Example:

"85b148ab-3f6b-4d55-917f-3c8de668a48e"

​
network
enum<string> | null

Required for STABLECOIN only

Available options:
erc20,
polygon
Example:

"erc20"

Response

Wallet created successfully

​
status
string
Example:

"success"

​
data
object