API 文件

打造能自主探索並使用服務的 AI Agent。

Base URL: https://agentictrade.io/api/v1

快速開始

三個步驟讓你的 Agent 開始呼叫服務：

建立 API 金鑰

curl -X POST https://agentictrade.io/api/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"owner_id": "my-agent-001", "role": "buyer"}'

# Response:
# {"key_id": "acf_a1b2c3...", "secret": "Sp8vKq9w...", "role": "buyer"}
# Save the secret — it won't be shown again!

瀏覽可用服務

curl https://agentictrade.io/api/v1/discover

# Returns all active services with pricing, categories, and free tier info

呼叫服務

curl -X POST https://agentictrade.io/api/v1/proxy/{service_id}/api/scan \
  -H "Authorization: Bearer acf_a1b2c3:Sp8vKq9w..." \
  -H "Content-Type: application/json"

# The marketplace handles payment automatically.
# Response headers include billing info:
# X-ACF-Amount: 0.50
# X-ACF-Free-Tier: true

身分驗證

所有需要驗證的端點都使用 Bearer token 認證：

Authorization: Bearer {key_id}:{secret}

範例：

Authorization: Bearer acf_a1b2c3d4e5f6g7h8:Sp8vKq9wRx2yZaA_B1C2D3E4F5G6H7

角色

角色權限
buyer透過代理呼叫服務、查看餘額、檢視使用量
provider註冊並管理服務、查看收益
admin完整平台存取權限

速率限制

等級限制
預設每分鐘 60 次請求
最大每分鐘 300 次請求

可用服務

CoinSifter Demo — Sample Results

Free demo endpoint returning sample CoinSifter scan results. No Binance API key required. Test integration before upgrad...

免費
ID: 758c1057-191e-405e-a352-7f52bcd97a82

Strategy Catalog — Browse Templates

Browse available trading strategy templates and their configurable parameters. Free to access.

免費
ID: 0a7ab758-ee00-4141-afcd-d86d5fd1536b

AI Result Validator

Two-layer AI task validation API. Rule-based fast screening (<100ms) catches errors, empty claims, and missing evidence....

$0.01 / 次 20 免費
ID: 69517247-9a7d-45d7-8ba7-bee3b3cc130b

Test Echo API

A simple echo service for testing

$0.01 / 次 10 免費
ID: 517f8fff-cd14-483d-9f17-1262832b64a4

CoinSifter Pro API

Real-time crypto scanner — scans 600+ USDT pairs across exchanges, applies multi-strategy filtering with technical indic...

$0.1 / 次 10 免費
ID: 7ed931d1-57fb-4d97-8a27-8efd3dad04a4

CoinSifter — Crypto Market Scanner

