ADDRESSES

充值地址 (Addresses)

为商户的每个终端用户生成专属链上收款地址。本章先讲清楚地址模型，再进具体接口。

先读这里再翻接口

地址是充值流程的入口对象——所有充值记录、回调、对账都关联到具体地址。花两分钟理解下面的概念，能省掉接入时 80% 的来回返工。

1. 地址模型

派付里的"充值地址"由以下映射关系确定：

(chainCode, externalUserId) → 地址（幂等）

意思是：当你的某个终端用户（externalUserId）需要在某条链（chainCode）上收款时，你向派付申请一个地址，派付返回一个稳定的 id 和对应的链上字符串。之后这个用户每次在同一条链上充值，都应该复用同一个地址，不要每次重建。

全部由派付的钱包基础设施生成与托管——你拿到的是已经可以接收的地址，不需要在自己服务里管私钥。回调到账由派付主动 push 给你，详见充值回调 payload。

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

在 ETH / BSC / POLYGON 等 EVM 链上，同一私钥派生的地址是相同的。因此传 chainCode=ETH 创建时，派付会给该应用所有已开通的 EVM 系链同步创建地址，避免用户在 BSC 上充值找不到对应地址。用查询用户地址可一次拿到该用户所有链的地址。

externalUserId

商户侧的用户唯一标识（直接传你的内部 user id 即可）。派付以此区分不同终端用户，同一 externalUserId 在同一公链上始终对应同一个地址（幂等）。

chainCode

公链的唯一标识符，如 ETH、BSC、TRON、SOL。创建地址时必须传，且该链必须在当前应用中已开通。完整支持列表见 GET /api/v1/wallet/support/chains。

id（地址主键）

派付侧给每条地址记录分配的数字主键。后续查询、引用请使用 id，不要用链上地址字符串当主键——不同链大小写规则不同，容易出错。

幂等键：(应用, chainCode, externalUserId)

这三个维度共同确定唯一性。对同一组合重复调用创建接口，派付直接返回首次创建的地址，不会重复生成。建议你在自己的数据库里也维护这个映射，存在就直接复用。

地址资源提供创建、批量创建、按用户查询和校验共 4 个接口：

为商户用户在指定公链上分配专属收款地址，同一用户同一链幂等。

一次为多个用户批量分配地址，单项失败不影响整批，按条目返回结果。

按 externalUserId 拉取该用户在所有公链上的地址列表，返回扁平数组。

校验目标地址格式并返回标准化形式，提币前调用可防止用户输错。

创建：调 POST /api/v1/wallet/address/create，派付返回 id + 链上地址字符串。此时地址立刻可收款，不需要任何"激活"步骤。
使用：把链上地址字符串展示给终端用户。用户充值后派付侦测到链上转账，达到所需确认数后入账，推 RECHARGE_CREDITED 回调。
查询：用 GET /api/v1/wallet/address/list-by-user 拉取某用户在所有链上的地址，用于对账或客服查单。
归集：达到阈值后派付自动从充值地址归集到归集账户，对你完全透明，对账数据不变。

请持久化地址，不要重复申请

用户首次需要充值时调一次创建接口，把返回的地址存到你自己的数据库，之后直接读自家数据。频繁为同一 (externalUserId, chainCode) 创建地址不会生成新地址（幂等），但会增加不必要的 API 调用和对账复杂度。