API 總覽
Tenorline API 讓你詢價、成交並管理以 USDC 結算的無本金交割遠期外匯（NDF）。交易台的每個畫面都建立在這些端點上，所以在交易台能做的事，都能從你自己的產品完成，包括把匯率鎖定以白牌方式嵌入支付或資金管理流程。
API 採 HTTPS 上的 REST，請求與回應皆為 JSON。金額一律以 USD/USDC 計，時間戳記一律為 ISO-8601 UTC，匯率一律以「每 1 美元兌多少當地貨幣」報價。
| 環境 | Base URL | 說明 |
|---|---|---|
| 沙盒 | https://…/v1 | 交易商、定盤與區塊鏈皆為模擬。任何 sk_test_ 金鑰都會開立一個已注資的帳戶。 |
| 正式 | https://api.<your-domain>/v1 | 介面相同，須完成合格交易對手的開戶審核。 |
…
驗證
以 Bearer token 傳送你的私密金鑰。市場資料與交易商端點為公開，所有與帳戶相關的端點都需要金鑰。
Authorization: Bearer sk_test_…
沙盒中，任何符合 sk_test_ 加 16–64 個英數字元的金鑰，首次使用時都會自動開立帳戶並注入 1,000,000 測試 USDC。此瀏覽器的金鑰為 (重設沙盒)
慣例
| 欄位 | 意義 |
|---|---|
pair | 一律為 USD/XXX（例如 USD/MXN）。放在網址路徑時改用連字號：USD-MXN。 |
side | 你在美元這一邊的方向。buy 表示到期時買入美元、賣出當地貨幣，美元走強時獲利；sell 則相反。 |
notional | 美元金額，1,000 – 50,000,000。 |
maturity | 定價日，格式 YYYY-MM-DD，T+1 起到兩年內任一營業日，沒有固定天期。定盤時間為 15:00 UTC，交割日為定價日後 2 個營業日。 |
rate | 每 1 美元兌當地貨幣數。vsMidBps 是報價與遠期中價的距離，也就是這筆報價的全部成本。 |
| 結算損益 | 以買入為例：notional × (F − K) / F，折現後以 USDC 支付。F 為目前遠期匯率（到期時為定盤匯率），K 為合約匯率。 |
交易生命週期
價格發現在鏈下，結算在鏈上。流程採用以交易意圖為基礎的 RFQ 模式：參考報價 → 你的簽署 → 獨家成交方的確定報價 → 成交；若得標者未履約，則轉由備援成交。
| # | 步驟 | 內容 |
|---|---|---|
| 1 | POST /rfqs | 詢價送給所有交易商。這是密封、最佳價成交的競價：交易商彼此看不到報價。 |
| 2 | 競價時限 | 每家交易商須在 responseDeadlineMs（2,500 毫秒）內回覆報價（live）或明確的 no_quote（在線但婉拒）。未回應者標記為 timeout。報價有效 15 秒。 |
| 3 | POST /rfqs/{id}/accept | 你簽署帶有 limitRate（報價 ± maxSlippageBps）的交易意圖，所選交易商取得確認成交的獨家權利。 |
| 4 | 確定報價／最後確認 | 若行情對得標者不利，它可能反悔，這就是「免費選擇權」問題，並會記在該交易商的紀錄上。交易意圖接著依價格順序轉給其餘報價，只在你的限價內成交。 |
| 5 | 成交 | 建立遠期合約、鎖定原始保證金，並以 UTI 申報交易。 |
| 6 | 持續結算 | 每 10 秒將評價變動以 USDC 作為變動保證金入帳。 |
| 7 | 平倉或到期 | POST /trades/{id}/close 以交易商的買賣價提前平倉；到期定盤時結算最終差額並釋放保證金。 |
錯誤
錯誤會回傳非 2xx 狀態碼，並附上固定、可供程式判讀的錯誤代碼：
{ "error": { "code": "insufficient_collateral", "message": "initial margin 46759.32 USDC exceeds free collateral …" } }
| 狀態碼 | 錯誤代碼 |
|---|---|
| 400 | invalid_json unknown_pair invalid_side invalid_notional invalid_maturity invalid_slippage invalid_amount invalid_address invalid_network |
| 401 | unauthorized |
| 404 | not_found quote_not_found |
| 409 | rfq_closed quote_not_live trade_not_active |
| 422 | insufficient_collateral |
冪等性
任何 POST 都可附上 Idempotency-Key 標頭。以相同金鑰重試會回傳原本的回應，不會重複建立詢價、成交或提領。每個帳戶保留最近 200 筆。