Create Deposit Address

HTTP Method: POST
Endpoint URL: /deposit-addresses/create
Description: Generates persistent deposit wallet addresses for a merchant.
Security: Requires both API-KEY and X-HMAC headers.

Request Headers

• Content-Type: application/json
• API-KEY: your_account_api_key
• X-HMAC: your_hmac_signature (calculated from all request body fields)

Request Body (JSON)

{
  "assetNetwork": "tron",
  "assetShort": "USDT",
  "number": 5
}

Field Descriptions

• assetNetwork — (required) Blockchain network (e.g., tron, ethereum, solana). Automatically converted to lowercase
• assetShort — (required) Asset ticker symbol (e.g., USDT, USDC). Automatically converted to uppercase
• number — Number of addresses to generate (1–100). Required when clientId is not provided. Ignored when clientId is provided (defaults to 1)
• clientId — Client identifier for sticky address binding. When provided, the system returns exactly 1 address bound to this client. See Sticky Address Behavior below

Example cURL

Sticky address (with clientId)

curl https://api.alppay.io/v2/deposit-addresses/create \
  -X POST \
  -H "Content-Type: application/json" \
  -H "API-KEY: ak_live_1234567890abcdef" \
  -H "X-HMAC: your_calculated_signature" \
  -d '{
    "assetNetwork": "ton",
    "assetShort": "TON",
    "clientId": "AA-BB-CC"
  }'

Batch generation (without clientId)

curl https://api.alppay.io/v2/deposit-addresses/create \
  -X POST \
  -H "Content-Type: application/json" \
  -H "API-KEY: ak_live_1234567890abcdef" \
  -H "X-HMAC: your_calculated_signature" \
  -d '{
    "assetNetwork": "tron",
    "assetShort": "USDT",
    "number": 5
  }'

Successful Response (200 OK)

Example: TON network with clientId

{
  "addresses": [
    {
      "symbol": "TON",
      "address": "UQAQy6n7u0BpyXVy2BLpVt2UHxRXSkkaV8-ZdKKaFnOXWOav",
      "dest_tag": "AA-BB-CC"
    }
  ],
  "success": true
}

Note: For TON network, dest_tag is always returned. When clientId is provided, dest_tag equals the clientId value.

Example: TRON network

{
  "addresses": [
    {
      "symbol": "USDT",
      "address": "TXic41xPQPrqRNoJyt191eKJ6E8sWD6uxF"
    }
  ],
  "success": true
}

Response Field Descriptions

• success — true when addresses were generated successfully
• addresses — Array of generated wallet address objects:
  • symbol — Asset ticker symbol (e.g., USDT)
  • address — The generated cryptocurrency wallet address
  • dest_tag — Destination tag/memo. Returned only for networks that require it (e.g., TON), otherwise null. If clientId is provided in the request, the dest_tag will be equal to the clientId value

Sticky Address Behavior with clientId

When clientId is provided, the endpoint implements idempotent address assignment:

1. The system searches for an existing wallet address bound to the combination of merchant + assetNetwork + clientId
2. If found — returns the existing address immediately (no new address is generated)
3. If not found — generates exactly 1 new address and binds it to the clientId

This means the same client always receives the same deposit address for a given asset and network, making it ideal for persistent wallet assignment.

Note: The number field is ignored when clientId is provided — exactly 1 address is always returned.

Scope of clientId

The clientId is scoped to:

• Merchant account (determined by your API key)
• Network (assetNetwork)

The same clientId will receive the same address for different assets on the same network, but different addresses for different networks:

clientId="user-123" + USDT + tron     = Address X
clientId="user-123" + USDC + tron     = Address X  (same network = same address)
clientId="user-123" + USDT + ethereum = Address Y  (different network = different address)

Use Cases

• Batch address pre-generation — Generate up to 100 deposit addresses at once (without clientId), useful for pre-allocating addresses before customers arrive
• Persistent customer wallets — Assign a permanent deposit address to each customer using clientId, so customers can reuse the same address for all future deposits

Error Responses

400 Bad Request

Returned when request validation fails:

• "assetNetwork is required" — missing assetNetwork field
• "assetShort is required" — missing assetShort field
• "number must be between 1 and 100" — invalid number of addresses (when clientId is not provided)

401 Unauthorized

Invalid or missing API-KEY header.

403 Forbidden

Invalid HMAC signature.

500 Internal Server Error

Server-side error occurred (e.g., wallet generation service unavailable).