快速開始
5 分鐘完成接入
接入步驟
- 1取得 API Key — 前往 申請頁面 提交申請（需提供金庫帳號 Email，見「平台劃轉 API」章節），審核通過後取得
- 2後端換取 Token — 呼叫
/api/widget/token，每次開啟 Widget 前換取 - 3前端引入 SDK —
<script src="https://stellabit.cc/sdk.js">，然後呼叫Stellabit.open()
安裝 SDK
在頁面 <head> 或 <body> 底部引入：
<script src="https://stellabit.cc/sdk.js"></script>SDK 載入後自動掛載全域物件 Stellabit，無需額外初始化。
取得 Token
每次用戶要開啟 Widget 前，需由後端呼叫此 API 換取代表該用戶身份的短期 JWT Token（有效期 1 小時），再傳給前端使用。 不可在前端直接呼叫（會暴露 API Key）。
POST https://stellabit.cc/api/widget/token
x-api-key: {您的 API Key}
Content-Type: application/json
{
"userId": "您平台的用戶唯一 ID",
"expiresIn": 3600
}回應：
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 3600,
"widgetUrl": "https://stellabit.cc/widget/account?token=eyJ..."
}⚠️ 注意事項
- API Key 僅在後端使用，切勿暴露至前端
- Token 有效期 1 小時，建議每次開啟 Widget 前重新換取
- userId 應為您系統中該用戶的唯一識別符
OTC 兌換 (swap)
C2C 穩定幣兌換，是目前推薦的主要接入入口。swap 並非「買/賣」之外獨立的第三種功能， 而是把買入與賣出整合進同一個視窗：進入後頁面頂部會有「買入 USDT / 賣出 USDT」切換分頁（tab），用戶必須先選定買或賣，才能繼續後續流程。 底層下單 API（/api/v1/orders/topup 對應買入、/api/v1/orders/withdraw 對應賣出） 與舊版 buy/sell widget 相同， swap 是在前端把兩者合併為單一、可雙向輸入金額的 4 步流程：選買/賣 → 輸入金額 → 選幣商 → 付款 → 完成。
<button onclick="Stellabit.open('swap', token)">買幣 / 賣幣</button>流程說明
- 1進入後先選擇「買入 USDT」或「賣出 USDT」分頁
- 2用戶輸入欲換出 / 換入的金額
- 3系統列出符合條件的幣商報價
- 4用戶選擇幣商，建立訂單
- 5用戶依幣商指定方式付款
- 6幣商確認收款後交易完成
完成事件：stellabit:done
💡 關於舊版 buy / sell widget
系統內部仍保留獨立的 /widget/buy 與/widget/sell 頁面（較早期的實作，介面較簡化、無金額雙向互算）， 但本文件不建議新接入平台使用，僅作為既有整合的相容保留。新接入請一律使用 swap。
儲值 (deposit)
「儲值」是指用戶將 USDT（TRC-20）從外部錢包轉入平台帳戶。Widget 會為每位用戶生成專屬的 TRC-20 充幣地址， 用戶掃碼或複製地址後，在自己的錢包 App 發起轉帳，系統偵測到鏈上交易確認後自動入帳。
<button onclick="Stellabit.open('deposit', token)">儲值 / 充幣</button>充幣流程
- 1SDK 呼叫後，Widget 顯示用戶的專屬 TRC-20 充幣地址（含 QR Code）
- 2用戶用外部錢包掃碼或複製地址，發起鏈上轉帳
- 3系統偵測到 TRON 鏈上交易（通常 1–3 分鐘內確認）
- 4交易確認後，平台帳戶餘額自動更新
- 5Widget 顯示充幣成功，觸發
stellabit:done事件
💡 重要提示
- 僅接受 TRON TRC-20 USDT，請勿轉入其他幣種或其他鏈的資產
- 每位用戶的充幣地址是固定且唯一的
- 小額充幣（< 1 USDT）可能因礦工費問題無法到帳
完成事件：stellabit:done（用戶可監聽此事件刷新餘額顯示）
提幣 (withdraw)
用戶將平台帳戶的 USDT 提出至外部 TRC-20 錢包。需要輸入提幣地址和金額，系統扣除帳戶餘額後發起鏈上轉帳。
<button onclick="Stellabit.open('withdraw', token)">提幣</button>流程說明
- 1用戶輸入提幣地址（TRC-20）和數量
- 2確認後系統立即扣除帳戶餘額
- 3後台發起鏈上轉帳
- 4鏈上確認後提幣完成
完成事件：stellabit:done
帳戶總覽 (balance-hub)
顯示用戶的帳戶餘額，並提供餘額劃轉（平台帳戶 ↔ 交易帳戶）及內部轉帳功能。
<button onclick="Stellabit.open('balance-hub', token)">帳戶總覽</button>功能
- 查看 USDT 餘額（平台帳戶、交易帳戶）
- 劃入交易平台（to_platform）
- 平台內部轉帳給其他用戶
💡 關於「從平台轉入」（from_platform）
用戶端不提供「從平台轉入」方向。平台 → 用戶的入帳僅限您的後端以 API Key 發起， 並從平台金庫餘額即時扣款，詳見「API 參考」分頁的「平台劃轉 API」章節。
嵌入方式
| 方式 | 呼叫方式 | 適用場景 |
|---|---|---|
| Popup Modal | Stellabit.open(action, token) | 最常用，按鈕觸發，Widget 覆蓋在頁面上方 |
| iframe 嵌入 | <iframe src="https://stellabit.cc/widget/swap?token=..."> | 一體化頁面設計，Widget 嵌在頁面區塊內 |
Popup 用法
// 基本呼叫
Stellabit.open('swap', token)Stellabit.open() 目前只接受 (action, token) 兩個參數， 不支援第三個選項物件（例如主題）；若需要深色主題，請改用下方「主題設定」章節的 iframe URL 參數或 postMessage 方式。
iframe 用法
<iframe
src="https://stellabit.cc/widget/swap?token=YOUR_TOKEN&theme=light"
width="480"
height="640"
frameborder="0"
style="border-radius: 12px; box-shadow: 0 4px 24px rgba(0,0,0,0.1);"
></iframe>主題設定
主題僅支援 iframe 嵌入模式（含 Popup 內部使用的 iframe），Stellabit.open() 本身不接受主題參數。
方式一：URL 參數（載入時套用，無閃爍）
// iframe src 加上 ?theme=dark
/widget/swap?token=...&theme=dark方式二：postMessage 動態切換（適合跟隨系統主題）
iframe.contentWindow.postMessage({ type: 'stellabit:theme', theme: 'dark' }, '*')事件監聽
Widget 透過 window.postMessage 與外層頁面溝通，無論是 Popup 還是 iframe 方式均適用。
window.addEventListener('message', function(event) {
const { type, ...data } = event.data || {}
switch (type) {
case 'stellabit:done':
// 用戶完成操作（充幣成功、交易完成、提幣發出等）
// 建議：重新取得用戶餘額，更新 UI
refreshUserBalance()
break
case 'stellabit:openUrl':
// 幣商提供了支付連結（如網銀頁面）
// 由外層頁面開啟，確保 iframe 環境下也能正常工作
window.open(data.url, '_blank', 'noopener,noreferrer')
break
case 'stellabit:close':
// 用戶主動關閉 Widget（未完成操作）
break
}
})| 事件類型 | 觸發時機 | 附帶資料 |
|---|---|---|
stellabit:done | 交易或操作成功完成 | { type, action } |
stellabit:openUrl | 幣商推送支付連結 | { type, url } |
stellabit:close | 用戶關閉 Widget | { type } |