注册商户

POST · /api/v1/wallet/address/batch-create

批量创建地址

一次为多个商户用户在同一公链上批量分配专属充值地址。单项失败不阻塞其他用户，响应按条目独立返回成功/失败。

单项失败不影响整批

每个 externalUserId 独立处理——其中一个失败（如已超出地址配额）， 其余成功的条目照常返回地址。请遍历 items 检查每条 success 字段， 不要只看顶层 code。
POST/api/v1/wallet/address/batch-create HMAC 幂等

与单次创建一样，同一应用 + 同一 chainCode + 同一 externalUserId 是幂等的——已有地址时 success=true 并返回原地址，不会重复生成。

请自行持久化地址

批量创建通常用于账户初始化场景。成功后请将 items[].address 里的链上地址持久化到你的数据库， 后续充值页直接读自家数据，不要每次都重新调用此接口。

Header 参数

X-Api-Key
string required
应用 apiKey。沙箱前缀 pk_test_，正式 pk_live_。
例： pk_test_4f9d8ab1c0e74...
X-Timestamp
integer (UNIX 毫秒) required
请求发起时刻的 UNIX 毫秒时间戳（13 位整数）。与服务端时差不能超过 ±300000ms（5 分钟）。
例： 1746450000000
X-Nonce
string required
本次请求的随机串，建议 UUID v4 或 16 字节 hex。同一 (apiKey, nonce) 在 10 分钟窗口内不可重复。
例： 8e3a1c2f7b6d4a90
X-Signature
string required
HMAC-SHA256 签名（小写 hex，64 字符）。算法：HMAC(secret, METHOD + "\n" + PATH + "\n" + ts + "\n" + nonce + "\n" + SHA256(body))。详见 鉴权章节。
例： 6e4a8c1f...（64 字符）

Body 参数

application/json
chainCode
string required
公链 code，必须是该应用已开通的公链。完整列表见 GET /api/v1/wallet/support/chains。
例： ETH
externalUserIds
string[] required
商户侧用户唯一标识数组，不能为空。数组内每个元素与单次创建的 externalUserId 语义相同；同应用 + 同 chainCode + 同 externalUserId 幂等，已有地址的用户返回原地址。
例： ["user_1024","user_1025"]

示例 

{
  "chainCode": "ETH",
  "externalUserIds": ["user_1024", "user_1025"]
}

请求示例

# 签名算法（stringToSign / 4 个 header）见 /docs/api/auth
API_KEY=pk_test_xxx
SECRET=sk_test_xxx
METHOD=POST
REQ_PATH=/api/v1/wallet/address/batch-create
BODY='{"chainCode":"ETH","externalUserIds":["user_1024","user_1025"]}'
TS=$(( $(date +%s) * 1000 ))
NONCE=$(uuidgen | tr -d '-' | tr '[:upper:]' '[:lower:]')
BODY_SHA=$(printf "%s" "$BODY" | openssl dgst -sha256 -hex | awk '{print $2}')
SIG=$(printf "%s\n%s\n%s\n%s\n%s" "$METHOD" "$REQ_PATH" "$TS" "$NONCE" "$BODY_SHA" \
  | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $2}')

curl -X POST "https://api.pqpa.com$REQ_PATH" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key:    $API_KEY" \
  -H "X-Timestamp:  $TS" \
  -H "X-Nonce:      $NONCE" \
  -H "X-Signature:  $SIG" \
  -d "$BODY"

响应

Response
200OK
{
  "code": 0,
  "data": {
    "total": 2,
    "successCount": 1,
    "failedCount": 1,
    "items": [
      {
        "externalUserId": "user_1024",
        "success": true,
        "address": {
          "id": 88001,
          "chainCode": "ETH",
          "address": "0xab12cd34ef56...",
          "memo": null,
          "addressType": "USER",
          "externalUserId": "user_1024",
          "status": "ACTIVE"
        }
      },
      {
        "externalUserId": "user_1025",
        "success": false,
        "errorCode": 1007003005,
        "errorMessage": "应用未开通该链：ETH（请先在管理后台启用对应代币）"
      }
    ]
  },
  "msg": ""
}

data 字段说明

total
integer required
本次请求的用户总数，等于 externalUserIds 数组长度。
successCount
integer required
成功创建（或幂等命中）的地址数。
failedCount
integer required
失败的用户数。失败不影响其他用户。
items
object[] required
逐条结果数组，顺序与入参 externalUserIds 一致。
items[].externalUserId
string required
该条目对应的商户侧用户标识。
items[].success
boolean required
true = 地址已就绪；false = 创建失败。
items[].address
object optional
成功时返回完整的 AddressRespVO 对象（含 id / chainCode / address / memo / addressType / externalUserId / status）；失败时不返回此字段。
items[].errorCode
integer optional
失败时的业务错误码。
items[].errorMessage
string optional
失败时的错误描述。

下一步