API文檔

API測試與沙盒環境指南

透過Smart Money API全面的沙盒環境掌握測試技巧。使用真實的測試數據、確定性回應及寬鬆的速率限制進行無風險開發與實驗。

發佈於2026年3月21日 • 14分鐘閱讀 • 開發

沙盒環境概述

Smart Money API提供功能完整的沙盒環境供開發與測試使用。沙盒環境複製了生產API結構，但使用合成數據與寬鬆的速率限制，讓您在上線前能安心開發。

主要特性：

  • 與生產環境相同 — 相同的端點、認證方式、回應格式
  • 僅測試數據 — 絕不影響真實帳戶或即時市場
  • 高速率限制 — 每小時10,000次請求（生產環境為1,000次）
  • 確定性回應 — 一致的測試固定數據，確保可重現的測試結果
  • 隔離帳戶 — 與生產環境用戶數據完全分離

最佳實踐： 所有開發、測試及預發佈階段都應使用沙盒環境。僅在通過完整沙盒驗證後才切換至生產環境。

沙盒功能

真實測試數據

沙盒包含不會隨機變動的真實加密貨幣市場數據：

  • 歷史市場數據（6個月真實OHLCV數據）
  • 固定巨鯨錢包地址與一致的行為模式
  • 每小時重置的穩定資金費率
  • 用於測試邊界案例的確定性清算模式

測試專用功能

測試功能
// 確定性測試代幣
// 所有測試代幣皆以TEST_開頭
TEST_BTC, TEST_ETH, TEST_SOL等
// 模擬情境的特殊時間戳記
GET /v1/derivatives/funding-heatmap?
timestamp=1234567890000 // 回傳固定測試數據
// 強制觸發錯誤以測試例外處理
X-Test-Error: rate_limit_exceeded
X-Test-Error: service_unavailable

測試工具

  • 數據重置 — 將所有測試帳戶還原至初始狀態
  • 時間控制 — 模擬不同市場條件
  • 錯誤注入 — 強制回傳特定錯誤
  • 速率限制測試 — 觸發速率限制回應
30秒取得API金鑰

準備開始開發？立即獲取免費API金鑰（每日50次呼叫，免綁卡），開始獲取巨鯨、資金費率及鏈上數據。

取得API金鑰 →

測試憑證

獲取測試API金鑰

透過儀表板創建測試帳戶以生成沙盒API金鑰：

測試金鑰格式
// 測試金鑰有不同前綴
sk_test_1234567890abcdef // 測試API金鑰
sk_live_1234567890abcdef // 生產API金鑰
// 自動路由至對應環境
GET https://api.smartmoneyapi.com/v1/whales
-H "Authorization: Bearer sk_test_xxx"
# 自動導向至沙盒環境

預設測試金鑰

使用這些公開測試金鑰快速體驗（有速率限制）：

金鑰 權限 限制
sk_test_demo 唯讀權限 100次/小時
sk_test_trader 讀取 + 警報 500次/小時
sk_test_pro 完整權限 5000次/小時

切勿在生產環境使用測試金鑰。 其功能與速率限制均有限制。

測試數據與固定資料

可用測試代幣

沙盒包含以下具有真實歷史數據的測試交易對：

測試代幣
// 加密貨幣交易對
TEST_BTCUSDT, TEST_ETHUSDT, TEST_BNBUSDT
TEST_SOLSDT, TEST_ARBUSDT, TEST_OPUSDT
// 查詢測試代幣
GET /v1/symbols?test_only=true

測試巨鯨錢包

預設測試錢包具確定性行為：

  • 累積型錢包 — 持續買入，適合多頭測試
  • 分配型錢包 — 持續賣出，適合空頭測試
  • 震盪型錢包 — 交替買賣，適合區間震盪測試
  • 波動型錢包 — 隨機大額交易，適合壓力測試

重置測試數據

重置測試數據
// 重置所有測試帳戶至初始狀態
POST /v1/test/reset
-H "Authorization: Bearer sk_test_xxx"
// 重置特定資源
POST /v1/test/reset?resource=whales
// 回應
{
"status": "reset_complete",
"timestamp": 1709980800000
}

沙盒端點

基礎URL

環境URL
// 沙盒（測試模式）
https://api-test.smartmoney.io/v1
// 或使用查詢參數
https://api.smartmoneyapi.com/v1?environment=sandbox
// 生產（實時模式）
https://api.smartmoneyapi.com/v1

僅限沙盒的端點

端點 目的
POST /test/reset 將測試數據重置為初始狀態
POST /test/inject-error 注入特定錯誤以進行測試
POST /test/simulate-time 模擬不同的市場條件
GET /test/status 檢查沙盒環境的健康狀態

回應模擬

注入測試錯誤

