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

# 快速开始

> 几次 API 调用即可接收你的第一笔加密货币充值并查询余额。

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

本指南带你在沙盒环境中走完核心充值流程：查询可接收的资产、获取充值地址、确认资金到账。完成后，你就跑通了每个 Stablecoin Account 集成都会用到的起步接口。

<Info>
  **前置条件**

  * 一个已启用 Stablecoin Account 的 UQPAY 沙盒账户
  * 通过 [Access Token](/zh/account-center/v1.6/api-reference/access-token) 接口获取的 API token，随请求放在 `x-auth-token` 请求头中
</Info>

<Steps>
  <Step title="查询支持的资产与网络">
    先向系统查询当前可用的币种和网络，以及各自是否开放充值。

    ```bash theme={null}
    curl "https://api-sandbox.uqpaytech.com/api/v1/ramp/config/assets?asset_type=CRYPTO" \
      -H "x-auth-token: YOUR_API_TOKEN" \
      -H "Content-Type: application/json"
    ```

    **响应（节选）：**

    ```json theme={null}
    {
      "code": 200,
      "message": "Success",
      "data": [
        {
          "asset": "USDT",
          "asset_name": "Tether USD",
          "asset_type": "CRYPTO",
          "networks": [
            {
              "network": "ETH",
              "network_name": "Ethereum (ERC20)",
              "deposit_enabled": true,
              "withdraw_enabled": true,
              "min_deposit_amount": "10.00",
              "min_withdraw_amount": "20.00",
              "withdraw_precision": 2,
              "estimated_arrival_time": 15
            }
          ]
        }
      ]
    }
    ```

    选择一个 `deposit_enabled: true` 的资产-网络组合，并留意 `min_deposit_amount` —— 低于该最小金额的充值不会入账。
  </Step>

  <Step title="获取充值地址">
    为选定的资产和网络请求充值地址。地址只生成一次并与你的账户绑定，后续充值可以重复使用。

    ```bash theme={null}
    curl "https://api-sandbox.uqpaytech.com/api/v1/ramp/deposit/address?asset=USDT&network=ETH" \
      -H "x-auth-token: YOUR_API_TOKEN" \
      -H "Content-Type: application/json"
    ```

    **响应：**

    ```json theme={null}
    {
      "code": 200,
      "message": "Success",
      "data": {
        "asset": "USDT",
        "network": "ETH",
        "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
        "qr_code": "https://cdn.uqpaytech.com/qr/...",
        "minimum_deposit": "10.00",
        "create_time": "2024-07-18T14:19:52+08:00"
      }
    }
    ```

    <Warning>
      只能向该地址发送指定网络上的指定资产。以其他代币形式、或经其他网络发送的资金无法自动入账。
    </Warning>
  </Step>

  <Step title="发送资金并接收充值 webhook">
    从外部钱包向充值地址转入资产。系统检测到链上交易后会创建充值订单，并向你的 webhook 端点推送 `ramp.deposit.pending` 事件；充值确认后再推送 `ramp.deposit.success`：

    ```json theme={null}
    {
      "version": "V1.6.0",
      "event_name": "DEPOSIT",
      "event_type": "ramp.deposit.pending",
      "event_id": "38614827-7666-4c0c-abae-cc3abef24903",
      "source_id": "eda7be90-8fbc-444c-b747-542faf5d3e10",
      "data": {
        "amount": "10",
        "currency": "USDC",
        "network": "ETH",
        "order_id": "eda7be90-8fbc-444c-b747-542faf5d3e10",
        "order_status": "Pending",
        "short_order_id": "DP260227-QZOXQND1",
        "from_address": "0x303039d7632c7341c681e889ea0073c3af1a2f6a",
        "txid": "0x65590ef2a2ef1902f3644da38b19eaf4b953831c0deaac73cadce02ee356d5d1",
        "transaction_type": "Deposit",
        "create_time": "2026-02-27 10:19:19 +0800 CST",
        "complete_time": "0001-01-01 00:00:00 +0000 UTC",
        "fee": "0",
        "reason": "test-remark",
        "need_travel_rule": true
      }
    }
    ```

    后续可用 `source_id`（即充值 `order_id`）查询该订单。

    <Note>
      如果事件中包含 `"need_travel_rule": true`，该笔充值需要先提交发起方信息才能继续处理。参见[充值的 Travel Rule](/zh/stablecoin-account/v1.6/guide/travel-rule-for-deposits)。
    </Note>
  </Step>

  <Step title="确认充值并查询余额">
    按订单 ID 查询充值订单，或直接查询入账币种的钱包余额。

    ```bash theme={null}
    curl "https://api-sandbox.uqpaytech.com/api/v1/ramp/deposit/eda7be90-8fbc-444c-b747-542faf5d3e10" \
      -H "x-auth-token: YOUR_API_TOKEN" \
      -H "Content-Type: application/json"
    ```

    当 `order_status` 变为 `Success` 后，资金会出现在你的资产钱包中：

    ```bash theme={null}
    curl "https://api-sandbox.uqpaytech.com/api/v1/ramp/asset/USDT" \
      -H "x-auth-token: YOUR_API_TOKEN" \
      -H "Content-Type: application/json"
    ```

    **响应：**

    ```json theme={null}
    {
      "code": 200,
      "message": "Success",
      "data": {
        "balance_id": "5e56e5de-f354-4570-8cbc-cc134d7a5b75",
        "balance_currency": "USDT",
        "balance_status": "Active",
        "available_balance": "9100",
        "margin_balance": "0",
        "frozen_balance": "0",
        "create_time": "2025-06-30 17:03:06 +08:00",
        "last_trade_time": "2025-10-24 17:51:24 +08:00"
      }
    }
    ```
  </Step>
</Steps>

<h2 id="what-s-next">
  下一步
</h2>

<CardGroup cols={2}>
  <Card title="发起提现" href="/zh/stablecoin-account/v1.6/guide/send-withdrawals" icon="arrow-up-from-bracket">
    登记目标地址并将资金提现到平台外。
  </Card>

  <Card title="货币兑换" href="/zh/stablecoin-account/v1.6/guide/convert-currencies" icon="arrow-right-arrow-left">
    锁定报价并在加密货币与法币之间兑换。
  </Card>

  <Card title="转账" href="/zh/stablecoin-account/v1.6/guide/transfer-funds-between-stablecoin-account-and-global-account" icon="building-columns">
    将法币划转到你的 Global Account。
  </Card>

  <Card title="核心概念" href="/zh/stablecoin-account/v1.6/guide/core-concepts" icon="book">
    理解资产、订单类型、状态与幂等性。
  </Card>
</CardGroup>