概覽
此範例應用程式展示了Quicknode 所採用的x402 協定，該協定用於實現按請求付費的區塊鏈 API 存取。x402 協定可讓API 呼叫實現無縫的微支付——每項請求皆透過 EVM 簽名進行支付，從而無需使用傳統的 API 金鑰或訂閱方案。
連接您的錢包，透過「Ethereum 登入」（SIWE）進行驗證，並向水龍頭申請testnet 的 USDC。當您執行區塊鏈方法時，若信用點數不足，應用程式將自動使用您的testnet USDC 購買測試信用點數。您可在多個網路中執行 RPC/REST 方法，包括Ethereum 、Base Sepolia、Arbitrum 、Polygon 以及Aptos 。
建築
錢包 ──► SIWE 驗證 ──► JWT 憑證
│
▼
x402 Fetch 封裝程式（JWT + EVM 支付簽名）
│
▼
Quicknode x402 API ──► 區塊鏈 RPC / REST
每個 API 請求都會被 @x402/fetch，該功能會透過您已連線的錢包自動簽署付款授權。x402 後端會驗證簽名、扣除代幣，並將請求轉發至目標區塊鏈網路。
特色
- 透過 ConnectKit連接錢包（MetaMask、Coinbase Smart Wallet 等）
- 透過 SIWE 驗證以取得會話 JWT
- Testnet Base Sepolia 上的USDC 贈幣活動— 當需要時，系統會自動使用 的 USDC 進行購買testnet
- 橫跨Ethereum 、Base 、Sepolia、Arbitrum 、Polygon 及Aptos
- 每次回應中皆會附帶「付款元資料檢查」結果
- 支援JSON-RPC、REST、gRPC-Web 及 WebSocket方法
支援的方法
由於支援所有 JSON-RPC、REST、gRPC-Web 以及 WebSocket 方法，您可以呼叫目標網路上的任何可用方法。為便於示範，此應用程式內建了常用方法的按鈕：
| 方法 | 議程 | 網路 |
|---|---|---|
eth_blockNumber | JSON-RPC | Base Sepolia，Arbitrum ，Polygon |
eth_gasPrice | JSON-RPC | Base |
eth_chainId | JSON-RPC | Ethereum |
| 帳本資訊 | REST | Aptos |
| 依高度分區 | REST | Aptos |
先決條件
專案架構
src/
├── app/ # Next.js 應用程式路由器（頁面與佈局）
├── components/
│ ├── providers.tsx # Wagmi + React Query + ConnectKit 提供者
│ └── wallet-connection-shell.tsx
├── hooks/
│ ├── use-x402-auth.ts # SIWE 驗證狀態
│ ├── use-credits.ts # 信用餘額擷取
│ └── use-x402-fetch.ts # 經認證的資料擷取封裝函式
└── lib/
├── constants.ts #x402 URL、鏈 ID、合約地址
├── methods.ts # 可用 RPC/REST 方法定義
├── types.ts # TypeScript 類型
└──x402.ts # 核心x402 邏輯（認證、信用點數、執行）
環境變數
| 變數 | 預設 | 說明 |
|---|---|---|
NEXT_PUBLIC_X402_BASE_URL | https://x402.quicknode.com/ | x402 API 基礎網址 |
建立一個 .env.local 需覆寫的檔案，但預設值指向公開的x402 endpoint ，您無需任何設定即可使用該連結進行測試。
NEXT_PUBLIC_X402_BASE_URL=https://x402.quicknode.com/
開始使用
1. 複製儲存庫
git clone https://github.com/quiknode-labs/qn-guide-examples.git
cd qn-guide-examples/sample-dapps/x402-quicknode
2. 安裝依賴項
pnpm 安裝
3. 啟動開發伺服器
pnpm 開發
請在瀏覽器中開啟http://localhost:3000。連接您的錢包、透過 SIWE 進行驗證、向水龍頭申請testnet USDC，並開始進行「按次付費」的 API 呼叫——系統會在需要時自動使用您的testnet USDC 購買信用額度。
預覽
貢獻與回饋
我們非常樂意聽取您的意見，並歡迎您為這個範例應用程式提供任何貢獻！
若要回報問題或提供意見回饋，請在 qn-guide-examples 儲存庫。
若要貢獻，請依照以下步驟操作：
- 分叉此儲存庫
- 建立功能分支：git checkout -b feature/amazing-feature
- 將您的變更提交：git commit -m "新增超棒的功能"
- 推送您的分支：git push origin feature/amazing-feature
- 開啟一個 Pull Request。
