创建 XRP 与 XLM 虚拟账户的完整指南

虚拟账户（Virtual Accounts，简称 VA）是区块链应用开发中管理用户资产的常见方式。尤其在 XRP（瑞波币）和 XLM（恒星币）这类需要标签或备注的区块链网络中，正确配置虚拟账户对于确保资金准确归属至关重要。本文将详细介绍如何利用 API 创建和管理基于 XRP 与 XLM 的虚拟账户，并解释其中的关键概念与注意事项。

理解虚拟账户与 XPUB 的关系

在 XRP 和 XLM 网络中，虚拟账户的核心依赖于一个主地址（称为 XPUB）来管理所有子账户。这个主地址不仅作为资金接收的公共地址，还充当生成虚拟账户的根密钥。

XPUB 的作用：XPUB 是一个公共地址，所有用户存款都发送至此地址。通过唯一的 destinationTag（XRP）或 message（XLM），系统能够区分资金归属的不同虚拟账户。
私钥与安全：与 XPUB 对应的私钥用于签署交易，必须严格保密。私钥泄露可能导致资产损失，因此务必使用安全的密钥管理方案。

👉 查看实时密钥管理工具

创建主 XRP 地址（XPUB）

生成主 XRP 地址是创建虚拟账户的第一步。该地址将作为所有后续虚拟账户的公共基础。

使用 API 生成地址

通过调用 GET /v3/xrp/account 端点，您可以生成主 XRP 地址和对应的私钥。

请求示例：

curl --request GET \
  --url https://api.tatum.io/v3/xrp/account \
  --header 'x-api-key: {YOUR_API_KEY}'

响应示例：

{
  "address": "rDWpnpN3KHUz49WZJpwNe2GQLHeSZ62B1d", // 作为 XPUB 使用
  "secret": "ssKPqjZ9VPg79rEsrHjydRLMM8xgG" // 用于签署交易的私钥
}

关键参数说明

address：生成的公共地址，即 XPUB。所有虚拟账户将关联到此地址。
secret：私钥，用于交易签名。务必安全存储，切勿泄露。

创建 XRP 虚拟账户

获得 XPUB 后，您可以创建多个虚拟账户，每个账户关联到同一个 XPUB，但通过不同的参数区分用户。

调用创建账户接口

使用 POST /v3/ledger/account 端点创建虚拟账户，并指定相关用户信息。

请求示例：

curl --request POST \
  --url https://api.tatum.io/v3/ledger/account \
  --header 'content-type: application/json' \
  --header 'x-api-key: {YOUR_API_KEY}' \
  --data '{
    "currency":"XRP",
    "xpub":"rDWpnpN3KHUz49WZJpwNe2GQLHeSZ62B1d",
    "customer":{
      "accountingCurrency":"USD",
      "customerCountry":"US",
      "externalId":"123654",
      "providerCountry":"US"
    },
    "compliant":false,
    "accountCode":"AC_1011_B",
    "accountingCurrency":"USD",
    "accountNumber":"123456"
  }'

响应示例：

{
  "currency": "XRP",
  "active": true,
  "balance": {
    "accountBalance": "0",
    "availableBalance": "0"
  },
  "frozen": false,
  "xpub": "rDWpnpN3KHUz49WZJpwNe2GQLHeSZ62B1d",
  "accountingCurrency": "USD",
  "id": "61afba85997b887f543fa7f0" // 虚拟账户 ID
}

客户信息与账户参数

customer 对象：包含用户详细信息，如国家、会计货币和外部标识符（externalId）。externalId 应与您数据库中的用户 ID 对应。
账户属性：每个虚拟账户仅支持一种货币，且必须绑定到客户实体。

生成存款地址与标签

在 XRP 和 XLM 网络中，存款地址实际上是共享的 XPUB，但通过唯一的 destinationTag（XRP）或 message（XLM）来区分不同用户的存款。

创建存款地址

调用 POST /v3/offchain/account/{Virtual_Account_ID}/address 端点为虚拟账户生成存款标签。

请求示例：

curl --request POST \
  --url 'https://api.tatum.io/v3/offchain/account/{Virtual_Account_ID}/address?index=1' \
  --header 'x-api-key: {YOUR_API_KEY}'

响应示例：

{
  "xpub": "rDWpnpN3KHUz49WZJpwNe2GQLHeSZ62B1d",
  "derivationKey": 1,
  "address": "rDWpnpN3KHUz49WZJpwNe2GQLHeSZ62B1d",
  "currency": "XRP",
  "destinationTag": 1
}

存款标签的重要性

资金归属：用户存款时必须提供正确的 destinationTag（XRP）或 message（XLM），否则资金无法被正确计入账户。
共享地址：所有虚拟账户共享同一个 XPUB 地址，避免了为每个地址冻结资产的高额成本。

常见问题与错误处理

为什么必须使用相同的 XPUB？

XRP 和 XLM 网络要求所有虚拟账户和存款地址基于同一个 XPUB。如果您尝试使用不同的 XPUB，将返回错误：

{
  "errorCode": "account.xpub.bnb",
  "message": "For BNB, XLM and XRP, only 1 xpub is allowed for API Key. For your ledger account, use already defined xpub and memo field for address differentiation."
}

这不是系统错误，而是预期行为，确保资金管理的一致性与经济性。

如何保证存款安全？

始终验证用户提供的存款标签是否正确。
使用内部系统映射标签与虚拟账户的关系，确保自动资金分配。

👉 获取进阶密钥管理方法

最佳实践与安全建议

密钥管理：切勿在代码或日志中暴露助记词或私钥。对于主网环境，使用专业的密钥管理系统（KMS）来处理签名操作。
标签验证：在用户界面明确提示用户输入正确的存款标签，并提供实时验证机制。
账户监控：实时监控虚拟账户余额和交易状态，及时处理异常存款（如缺少标签的转账）。
用户教育：通过指南和提示帮助用户理解存款标签的重要性，减少操作失误。

常见问题

Q1: 虚拟账户支持哪些区块链？
A: 虚拟账户功能适用于多种区块链，包括 XRP、XLM、BTC、ETH 等。但 XRP 和 XLM 因需要标签机制，配置上较为特殊。

Q2: 如果用户存款时忘记填写标签怎么办？
A: 资金仍会到达 XPUB 地址，但无法自动计入具体账户。您需要联系技术支持，通过手动流程根据交易哈希分配资金。

Q3: 一个虚拟账户可以持有多种货币吗？
A: 不可以。每个虚拟账户仅支持单一货币。如需多货币支持，应为用户创建多个分别对应不同货币的虚拟账户。

Q4: 虚拟账户需要支付网络费用吗？
A: 创建虚拟账户本身无需费用，但区块链交易（如存款、提现）需要支付对应的网络手续费（如 XRP 中的交易费）。

Q5: 如何查询虚拟账户的交易历史？
A: 通过调用 Tatum 的 API 端点获取账户交易列表，您可以按时间范围、交易类型过滤记录，并查看每笔交易的详细信息。

Q6: 虚拟账户与冷钱包有何区别？
A: 虚拟账户是托管式解决方案，资金存储在共享地址中，通过标签区分归属；而冷钱包是独立存储的离线钱包，资金完全由用户控制。