如何在 RippleApi payment JSON 中使用 Destination tag

2026-10-24支付老李

结论

在旧版 RippleAPI 的 payment 对象中，直接把 tag 添加到 destination 下。它与 address、amount 同级，不能放在 amount 中，也不能拼接到地址里。

const payment = {
  source: {
    address: ADDRESS_1,
    maxAmount: {
      value: amount,
      currency: currency
    }
  },
  destination: {
    address: ADDRESS_2,
    tag: DESTINATION_TAG,
    amount: {
      value: amount,
      currency: currency
    }
  }
}

DESTINATION_TAG 通常是一个无符号 32 位整数，例如：

const DESTINATION_TAG = 123456;

为什么这样设置

Destination Tag 用来区分同一个 XRP Ledger 地址下的账户、用户或充值记录。交易提交后，destination.tag 对应 XRP Ledger 交易中的 DestinationTag 字段。

Destination Tag 既不是地址的一部分，也不是金额属性。下面两种写法都不正确：

address: `${ADDRESS_2}:${DESTINATION_TAG}`

amount: {
  value: amount,
  currency: currency,
  tag: DESTINATION_TAG
}

完整示例

const payment = {
  source: {
    address: ADDRESS_1,
    maxAmount: {
      value: amount,
      currency: currency
    }
  },
  destination: {
    address: ADDRESS_2,
    tag: 123456,
    amount: {
      value: amount,
      currency: currency
    }
  }
};

const prepared = await api.preparePayment(ADDRESS_1, payment);

如果标签来自字符串输入，应先严格校验，再转换成数字：

const parsedTag = Number(destinationTag);

if (
  !Number.isInteger(parsedTag) ||
  parsedTag < 0 ||
  parsedTag > 0xFFFFFFFF
) {
  throw new Error('Invalid destination tag');
}

payment.destination.tag = parsedTag;

注意事项

Destination Tag 的有效范围是 0 到 4294967295。
不能使用负数、小数或超出范围的数值。
部分交易所和托管钱包强制要求填写 Destination Tag。标签遗漏或填写错误时，对方可能无法自动识别对应的入账账户。
不需要标签时，省略 tag 字段即可。不要随意填写 0，因为 0 本身也是有效标签。
source.tag 和 destination.tag 的含义不同。如果发送方需要 Source Tag，应在 source 下单独添加 tag。
以上写法要求当前使用的 ripple-lib/RippleAPI 版本支持 payment 对象中的 destination.tag。如果旧版本在参数校验阶段拒绝该字段，只修改 JSON 不能解决问题，需要升级到兼容版本或改为构造底层交易。
如果使用包含标签信息的 X-address，应按照对应库版本的地址规则处理，避免在地址和 destination.tag 中重复指定标签。