AI-powered cryptocurrency market scanner. Scans Binance USDT pairs with customizable technical indicators (RSI, EMA, MAC...

$0.5 / 次 5 免費
ID: 6a9939cf-583b-4e6d-897f-360dcf200f59

Shorts Script Factory API

Turn one topic into a production-ready Shorts script — returned as usable JSON with hooks, scenes, visual prompts, CTA, ...

$0.79 / 次
ID: 43d2d4ad-f1b2-43e4-b91c-ea366b307588

Strategy Backtest API

Run backtests with pre-built crypto trading strategies. 3 strategies: BB Squeeze (momentum), MACD Divergence (reversal),...

$2.0 / 次 3 免費
ID: 3c6734ed-3d9c-472c-a8dd-b190d1d4ac05

服務探索

GET /api/v1/services 列出所有服務

回傳所有已註冊的服務及定價資訊。不需要驗證。

查詢參數

參數類型描述
categorystring依分類篩選
querystring依名稱/描述搜尋
limitint最大結果數（預設：50）
offsetint分頁偏移量
 
curl https://agentictrade.io/api/v1/services?category=crypto-analysis
GET /api/v1/discover 進階服務探索

支援篩選、排序和標籤匹配的進階探索功能。

查詢參數

參數類型描述
tagsstring以逗號分隔的標籤篩選
min_pricefloat每次呼叫最低價格
max_pricefloat每次呼叫最高價格
sortstring排序方式：price、name、created
 
curl "https://agentictrade.io/api/v1/discover?tags=crypto&max_price=1.0&sort=price"
GET /api/v1/discover/categories 列出分類

回傳可用的服務分類及各分類的服務數量。

curl https://agentictrade.io/api/v1/discover/categories

代理 — 呼叫服務

這是核心端點。你的 Agent 將請求發送到這裡，市集負責路由、付款和使用量追蹤。
POST /api/v1/proxy/{service_id}/{path} 呼叫服務

將你的請求代理到服務供應商。支援 GET、POST、PUT、PATCH、DELETE。

路徑參數

參數描述
service_id目標服務的 UUID
path供應商的 API 路徑 (e.g., api/scan)

回應標頭

標頭描述
X-ACF-Usage-Id唯一使用紀錄 ID
X-ACF-Amount收取金額（USDC）
X-ACF-Free-Tiertrue 如果使用了免費額度則為 true
X-ACF-Latency-Ms請求延遲（毫秒）

範例：CoinSifter Demo（免費）

curl -H "Authorization: Bearer {key_id}:{secret}" \
  "https://agentictrade.io/api/v1/proxy/758c1057-191e-405e-a352-7f52bcd97a82/api/demo"

# Returns real-time crypto scan results

範例：CoinSifter Scanner（$0.50/次）

curl -X POST -H "Authorization: Bearer {key_id}:{secret}" \
  "https://agentictrade.io/api/v1/proxy/6a9939cf-583b-4e6d-897f-360dcf200f59/api/scan"

# Triggers a full market scan with your strategy

範例：Strategy Backtest（$2.00/次）

curl -X POST -H "Authorization: Bearer {key_id}:{secret}" \
  -H "Content-Type: application/json" \
  -d '{"symbol": "BTC/USDT", "strategy": "bb_squeeze", "timeframe": "4h"}' \
  "https://agentictrade.io/api/v1/proxy/3c6734ed-3d9c-472c-a8dd-b190d1d4ac05/api/backtest"

# Returns win rate, profit factor, equity curve, trade list
GET /api/v1/usage/me 你的使用統計

回傳已驗證買家的總呼叫數、花費及平均延遲。

curl -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/usage/me

# {"buyer_id": "my-agent", "total_calls": 42, "total_spent_usd": "12.50", "avg_latency_ms": 35}

帳單與儲值

服務採預付制。先將資金儲值到你的帳戶，再呼叫服務。

大多數服務包含免費額度。只有免費次數用完後才需要儲值。
GET /api/v1/balance/{buyer_id} 查詢餘額 
curl https://agentictrade.io/api/v1/balance/my-agent-001

# {"buyer_id": "my-agent-001", "balance": 50.0, "total_deposited": 100.0, "total_spent": 50.0}
POST /api/v1/deposits 儲值

透過 NOWPayments 建立加密貨幣付款帳單。支援 USDT、USDC、BTC、ETH 及 300 種以上加密貨幣。

curl -X POST https://agentictrade.io/api/v1/deposits \
  -H "Content-Type: application/json" \
  -d '{"buyer_id": "my-agent-001", "amount": 50}'

# {"deposit_id": "...", "amount": 50, "status": "pending",
#  "checkout_url": "https://nowpayments.io/payment/?iid=...",
#  "message": "Pay $50 at the checkout URL..."}

付款確認後，你的餘額會透過 IPN webhook 自動入帳。

API 金鑰

POST /api/v1/keys 建立 API 金鑰

請求內容

欄位類型必填描述
owner_idstring是你的 Agent/使用者識別碼
rolestring否buyer（預設）或 provider
 
curl -X POST https://agentictrade.io/api/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"owner_id": "my-trading-bot", "role": "buyer"}'

# {"key_id": "acf_...", "secret": "...", "role": "buyer", "rate_limit": 60}
# IMPORTANT: Save the secret! It cannot be retrieved later.

供應商

供應商管理服務、查看收益及追蹤健康狀態的端點。全部需要供應商角色驗證。

GET /api/v1/provider/dashboard 供應商總覽

回傳已驗證供應商的服務數量、總呼叫數、收益及結算狀態。

curl -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/provider/dashboard
GET /api/v1/provider/services 列出你的服務

回傳已驗證供應商所擁有的所有服務及使用統計。

curl -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/provider/services
GET /api/v1/provider/services/{service_id}/analytics 服務分析

特定服務的詳細分析：總呼叫數、收益、成功率、每日明細。

curl -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/provider/services/{service_id}/analytics
GET /api/v1/provider/earnings 收益摘要

回傳總收益、已結算、待處理金額及結算歷史。

curl -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/provider/earnings
GET /api/v1/provider/health 服務健康評分

根據延遲、錯誤率和正常運行時間回傳所有服務的健康評分。

curl -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/provider/health
POST /api/v1/provider/services/{service_id}/test 測試服務端點

測試與你的服務端點的連線狀態。回傳可達性、延遲及狀態碼。

curl -X POST -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/provider/services/{service_id}/test
GET /api/v1/provider/onboarding 新手引導進度

追蹤你的新手引導進度：API 金鑰建立、服務註冊、首次流量、首次結算。

curl -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/provider/onboarding

結算

管理供應商出金的管理員端點。

POST /api/v1/settlements 建立結算

為供應商建立新的結算。需要管理員角色。

curl -X POST -H "Authorization: Bearer {key_id}:{secret}" \
  -H "Content-Type: application/json" \
  -d '{"provider_id": "prov-001", "period_start": "2026-01-01", "period_end": "2026-02-01"}' \
  https://agentictrade.io/api/v1/settlements
GET /api/v1/settlements 列出結算

列出所有結算，可依供應商或狀態篩選。

curl -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/settlements
PATCH /api/v1/settlements/{settlement_id}/pay 執行結算付款

將結算標記為已付款並觸發鏈上轉帳。

curl -X PATCH -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/settlements/{settlement_id}/pay

推薦計畫

推薦計畫端點，用於產生及追蹤推薦碼。

POST /api/v1/referrals/code 建立推薦碼

為已驗證的使用者產生唯一推薦碼。

curl -X POST -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/referrals/code
POST /api/v1/referrals/apply 套用推薦碼

在註冊時套用推薦碼以連結帳戶。

curl -X POST -H "Content-Type: application/json" \
  -d '{"code": "REF-ABC123"}' \
  https://agentictrade.io/api/v1/referrals/apply
GET /api/v1/referrals 列出推薦紀錄

列出已驗證使用者的所有推薦紀錄。

curl -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/referrals
GET /api/v1/referrals/stats 推薦統計

匯總推薦統計：總推薦數、轉換率及收益。

curl -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/referrals/stats

Webhooks

訂閱即時事件通知。

POST /api/v1/webhooks 建立 Webhook

註冊新的 Webhook 端點以接收事件通知。

請求內容

欄位類型描述
urlstring接收事件的 HTTPS 端點
eventsarray要訂閱的事件類型: usage.created, settlement.completed, etc.
 
curl -X POST -H "Authorization: Bearer {key_id}:{secret}" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://myapp.com/webhooks", "events": ["usage.created"]}' \
  https://agentictrade.io/api/v1/webhooks
GET /api/v1/webhooks 列出 Webhooks

列出你帳戶中所有已註冊的 Webhooks。

curl -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/webhooks
DELETE /api/v1/webhooks/{webhook_id} 刪除 Webhook

移除 Webhook 訂閱。

curl -X DELETE -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/webhooks/{webhook_id}

稽核

用於追蹤平台活動的安全稽核端點。需要管理員角色。

GET /api/v1/admin/audit 稽核日誌

回傳支援篩選的安全稽核日誌。

curl -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/admin/audit
GET /api/v1/admin/audit/summary 稽核摘要

匯總稽核統計：依類型和時間區間的事件數量。

curl -H "Authorization: Bearer {key_id}:{secret}" \
  https://agentictrade.io/api/v1/admin/audit/summary

錯誤回應

所有 API 錯誤都會回傳一致的 JSON 結構，並附帶適當的 HTTP 狀態碼。

常見狀態碼

狀態碼 含義 描述
400Bad Request無效的參數或格式錯誤的請求內容。
401Unauthorized缺少或無效的 API 金鑰。
403Forbidden對請求的資源權限不足。
404Not Found請求的資源不存在。
429Too Many Requests超過速率限制。請等待後重試。
500Internal Server Error未預期的伺服器錯誤。若持續發生，請聯繫支援。

錯誤回應格式

每個錯誤回應都包含一個錯誤代碼、一段人類可讀的訊息，以及 HTTP 狀態碼：

{
  "error": "unauthorized",
  "message": "Invalid API key. Check your key_id and secret.",
  "status": 401
}

欄位：

欄位 類型 描述
errorstring機器可讀的錯誤代碼（例如 "unauthorized"、"bad_request"、"rate_limited"）。
messagestring人類可讀的錯誤描述。
statusintHTTP 狀態碼（與回應狀態一致）。

速率限制標頭

每個回應都包含速率限制標頭，讓您的代理可以主動調節請求頻率：

標頭 描述 範例
X-RateLimit-Limit每個時間窗口允許的最大請求數量。60
X-RateLimit-Remaining目前時間窗口中剩餘的請求數量。42
X-RateLimit-Reset速率限制窗口重置時的 Unix 時間戳（秒）。1711324800

當收到 429 回應時，使用這些標頭來決定何時重試：

# Example 429 response headers
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1711324800
Content-Type: application/json

{
  "error": "rate_limited",
  "message": "Rate limit exceeded. Retry after 1711324800.",
  "status": 429
}

Python SDK

安裝 SDK：

# Install from PyPI
pip install agentictrade

使用內建 SDK 實現無縫整合：

from sdk.client import ACFClient

client = ACFClient(
    base_url="https://agentictrade.io",
    api_key="acf_xxx:secret_yyy",
)

# Discover services
services = client.list_services(category="crypto-analysis")

# Call a service through the proxy
result = client.proxy(
    service_id="6a9939cf-583b-4e6d-897f-360dcf200f59",
    path="api/scan",
    method="POST",
)
print(result["results"])

Agent 整合指南

自主 Agent 如何使用 AgenticTrade：

Agent 探索可用服務

GET /api/v1/discover — 找到符合任務需求的服務。

Agent 檢查餘額

GET /api/v1/balance/{buyer_id} — 確保資金充足。

Agent 呼叫服務

POST /api/v1/proxy/{service_id}/{path} — 市集處理付款。

Agent 處理回應

來自供應商的回應內容 + 來自市集的帳單標頭。

定價

服務價格免費額度付款方式
CoinSifter Demo — Sample Results 免費 永久免費 加密貨幣（100+ 幣種）
Strategy Catalog — Browse Templates 免費 永久免費 加密貨幣（100+ 幣種）
AI Result Validator $0.01 USDC 20 次 加密貨幣（100+ 幣種）
Test Echo API $0.01 USDC 10 次 加密貨幣（100+ 幣種）
CoinSifter Pro API $0.1 USDC 10 次 加密貨幣（100+ 幣種）
CoinSifter — Crypto Market Scanner $0.5 USDC 5 次 加密貨幣（100+ 幣種）
Shorts Script Factory API $0.79 USDC 永久免費 加密貨幣（100+ 幣種）
Strategy Backtest API $2.0 USDC 3 次 加密貨幣（100+ 幣種）
平台佣金：第 1 個月 0%，第 2-3 個月 5%，之後 10%（上限）。透過 NOWPayments 接受儲值（USDT、USDC、BTC、ETH 及 300 種以上加密貨幣）。
© 2025-2026 AgenticTrade by JudyAI Lab. 保留所有權利。