> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Travel Rule 合规

> 通过 meta_data 提供受益人与发起方信息 —— 字段规则、条件必填项与参考数据查询。

[Stablecoin Account API 发布方声明](/zh/stablecoin-account/v1.6/guide/stablecoin-account-api-publisher-disclaimer)

FATF Travel Rule 要求在特定情形下识别加密货币转账的交易对手。在 Stablecoin Account API 中，这些信息统一放在一个对象 —— `meta_data` —— 里，用于三个位置：

* [Create Address Book](/zh/stablecoin-account/v1.6/api-reference/create-address-book) 和 [Update Address Book](/zh/stablecoin-account/v1.6/api-reference/update-address-book) —— 描述提现目标地址的**受益人**。
* [Submit Deposit Sender Travel Rule](/zh/stablecoin-account/v1.6/api-reference/create-deposit-sender) —— 描述入账充值的**发起方**。

<h2 id="when-meta_data-is-required">
  何时必须提供 `meta_data`
</h2>

`meta_data` 在 API 层面是可选字段，但出现以下任一情形时必须提供（且需通过校验）：

| 场景                                    | 原因                                                                                 |
| ------------------------------------- | ---------------------------------------------------------------------------------- |
| 地址属于第三方（`address_party: third_party`） | 必须识别受益人身份                                                                          |
| 钱包由交易所托管（`wallet_type: hosted`）       | 必须识别托管方 VASP                                                                       |
| 地址是经 Binance 通道的提现目标                  | 地址簿条目补齐 Travel Rule 数据前，提现会被拒绝（错误：`missing travel_rule_data for binance withdraw`） |
| 充值到账时带有 `need_travel_rule: true`      | 提交发起方数据前，充值会被暂缓                                                                    |

一旦提供了 `meta_data`，其字段就会被校验 —— 提供了但内容无效的对象会导致请求失败。

<h2 id="field-reference">
  字段参考
</h2>

顶层字段 —— 只要提供 `meta_data`，以下两个字段都必填：

| 字段                        | 类型     | 取值                          | 描述                                                             |
| ------------------------- | ------ | --------------------------- | -------------------------------------------------------------- |
| `wallet_type`             | string | `hosted`、`unhosted`         | `hosted` 表示托管/交易所钱包（需要 VASP 信息）；`unhosted` 表示自托管钱包             |
| `address_party`           | string | `first_party`、`third_party` | `first_party` 表示地址属于账户持有人本人；`third_party` 表示属于其他受益人            |
| `beneficiary_information` | object | —                           | `address_party` 为 `third_party` 或 `wallet_type` 为 `hosted` 时必填 |

`beneficiary_information` 内部的必填项取决于实体类型和钱包类型：

| 字段                       | 必填条件                               | 描述                                                                                                                       |
| ------------------------ | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `entity_type`            | 第三方                                | `individual` 或 `corporation`                                                                                             |
| `first_name`、`last_name` | 第三方且 `entity_type: individual`     | 受益人的名和姓                                                                                                                  |
| `company_name`           | 第三方且 `entity_type: corporation`    | 受益人公司名称                                                                                                                  |
| `country`                | 第三方                                | ISO 3166-1 alpha-2 小写 —— 使用 [List Countries](/zh/stablecoin-account/v1.6/api-reference/list-countries) 返回的 `countryCode` |
| `city`                   | 第三方                                | 使用 [List Regions](/zh/stablecoin-account/v1.6/api-reference/list-regions) 返回的 `regionName`                               |
| `vasp_id`                | 托管钱包（`vasp_id` / `vasp_name` 至少一项） | 使用 [List VASPs](/zh/stablecoin-account/v1.6/api-reference/list-vasps) 返回的 `identifier`                                   |
| `vasp_name`              | 托管钱包                               | VASP 名称。交易所不在 VASP 目录中时，在此填写其名称并省略 `vasp_id`                                                                             |
| `id_type`、`id_primary`   | 可选                                 | 受益人身份证件类型与证件号码                                                                                                           |

常见校验错误：`invalid wallet_type`、`invalid address_party`、`invalid entity_type`、`individual third party requires first_name and last_name`、`corporation third party requires company_name`、`third party requires country and city`、`hosted wallet requires vasp_id or vasp_name`。

<h2 id="examples">
  示例
</h2>

第三方个人受益人，地址在交易所（托管）：

```json theme={null}
{
  "wallet_type": "hosted",
  "address_party": "third_party",
  "beneficiary_information": {
    "entity_type": "individual",
    "first_name": "John",
    "last_name": "Doe",
    "country": "sg",
    "city": "Singapore",
    "vasp_id": "I1QNLP",
    "vasp_name": "Binance"
  }
}
```

第三方企业，使用自托管钱包（非托管）：

```json theme={null}
{
  "wallet_type": "unhosted",
  "address_party": "third_party",
  "beneficiary_information": {
    "entity_type": "corporation",
    "company_name": "Acme Pte Ltd",
    "country": "sg",
    "city": "Singapore"
  }
}
```

账户持有人本人的自托管钱包 —— 受益人信息可以省略：

```json theme={null}
{
  "wallet_type": "unhosted",
  "address_party": "first_party"
}
```

<h2 id="look-up-reference-data">
  查询参考数据
</h2>

三个只读接口提供 `beneficiary_information` 字段必须使用的取值来源：

<Steps>
  <h3 id="list-vasps">
    List VASPs
  </h3>

  [List VASPs](/zh/stablecoin-account/v1.6/api-reference/list-vasps) 返回虚拟资产服务提供商（VASP）目录。用 `q` 搜索（匹配 `vaspName` 和 `identifier`），用 `limit` 限制结果数量。把返回的 `identifier` 用作 `vasp_id`。

  ```bash theme={null}
  curl "https://api-sandbox.uqpaytech.com/api/v1/ramp/wallet_address/vasps?q=binance&limit=10" \
    -H "x-auth-token: YOUR_API_TOKEN"
  ```

  <h3 id="list-countries">
    List Countries
  </h3>

  [List Countries](/zh/stablecoin-account/v1.6/api-reference/list-countries) 只返回当前可选的国家，以 `countryCode`（ISO alpha-2 小写）和 `countryName` 成对给出。把 `countryCode` 用作 `country`。

  <h3 id="list-regions">
    List Regions
  </h3>

  [List Regions](/zh/stablecoin-account/v1.6/api-reference/list-regions) 需要传入 `country` 代码，返回该国家的地区列表；把某个 `regionName` 用作 `city`。没有地区数据的国家返回空数组。
</Steps>

<h2 id="related">
  相关页面
</h2>

* [地址簿](/zh/stablecoin-account/v1.6/guide/address-book) —— 提现侧 `meta_data` 所在的位置
* [充值的 Travel Rule](/zh/stablecoin-account/v1.6/guide/travel-rule-for-deposits) —— 发起方侧的流程
* [发起提现](/zh/stablecoin-account/v1.6/guide/send-withdrawals)
* [List VASPs API](/zh/stablecoin-account/v1.6/api-reference/list-vasps)