> ## 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.

# 核心概念

> 理解 Stablecoin Account API 通用的资产、网络、订单类型、状态与请求约定。

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

本页介绍适用于所有 Stablecoin Account 接口的术语与请求约定。建议在开始集成前通读一遍 —— 指南的其余部分默认你已掌握这些概念。

<h2 id="assets-networks-and-balances">
  资产、网络与余额
</h2>

以下四个术语贯穿整个 API：

| 术语              | 含义                                                             | 示例                                         |
| --------------- | -------------------------------------------------------------- | ------------------------------------------ |
| **资产（Asset）**   | 你可以持有或调拨的币种 —— 加密货币或法币。每个资产的 `asset_type` 为 `CRYPTO` 或 `FIAT`。 | `USDT`、`USDC`、`USD`                        |
| **网络（Network）** | 加密资产流转所在的区块链。同一资产可能支持多个网络，各网络的限额与费用不同。                         | `ETH`、`TRX`、`BSC`                          |
| **余额（钱包）**      | 你持有的某一币种，由 `balance_id` 和 `balance_currency` 标识。首次收到该币种时自动创建。  | 一个 `available_balance: "9100"` 的 `USDC` 钱包 |
| **钱包地址（充值地址）**  | UQPAY 为你管理的、用于接收加密货币充值的区块链地址。每个资产-网络组合对应一个地址 —— 首次请求时生成，此后复用。  | `TRX` 网络上的 `USDT` 充值地址                     |

每个余额分为三个部分：

* `available_balance` —— 当前可以提现、兑换或转账的资金。
* `frozen_balance` —— 被在途订单或风控审核锁定的资金。
* `margin_balance` —— 作为保证金预留的资金。

通过 [List Assets](/zh/stablecoin-account/v1.6/api-reference/list-assets) 查询余额；在向用户开放某个资产-网络组合之前，务必先查询 [List Supported Assets and Networks](/zh/stablecoin-account/v1.6/api-reference/list-supported-assets)：它会告诉你充值和提现当前是否开放、最小金额、精度以及预计到账时间。

<h3 id="wallet-addresses">
  钱包地址
</h3>

**钱包地址**和余额不是一回事：余额是你持有的资金，钱包地址是付款方向你转入加密货币的目标位置。UQPAY 按资产-网络组合生成并管理地址 —— 首次请求时创建，之后每次请求都返回同一个地址，可以放心重复调用。每个地址只接受其对应网络上的对应资产；以其他代币形式、或经其他网络发送的资金无法自动入账。

通过 [Deposit Wallet Address](/zh/stablecoin-account/v1.6/api-reference/deposit-wallet-address) 获取地址（完整流程见[接收充值](/zh/stablecoin-account/v1.6/guide/receive-deposits)），或在商户后台直接查看 —— 参见[钱包地址 - 在商户后台查看钱包地址](/zh/stablecoin-account/v1.6/guide/wallet-address)。

<h2 id="order-types-and-lifecycles">
  订单类型与生命周期
</h2>

每一次资金变动都会创建一个**订单**，包含长 `order_id`（UUID）和便于人工识别的 `short_order_id`（例如 `WD260124-N1PAAIXX`）。订单会出现在统一的[资产交易流水](/zh/stablecoin-account/v1.6/api-reference/list-asset-transactions)中，类型为以下之一：

| 订单类型                           | 创建方式                                                                             | 作用                                           |
| ------------------------------ | -------------------------------------------------------------------------------- | -------------------------------------------- |
| `Deposit`                      | 加密货币转入你的充值地址                                                                     | 加密货币余额入账                                     |
| `Withdraw`                     | [Create Withdraw](/zh/stablecoin-account/v1.6/api-reference/create-withdraw)     | 向外部地址发送加密货币                                  |
| `Sell` / `Buy` / `Swap`        | [Create Conversion](/zh/stablecoin-account/v1.6/api-reference/create-conversion) | 在币种之间兑换                                      |
| `Transfer In` / `Transfer Out` | [Create Transfer](/zh/stablecoin-account/v1.6/api-reference/create-transfer)     | 在 Global Account 与 Stablecoin Account 之间划转法币 |

