Z Zise Developers
/
简体中文
Account Center › API Reference › Merchant Account

Request a prepaid deposit address (reused by asset × network)

POST /v1/merchant/deposit-addresses scope: merchant:write
Merchant account Requires x-idempotency-key

If an address already exists for the merchant and network, returns it directly; a second address is not allocated.

network requires a case-sensitive machine-readable code. Valid values come from networks[].network in GET /v1/assets, the sole authoritative catalog. ⚠ The code for BSC is BSC, not BEP20; BEP20 appears only in the display name BNB Smart Chain (BEP20). An earlier version of this page incorrectly said BEP20, which always caused rejection. Unrecognized asset × network combinations are rejected without automatically choosing another network. Automatic selection could send your prepayment onto a chain you never chose.

⚠ service_unavailable means not ready yet, not failure: the upstream is creating the address. Retry after a few seconds according to retry_after. It is 400, not 503; do not handle it as a 5xx. Treating it as failure and switching chains merely creates an unnecessary additional address.

On-chain receipt is posted automatically using the custodian-confirmed amount, with no manual amount entry. Check the result through GET /v1/merchant/balances.

Prerequisites

  • The asset × network combination exists in our channel configuration and is enabled.
FieldTypeRequiredDescription
x-idempotency-key string Required UUID v4

Request Body

FieldTypeRequiredDescription
asset string Required Asset code, case-insensitive; the server converts it to uppercase.
network string Required Network short code, case-sensitive and matched exactly: TRC20, not TRON (TRC20) or trc20.

Response

201Allocated, or returns the existing address; both return 201.
{
  "asset": "USDT",
  "network": "TRC20",
  "address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "memo": ""
}
400invalid_request: body is not JSON, or asset/network missing. asset_not_allowed: the asset × network combination does not exist or is disabled. service_unavailable: the upstream is still creating the address; retry according to retry_after in seconds.
409idempotency_key_reused · idempotency_in_progress
Request 
curl -X POST 'https://api.zinfra.vip/v1/merchant/deposit-addresses' \
  -H 'x-auth-token: Bearer $TOKEN' \
  -H 'x-idempotency-key: $IDEMPOTENCY_KEY' \
  -H 'content-type: application/json' \
  -d '{
    "asset": "USDT",
    "network": "TRC20"
  }'
const res = await fetch("https://api.zinfra.vip/v1/merchant/deposit-addresses", {
  method: "POST",
  headers: {
    "x-auth-token": "Bearer $TOKEN",
    "x-idempotency-key": "$IDEMPOTENCY_KEY",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    "asset": "USDT",
    "network": "TRC20"
  }),
});
// Keep monetary amounts as strings, never numbers.
const data = await res.json();
import requests

res = requests.post(
    "https://api.zinfra.vip/v1/merchant/deposit-addresses",
    headers={
        "x-auth-token": "Bearer $TOKEN",
        "x-idempotency-key": "$IDEMPOTENCY_KEY",
        "content-type": "application/json",
    },
    json={
      "asset": "USDT",
      "network": "TRC20"
    },
)
# Use Decimal(str(...)) for amounts, not float.
data = res.json()
req, _ := http.NewRequest("POST", "https://api.zinfra.vip/v1/merchant/deposit-addresses",
    strings.NewReader(`{
  "asset": "USDT",
  "network": "TRC20"
}`))
req.Header.Set("x-auth-token", "Bearer $TOKEN")
req.Header.Set("x-idempotency-key", "$IDEMPOTENCY_KEY")
req.Header.Set("content-type", "application/json")
res, err := http.DefaultClient.Do(req)
// Decode amount fields as string, not float64.
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.zinfra.vip/v1/merchant/deposit-addresses"))
    .header("x-auth-token", "Bearer $TOKEN")
    .header("x-idempotency-key", "$IDEMPOTENCY_KEY")
    .header("content-type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("""
{
  "asset": "USDT",
  "network": "TRC20"
}
"""))
    .build();
// Use String / BigDecimal for amounts, not double.
$ch = curl_init('https://api.zinfra.vip/v1/merchant/deposit-addresses');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'x-auth-token: Bearer $TOKEN',
    'x-idempotency-key: $IDEMPOTENCY_KEY',
    'content-type: application/json',
  ],
  CURLOPT_POSTFIELDS => <<<'JSON'
{
  "asset": "USDT",
  "network": "TRC20"
}
JSON,
]);
$res = curl_exec($ch);
// Use bcmath / strings for amounts, not floatval.
201 
{
  "asset": "USDT",
  "network": "TRC20",
  "address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "memo": ""
}