強制特定錯誤回應以進行異常處理測試：

錯誤注入
// 測試速率限制處理
GET /v1/whales?X-Test-Error=rate_limit_exceeded
// 測試服務不可用
GET /v1/whales?X-Test-Error=service_unavailable
// 測試認證失敗
GET /v1/whales?X-Test-Error=invalid_key
// 測試超時
GET /v1/whales?X-Test-Error=timeout

可用的測試錯誤

錯誤代碼 HTTP狀態 使用案例
invalid_key 401 認證錯誤處理
rate_limit_exceeded 429 退避邏輯測試
not_found 404 缺失資源處理
service_unavailable 503 重試邏輯測試
timeout 504 超時處理

沙盒速率限制

速率限制層級

環境 限制/小時 突發 目的
沙盒 10,000 500/分鐘 開發與測試
生產免費 1,000 50/分鐘 業餘項目
生產交易者 10,000 400/分鐘 專業交易
生產專業 50,000 1000/分鐘 高頻系統

測試速率限制處理

速率限制測試
// 在沙盒中觸發速率限制回應
curl -H "X-Test-Error: rate_limit_exceeded" \
https://api-test.smartmoney.io/v1/whales
// 回應包含重試標頭
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1709984400
Retry-After: 3600

測試策略

使用固定裝置進行單元測試

Python單元測試
import unittest
import requests
class TestSmartMoneyAPI(unittest.TestCase):
def setUp(self):
self.api_key = 'sk_test_demo'
self.base_url = 'https://api-test.smartmoney.io/v1'
def test_whale_tracking(self):
response = requests.get(
f'{self.base_url}/whales/TEST_BTC',
headers={'Authorization': f'Bearer {self.api_key}'}
)
self.assertEqual(response.status_code, 200)
self.assertIn('whales', response.json())

整合測試

在生產部署前在沙盒中測試完整工作流程：

  1. 使用沙盒憑證部署到暫存環境
  2. 針對沙盒運行完整測試套件
  3. 使用錯誤注入測試錯誤處理
  4. 驗證速率限制行為
  5. 檢查回應時間和延遲
  6. 然後才推送到生產環境

負載測試

使用Apache Bench進行負載測試
// 沙盒允許高負載測試
ab -n 5000 -c 100 \
-H "Authorization: Bearer sk_test_pro" \
https://api-test.smartmoney.io/v1/whales/TEST_BTC

CI/CD整合

GitHub Actions範例

.github/workflows/test.yml
name: API Tests
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- run: pip install requests pytest
- env:
SMARTMONEY_API_KEY: ${{ secrets.TEST_API_KEY }}
SMARTMONEY_ENV: sandbox
run: pytest tests/

環境配置

使用環境變數切換沙盒與生產環境：

環境設定
// .env.sandbox
SMARTMONEY_API_KEY=sk_test_demo
SMARTMONEY_API_URL=https://api-test.smartmoney.io/v1
SMARTMONEY_ENV=sandbox
// .env.production
SMARTMONEY_API_KEY=sk_live_xxxx
SMARTMONEY_API_URL=https://api.smartmoneyapi.com/v1
SMARTMONEY_ENV=production

疑難排解

常見問題

測試金鑰無效

問題： 使用測試金鑰時出現401未授權錯誤

解決方案：

  • 確認金鑰以sk_test_開頭（非sk_live_）
  • 檢查Authorization標頭格式："Bearer sk_test_xxx"
  • 確保使用測試端點：api-test.smartmoney.io
  • 測試金鑰可能已達速率限制

資料未重置

問題： 執行POST /test/reset後測試資料未重置

解決方案：

  • 重置可能需要最多30秒生效
  • 使用GET /test/status檢查沙盒狀態
  • 確認使用正確的測試API金鑰
  • 若持續發生請聯繫支援

沙盒中的速率限制

問題： 在沙盒環境觸發速率限制（不應發生）

解決方案：

  • 確認使用sk_test_pro金鑰（10,000次/小時）
  • 檢查X-RateLimit-Remaining標頭
  • 等待整點或使用其他測試帳戶
  • 聯繫支援暫時提高速率限制

立即開始測試

使用我們完整的沙盒環境進行安全隔離的開發。提供確定性測試資料、高速率限制，並與生產環境功能完全一致。

取得測試憑證
所有方案皆包含沙盒存取權限，無需額外費用。

相關資源

認證指南 →

API認證與金鑰管理

REST API參考 →

完整API端點文件

錯誤代碼 →

錯誤處理與回應代碼
免費開始 — 每日50次呼叫，無需信用卡

透過單一API取得3大交易所的實時大戶資金流向、資金費率、未平倉量及鏈上數據。免費方案無需信用卡，隨時可升級。

免費開始 →
試用實時API控制台 → （無需帳戶）