概覽
這個Solana 單頁應用程式是基於Titan Meta-Aggregation API 建構的，並透過Quicknode RPC 提供服務。此應用程式展示了 Titan Meta-Aggregation API 的獨特之處：多個供應商競相提供最佳路徑、路徑所經過的鏈上交易場所，以及您從頭到尾自主掌控的「建構 → 簽署 → 發送」flow 流程。
有關 Titan Meta-Aggregation API 整合的詳細操作指南，請參閱配套指南：《如何使用 Titan Meta-Aggregation API 交換代幣》。
Titan Gateway 僅可在Solana mainnet。執行兌換將以真實代幣進行交易，並產生實際的網路手續費。您可能因價格波動、滑點或選擇錯誤的代幣對而導致資產價值損失。請先以小額資金進行測試。
建築
這兩組憑證均保留在伺服器上。瀏覽器程式碼會與本機的 Next.js 路由處理器進行通訊： /api/titan/* 呼叫 Gateway（解碼 MessagePack 並將公鑰正規化），以及 /api/rpc 代理Solana 透過 JSON-RPC 連線至Quicknode endpoint 。無論是閘道器 (Gateway) 的驗證資訊，還是 RPC 憑證，都從未傳送至客戶端。
瀏覽器 ──> /api/titan/* ──> Titan Gateway（MessagePack 解碼，僅限伺服器端）
└─> /api/rpc ──>Quicknode Solana RPC（僅限伺服器端的憑證）
由於 RPC 代理僅支援 HTTP JSON-RPC（不支援 WebSocket），因此該應用程式透過輪詢來確認交易 getSignatureStatuses 而非透過簽名訂閱。
特色
- 供應商競標：Titan 從多個供應商處取得報價（包括其自有的 DART 路由器，以及其他匯集平台和詢價平台）。使用者介面會並列顯示所有競爭報價，並標示各報價相較於領先者落後多少個基點，以及 Titan 預估哪一方將勝出。
- 可組合指令：Titan 返回的是指令與位址查閱表，而非密封交易。應用程式會自行建構 v0 交易，由錢包進行簽署，並透過Quicknode RPC 提交及確認。
- 「精準」與「快速」: 一個對應於泰坦的切換開關
模擬參數，結果旁邊會顯示往返延遲。 - 價格與掉期終點的比較: 一個未連線的錢包使用輕量級
/報價/價格endpoint 以參考匯率為例；已連線的錢包會使用/quote/swap如需完整的提供者競逐機制及可執行指令，請參閱。
先決條件
- Node.js（v24 或更高版本）
- A Quicknode Solana endpoint
- 透過 Titan存取Quicknode 的 Swap API
- 一個具備mainnet 存取權限的Solana 錢包（Phantom 或 Solflare）
- 少量mainnet SOL作為交易手續費
- 少量代幣可供兌換（建議使用 USDC 進行測試）
要取得您的Quicknode RPC URL：
- 請於以下連結註冊： Quicknode
- 建立一個新的Solana endpoint
- 啟用 Titan DeFi 元聚合 REST API
- 複製Solana endpoint 的 URL 以及 Meta-Aggregation API 的 URL
專案架構
titan-swap/
├── app/
│ ├── api/titan/ # 伺服器代理：info、providers、venues、price、swap
│ ├── api/rpc/ # 伺服器代理：Solana JSON-RPC（隱藏Quicknode 代幣）
│ ├── layout.tsx
│ ├── page.tsx # 主要交換介面
│ ├── globals.css # Tailwind v4 +Quicknode 深色設計代碼
│ └── providers/WalletProvider.tsx
├── components/
│ ├── ProviderRace.tsx # 競爭提供者視覺化
│ ├── VenueSplit.tsx # 獲勝路徑所經過的場館
│ ├── SimulationToggle.tsx # 精確模式 vs. 快速模式（模擬參數）
│ ├── SlippageControl.tsx
│ ├── TokenInput.tsx / TokenSelector.tsx / SwapButton.tsx / StatusMessage.tsx
│ └── SwapCard.tsx / WalletButton.tsx
├── hooks/
│ ├── useQuote.ts # /quote/swap（已連線）或 /quote/price
│ ├── useSwap.ts # 建構 → 簽署 → 傳送 → 確認
│ ├── useTokenBalances.ts # 透過Quicknode RPC 查詢餘額
│ ├── useTokenList.ts
│ └── useTitanMeta.ts # 服務提供者 / 交易場所 / 資訊
└── lib/
├── titan-server.ts # 僅限伺服器的 Gateway 客戶端（MessagePack）
├── titan.ts # 用於 /api/titan/* 的客戶端擷取程式
├── build-swap-tx.ts # 指令 + ALTs → VersionedTransaction
├── tokens.ts # 代幣元數據註冊表
└── types.ts
環境變數
複製 .env.local.example 至 .env.local 並填入數值。這兩個 URL 皆僅供伺服器使用，絕不會對瀏覽器公開：
# https://your-endpoint.solana-mainnet.quiknode.pro/YOUR_TOKEN/
QUICKNODE_RPC_URL=您的_QuickNode_Solana_RPC_網址
TITAN_GATEWAY_URL=您的_Titan_Gateway_附加元件_網址
# TITAN_GATEWAY_AUTH=可選的 Bearer 憑證
| 變數 | 說明 |
|---|---|
QUICKNODE_RPC_URL | 您的Quicknode Solana mainnet RPCendpoint URL。瀏覽器的錢包適配器會與同源 /api/rpc 代理伺服器，會將請求轉發至此網址。 |
TITAN_GATEWAY_URL | 您在Quicknode 儀表板中顯示的 Swap API 的 Titan 基礎網址。無論末尾是否帶有 /api/v1 — 代理會將其正規化。 |
TITAN_GATEWAY_AUTH | 可選的承載者憑證，僅當您的閘道 URL 尚未內嵌認證時才需使用。 |
開始使用
1. 複製儲存庫：
git clone https://github.com/quiknode-labs/qn-guide-examples.git
cd qn-guide-examples/solana/titan-swap
2. 安裝依賴項：
npm 安裝
3. 設定環境變數：
cp .env.local.example .env.local
編輯 .env.local 並加入您的Quicknode RPC URL 以及 Swap API Titan URL。
4. 執行開發伺服器：
npm 執行 dev
5. 開啟應用程式：
請在瀏覽器中瀏覽至http://localhost:3000。
API 端點
該應用程式包含以下伺服器端 API 路徑：
/api/titan/info: 返回 Titan Gateway 的元資料/api/titan/providers: 列出競逐航線的航空公司/api/titan/venues: 列出用於路由映射的鏈上場館計畫 ID/api/titan/price: 透過 Titan 提供的參考匯率/報價/價格endpoint/api/titan/swap: 透過 取得完整的提供者競逐及可執行指令/quote/swap/api/rpc: 將Solana 的 JSON-RPC 請求轉發至Quicknode
預覽
- 分叉此儲存庫
- 建立功能分支：git checkout -b feature/amazing-feature
- 將您的變更提交：git commit -m "新增超棒的功能"
- 推送您的分支：git push origin feature/amazing-feature
- 開啟一個 Pull Request。
