> For the complete documentation index, see [llms.txt](https://docs.blockchainsecurity.asia/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blockchainsecurity.asia/documentation/investigation/trace.md).

# 多跳資金追蹤

從一個地址出發，向外或向內逐跳展開資金流向，協助釐清資金來源、去向與多層交易路徑。

可依鏈別、幣別、金額、時間範圍與追蹤深度進行篩選。此查詢屬於較重的分析型端點，成功回應扣除 5 credits，結果會以 data 與 meta 回傳。

{% hint style="warning" %}
此端點屬於較重的分析查詢。追蹤深度、時間範圍與 limit 越大，處理時間越長。請預留較長 timeout；回應為一次性 JSON 結果。
{% endhint %}

支援鏈：`tron`、`ethereum`、`bitcoin`。

## 追蹤資金流向

```bash
curl -X POST "https://api.blockchainsecurity.asia/v1/trace" \
  -H "X-API-Key: ak_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "blockchain": "tron",
    "address": "TDZmNAhbGrrSzZZ8JJx1E3YhnSQ9TZQtYy",
    "track_setting": {
      "startTime": 1721145600,
      "endTime": 1721318399,
      "outbound_depth": 3,
      "inbound_depth": 1,
      "limit": 5,
      "enable_amount_aggregation": true
    },
    "filter_criterias": [
      { "symbol": "usdt", "min_value": 496, "max_value": 700, "sign": "range" }
    ]
  }'
```

請求 body：

| 欄位                     | 必填 | 說明                                  |
| ---------------------- | -- | ----------------------------------- |
| `blockchain`           | 是  | 鏈別（`tron` / `ethereum` / `bitcoin`） |
| `address`              | 是  | 起始追蹤地址                              |
| `track_setting`        | 否  | 追蹤深度、時間範圍與結果上限設定                    |
| `filter_criterias`     | 否  | 金額、幣別或交易條件篩選                        |
| `stop_track_condition` | 否  | 達到指定深度、金額低於門檻、命中特定地址類型或超過時間範圍。      |

`track_setting` 內欄位：

| 欄位                          | 說明             |
| --------------------------- | -------------- |
| `startTime` / `endTime`     | 追蹤時間範圍（Unix 秒） |
| `outbound_depth`            | 向外（資金流出）追蹤深度   |
| `inbound_depth`             | 向內（資金流入）追蹤深度   |
| `limit`                     | 每跳展開的筆數上限      |
| `enable_amount_aggregation` | 是否啟用金額累計彙整     |

`filter_criterias[]` 內欄位：

| 欄位                        | 說明              |
| ------------------------- | --------------- |
| `symbol`                  | 幣種 symbol       |
| `min_value` / `max_value` | 金額下 / 上限        |
| `sign`                    | 比較方式（如 `range`） |

```json
{
  "data": {
    "result": {
      "transactions": [
        {
          "hash": "0x...",
          "from": "TDZmNAhbGrrSzZZ8JJx1E3YhnSQ9TZQtYy",
          "to": "TAUN6FwrnwwmaEqYcckffC7wYmbaS6cBiX",
          "symbol": "usdt",
          "value": 500.0,
          "timestamp": 1721200000,
          "depth": 1,
          "direction": "outbound"
        }
      ],
      "normal": [],
      "token": []
    }
  },
  "meta": { "request_id": "..." }
}
```

| 欄位                    | 說明                                  |
| --------------------- | ----------------------------------- |
| `result.transactions` | 展開路徑上的交易節點，包含 depth 與 direction     |
| `result.normal`       | 原生幣轉帳，例如 ETH、TRX、BTC                |
| `result.token`        | Token 轉帳，例如 USDT、USDC、ERC-20、TRC-20 |

## 端點與計費

| Method | 路徑          | 說明     | Credit |
| ------ | ----------- | ------ | ------ |
| `POST` | `/v1/trace` | 資金流向追蹤 | 5      |