跳转至

快速开始

网络与兼容性

资源 值
API 基础 URL https://api.sera.cx/api/v1
链 以太坊主网（chainId 1）
Sera 合约 0xB5C50C5D5f038404F85970b7f5B7259C4AC0E198
Vault 合约 0xC7d4Fd2638e6630C8C61329878676b88A8A24D43
SOR 合约 0xa7A0cf7cd6f043fCA23f29d8ae5aae6b46e11c18

签名原语。 所有交易型变更都是针对 Sera 域的 EIP-712 类型化数据签名。走 permit 路径的充值使用 ERC-2612 Permit 扩展 — USDC、EURC 以及许多现代稳定币支持，但并非所有 ERC-20 都支持；签名前请调用 GET /permit/metadata 检查。API key 管理使用 EIP-712 ManageApiKey 载荷。

已验证客户端。 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 签名载荷接受 EIP-55 校验和地址。

本指南将引导您完成与 Sera 的首次交互 — 从查询可用代币到执行您的第一笔兑换。

前提条件

  • 一个以太坊钱包（例如 MetaMask）
  • 用于充值、提款和限价单结算的以太坊主网 ETH（仅兑换流程不需要 ETH）。

第 1 步：探索可用代币

查询代币注册表以查看可用的稳定币：

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);

第 2 步：获取兑换报价

获取两种代币之间的兑换报价：

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 — 这些是您将用钱包签名的参数。

第 3 步：签名并执行兑换

使用 EIP-712 类型化数据签名签署 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 重试。

详细的签名说明请参阅 身份验证。

第 4 步：检查您的余额

创建 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. 在仪表盘中监控您的订单

下一步