跳轉至

快速開始

網路與相容性

資源 值
API 基礎 URL https://api.sera.cx/api/v1
鏈 Ethereum 主網（chainId 1）
Sera 合約 0xB5C50C5D5f038404F85970b7f5B7259C4AC0E198
Vault 合約 0xC7d4Fd2638e6630C8C61329878676b88A8A24D43
SOR 合約 0xa7A0cf7cd6f043fCA23f29d8ae5aae6b46e11c18

簽名原語。 所有交易型變更都是針對 Sera domain 的 EIP-712 類型化資料簽名。走 permit 路徑的充值使用 ERC-2612 Permit 擴充功能 — USDC、EURC 以及許多現代穩定幣支援，但並非所有 ERC-20 都支援；簽名前請呼叫 GET /permit/metadata 檢查。API key 管理使用 EIP-712 ManageApiKey payload。

已驗證客戶端。 Python eth_account >= 0.10 + requests；TypeScript ethers v6（signer.signTypedData）。已驗證支援 EIP-712 類型化資料的瀏覽器錢包：MetaMask、Rabby、Frame、Coinbase Wallet、Trust、Rainbow。Safe 多簽透過 EIP-1271 支援（訊息於鏈上驗證，而非透過 ecrecover）。

地址大小寫。 讀取類端點（/balances、/orders、/fills）將 owner_address 視為大小寫敏感 — 請傳入小寫形式。EIP-712 簽名 payload 接受 EIP-55 校驗和地址。

本指南將帶您完成與 Sera 的首次互動 — 從查詢可用代幣到執行您的第一筆兌換。

前置條件

  • 一個 Ethereum 錢包（例如 MetaMask）
  • 用於充值、提取和限價單結算的 Ethereum 主網 ETH（僅兌換流程不需要 ETH）。

步驟一：瀏覽可用代幣

查詢代幣登錄表以查看可用的穩定幣：

curl https://api.sera.cx/api/v1/tokens

import requests

response = requests.get("https://api.sera.cx/api/v1/tokens")
tokens = response.json()["tokens"]
print(tokens)

const response = await fetch("https://api.sera.cx/api/v1/tokens");
const { tokens } = await response.json();
console.log(tokens);

步驟二：取得兌換報價

取得兩種代幣之間的兌換報價：

curl -X POST https://api.sera.cx/api/v1/swap/quote \
  -H "Content-Type: application/json" \
  -d '{
    "from_token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "to_token": "0x1aBaEA1f7C830bD89Acc67eC4af516284b1bC33c",
    "from_amount": "1000000000",
    "owner_address": "0xYOUR_ADDRESS",
    "recipient": "0xYOUR_ADDRESS",
    "expiration": 1735689600,
    "gas_mode": "receive_less"
  }'

import time, requests

quote = requests.post(
    "https://api.sera.cx/api/v1/swap/quote",
    json={
        "from_token":     "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",  # USDC
        "to_token":       "0x1aBaEA1f7C830bD89Acc67eC4af516284b1bC33c",  # EURC
        "from_amount":    "1000000000",                                  # 1000 USDC（6 位小數）
        "owner_address":  "0xYOUR_ADDRESS",
        "recipient":      "0xYOUR_ADDRESS",
        "expiration":     int(time.time()) + 3600,
        "gas_mode":       "receive_less",
    },
    timeout=10,
).json()
print(quote)

const response = await fetch("https://api.sera.cx/api/v1/swap/quote", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    from_token:    "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",   // USDC
    to_token:      "0x1aBaEA1f7C830bD89Acc67eC4af516284b1bC33c",   // EURC
    from_amount:   "1000000000",                                    // 1000 USDC（6 位小數）
    owner_address: "0xYOUR_ADDRESS",
    recipient:     "0xYOUR_ADDRESS",
    expiration:    Math.floor(Date.now() / 1000) + 3600,
    gas_mode:      "receive_less",
  }),
});
const quote = await response.json();
console.log(quote);

回應中包含 uuid 與 route_params — 這些是您將以錢包簽名的參數。

步驟三：簽名並執行兌換

使用 EIP-712 typed-data 簽名簽署 route_params，然後提交：

from eth_account import Account
from eth_account.messages import encode_typed_data

# `domain` 與 `INTENT_TYPES` 在 身份驗證 頁面有記載
signable  = encode_typed_data(domain, INTENT_TYPES, quote["route_params"])
signature = Account.from_key(PRIVATE_KEY).sign_message(signable).signature.hex()

submit = requests.post(
    "https://api.sera.cx/api/v1/swap",
    json={"uuid": quote["uuid"], "signature": "0x" + signature.lstrip("0x")},
    timeout=10,
).json()

// `domain` 與 `INTENT_TYPES` 在 身份驗證 頁面有記載
const signature = await signer.signTypedData(domain, INTENT_TYPES, quote.route_params);

const result = await fetch("https://api.sera.cx/api/v1/swap", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ uuid: quote.uuid, signature }),
});

報價是一次性的。若報價被消費之後提交失敗，請改為請求新的報價，不要以同一個 uuid 重試。

詳細簽名說明請參閱 身份驗證。

步驟四：檢查您的餘額

建立 API Key 以查詢您的餘額與訂單歷史。/balances 端點會同時回傳您的錢包餘額（錢包中的代幣）與 Vault 餘額（用於限價單交易的已充值代幣），以及任何被掛單凍結的部分。

balances = requests.get(
    "https://api.sera.cx/api/v1/balances",
    params={"owner_address": "0xYOUR_ADDRESS"},
    headers={"Authorization": "Bearer YOUR_API_KEY:YOUR_API_SECRET"},
    timeout=10,
).json()["balances"]

for bal in balances:
    print(f"{bal['symbol']}:")
    print(f"  錢包:           {bal['wallet_balance']}")
    print(f"  Vault 可用: {bal['vault_available']}")
    print(f"  Vault 凍結: {bal['vault_frozen']}")

const response = await fetch(
  "https://api.sera.cx/api/v1/balances?owner_address=0xYOUR_ADDRESS",
  { headers: { "Authorization": "Bearer YOUR_API_KEY:YOUR_API_SECRET" } },
);
const { balances } = await response.json();

for (const bal of balances) {
  console.log(`${bal.symbol}:`);
  console.log(`  錢包:           ${bal.wallet_balance}`);
  console.log(`  Vault 可用: ${bal.vault_available}`);
  console.log(`  Vault 凍結: ${bal.vault_frozen}`);
}

使用網頁應用

您也可以直接透過 Sera 網頁介面進行交易：

  1. 造訪 app.sera.cx
  2. 連接您的錢包
  3. 選擇貨幣對
  4. 下限價單或執行即時兌換
  5. 在儀表板中監控您的訂單

下一步