注册商户

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

创建充值地址

给商户用户分配链上专属充值地址。同一用户在同一公链上始终是同一地址；商户拿到后请<strong>自行持久化保存</strong>，不要在每次充值页加载时都重复调用。

请在你的系统里持久化地址

同一用户在同一公链上始终是同一地址。 请在该用户首次需要充值时调一次本接口， 把返回的 address（和 memo 链下的 memo）持久化到你自己的数据库， 后续直接读自家数据。
不要在每次"充值"页加载时都重复调用——商户侧本地缓存才是正确做法。
POST/api/v1/wallet/address/create HMAC 幂等

响应里 address 和 memo 字段的形态因公链类型而异：

  • HD 链（BTC / EVM 全家桶 / SOL 等）：每个用户拿到一个独立的链上地址，memo 恒为 null。 商户把 address 直接展示给用户即可。
  • Memo 链（XRP / XLM / EOS 等）：派付侧使用一个共享地址， memo 字段才是区分用户的关键。 商户必须同时引导用户填写 memo——只填地址不填 memo 会导致到账归错户。

EVM 系链一次创建、多链可收

传 chainCode=ETH 创建时，会给该应用所有已开通的同 namespace（EVM 系）链（BSC / POLYGON / …）一并创建同一私钥派生的地址，避免用户在 BSC 上充值丢失。 本响应只返回请求链（ETH）那一行；其它链上的地址用 查询用户地址 拉取。

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
externalUserId
string required
商户侧的用户唯一标识（建议直接传你的内部 user id）。同一应用 + 同一 chainCode + 同一 externalUserId 始终拿同一个地址（幂等）。
例： user_1024

示例 

{
  "chainCode": "ETH",
  "externalUserId": "user_1024"
}

请求示例

# 签名算法（stringToSign / 4 个 header）见 /docs/api/auth
API_KEY=pk_test_xxx
SECRET=sk_test_xxx
METHOD=POST
REQ_PATH=/api/v1/wallet/address/create
BODY='{"chainCode":"ETH","externalUserId":"user_1024"}'
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": {
    "id": 88001,
    "chainCode": "ETH",
    "address": "0xab12cd34ef56...",
    "memo": null,
    "addressType": "USER",
    "externalUserId": "user_1024",
    "status": "ACTIVE"
  },
  "msg": ""
}

data 字段说明

id
integer required
地址记录 id（系统内部主键，不是链上地址）。后续查询 / 引用都用这个。
chainCode
string required
所属公链 code。
address
string required
链上地址，原始大小写形式（EVM 走 EIP-55 校验和）。
memo
string? optional
Memo 链（XRP / XLM / EOS）下发的 memo/tag；非 memo 链恒为 null。
addressType
string required
地址类型，用户充值地址固定为 USER。
externalUserId
string required
回填请求传入的商户侧用户标识。
status
string required
地址状态，如 ACTIVE。

下一步