<h3 id="order-statuses">
  订单状态
</h3>

| 状态              | 含义                     |
| --------------- | ---------------------- |
| `Submitted`     | 订单已受理并排队（兑换与转账）。       |
| `Pending`       | 订单处理中 —— 等待链上确认、清算或审核。 |
| `Success`       | 订单完成，余额已最终生效。          |
| `Failed`        | 订单提交后失败。               |
| `Submit Failed` | 订单在提交时被拒绝（兑换与转账）。      |

充值和提现只使用其中的 `Pending` → `Success` / `Failed` 子集。只把 `Success` 和终态的 `failed` webhook 事件当作最终状态；受网络拥堵影响，`Pending` 订单可能持续较长时间。

<h2 id="request-conventions">
  请求约定
</h2>

<h3 id="base-urls">
  Base URL
</h3>

| 环境 | Base URL                                |
| -- | --------------------------------------- |
| 沙盒 | `https://api-sandbox.uqpaytech.com/api` |
| 生产 | `https://api.uqpay.com/api`             |

所有 Stablecoin Account 接口都位于 `/v1/ramp/` 路径下，两个环境的路径完全相同。

<h3 id="authentication">
  认证
</h3>

使用 `x-client-id` 和 `x-api-key` 凭证从 [Access Token](/zh/account-center/v1.6/api-reference/access-token) 接口获取访问令牌，然后在每次调用时携带：

```bash theme={null}
curl "https://api-sandbox.uqpaytech.com/api/v1/ramp/asset?page_size=10&page_num=1" \
  -H "x-auth-token: YOUR_API_TOKEN"
```

<h3 id="acting-on-behalf-of-a-sub-account">
  代表子账户操作
</h3>

传入可选的 `x-on-behalf-of` 请求头（值为子账户的 `account_id`），即可代表该子账户执行请求；不传则以主账户身份操作。子账户机制参见 [Connected Accounts](/zh/account-center/v1.6/guide/connected-accounts)。

<h3 id="idempotency">
  幂等性
</h3>

会创建订单的写接口 —— [Create Transfer](/zh/stablecoin-account/v1.6/api-reference/create-transfer)、[Create Conversion](/zh/stablecoin-account/v1.6/api-reference/create-conversion)、[Create Withdraw](/zh/stablecoin-account/v1.6/api-reference/create-withdraw)、[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) —— 都接受 `x-idempotency-key` 请求头（UUID）。使用相同的 key 重试请求会返回原始结果，而不会创建重复订单。每个业务操作生成一个新的 UUID，网络重试时复用同一个：

```bash theme={null}
-H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')"
```

<h3 id="response-envelope">
  响应结构
</h3>

所有响应都使用同一套结构封装。`code` 与 HTTP 状态码一致，`data` 承载结果：

```json theme={null}
{
  "code": 200,
  "message": "Success",
  "data": { }
}
```

列表接口在 `data` 内通过 `total_pages` 和 `total_items` 分页，由 `page_num` 和 `page_size` 查询参数控制。金额字段是十进制字符串（例如 `"100.50"`）—— 请用十进制类型解析，不要用浮点数。非 2xx 响应参见[错误码](/zh/stablecoin-account/v1.6/guide/error-codes)。

<h3 id="webhooks">
  Webhooks
</h3>

订单状态变化会以 `ramp.<resource>.<status>` 命名的事件（例如 `ramp.deposit.success`）推送到你配置的 webhook 端点。每个事件的 `data` 携带订单内容，`source_id` 携带订单 ID。各事件的报文参见 [Webhooks 标签页](/zh/stablecoin-account/v1.6/webhooks/deposit)。

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

* [快速开始](/zh/stablecoin-account/v1.6/guide/quickstart) —— 端到端跑通充值流程
* [List Supported Assets and Networks API](/zh/stablecoin-account/v1.6/api-reference/list-supported-assets)
* [错误码](/zh/stablecoin-account/v1.6/guide/error-codes)