快速开始¶

网络与兼容性

资源	值
API 基础 URL	`https://api.testnet.sera.cx/api/v1`
链	Sepolia（chainId `11155111`）
Sera 合约	`0x83475A1bD98a8DC2DCd507A747e4DC85da241D6e`
Vault 合约	`0x3c7945840bAE0d7e7f3824Ebccef1962629250F0`
SOR 合约	`0x83c1368110B640A729f3810De5FBe94b99aa5668`

签名原语。 所有交易型变更都是针对 Sera 域的 EIP-712 类型化数据签名。走 permit 路径的充值使用 ERC-2612 Permit 扩展 — USDC、EURC、EURT 以及多数现代稳定币支持，但并非所有 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 用于支付 Gas 费用（使用 Sepolia 水龙头）
用于交易的测试网稳定币 — 注册表中的所有代币（USDC、EURC、GBPA、XSGD …）都可以从 Sera 测试网水龙头免费领取（详见下方）。

Sera 测试网代币水龙头

测试网代币注册表中的每种稳定币都可以从 Sepolia 上的 Sera 水龙头合约免费铸造：

水龙头： 0x4FAc3BB8B77547E2Da7ed903baDBeD2f46cBe65a

在 testnet.sera.cx 的「领取测试代币」流程中使用，或直接调用水龙头合约并传入您想要的代币地址。若没有对应测试代币的非零余额，下方步骤都无法运行。

第 1 步：探索可用代币¶

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

cURLPythonTypeScript

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

import requests

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

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

第 2 步：获取兑换报价¶

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

cURLPythonTypeScript

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

import time, requests

quote = requests.post(
    "https://api.testnet.sera.cx/api/v1/swap/quote",
    json={
        "from_token":     "0x965d4b4546716e416e950bc30467d128455d2d0e",  # USDC
        "to_token":       "0xef64d15ed6c371545eb6dcd6c026c17dfb6c440f",  # 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.testnet.sera.cx/api/v1/swap/quote", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    from_token:    "0x965d4b4546716e416e950bc30467d128455d2d0e",   // USDC
    to_token:      "0xef64d15ed6c371545eb6dcd6c026c17dfb6c440f",   // 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，然后提交：

PythonTypeScript

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_body = {"uuid": quote["uuid"], "signature": "0x" + signature.removeprefix("0x")}
permit = quote.get("permit") or {}
if permit.get("permit_required") and permit.get("permit_supported"):
    typed = permit["eip712"]
    permit_message = encode_typed_data(typed["domain"], typed["types"], typed["message"])
    permit_signature = Account.from_key(PRIVATE_KEY).sign_message(permit_message).signature.hex()
    submit_body["permit_signature"] = "0x" + permit_signature.removeprefix("0x")
    submit_body["permit_deadline"] = int(typed["message"]["deadline"])
elif permit.get("permit_required") and int(permit["current_allowance_raw"]) < int(permit["value_raw"]):
    raise RuntimeError("Approve the quoted spender, confirm the transaction, then request a fresh quote")

submit = requests.post(
    "https://api.testnet.sera.cx/api/v1/swap",
    json=submit_body,
    timeout=10,
).json()

// `domain` 与 `INTENT_TYPES` 在 身份验证 页面有记录
const signature = await signer.signTypedData(domain, INTENT_TYPES, quote.route_params);

const submitBody: { uuid: string; signature: string; permit_signature?: string; permit_deadline?: number } = {
  uuid: quote.uuid, signature,
};
const permit = quote.permit;
if (permit?.permit_required && permit.permit_supported) {
  const typed = permit.eip712;
  submitBody.permit_signature = await signer.signTypedData(typed.domain, typed.types, typed.message);
  submitBody.permit_deadline = Number(typed.message.deadline);
} else if (permit?.permit_required && BigInt(permit.current_allowance_raw) < BigInt(permit.value_raw)) {
  throw new Error("Approve the quoted spender, confirm the transaction, then request a fresh quote");
}

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

一个报价授权一次执行。请保存报价 uuid 与完整签名请求。超时或 503 导致响应未知时，重试完全相同的请求以恢复已保存结果。POST /swap 返回 trade_id 后，携带 API Key 查询 GET /orders/{trade_id}。报价 uuid 与结果中的 trade_id 是不同标识，不能用报价 ID 查询订单。首笔结果未知时不要创建第二笔兑换。

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

第 4 步：检查您的余额¶

创建 API Key 以查询您的余额和订单历史。/balances 端点同时返回您的钱包余额（钱包中的代币）与 Vault 余额（用于限价单交易的已充值代币），以及任何被挂单冻结的部分。

余额中的 vault_available 是账务金额，不保证可花。请检查 vault_spendable 与恢复字段，包括零余额的恢复记录。提供充值、即时提款或余额同步前读取 /config 能力。可用时使用余额同步，不要为余额更新延迟重复充值。

PythonTypeScript

balances = requests.get(
    "https://api.testnet.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.get('vault_spendable')} ({bal.get('spendability_status')})")
    print(f"  Vault 冻结: {bal['vault_frozen']}")

const response = await fetch(
  "https://api.testnet.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_spendable} (${bal.spendability_status})`);
  console.log(`  Vault 冻结: ${bal.vault_frozen}`);
}

使用网页应用¶

您也可以直接通过 Sera 网页界面进行交易：

访问 testnet.sera.cx
连接您的钱包
选择货币对
下限价单或执行即时兑换
在仪表盘中监控您的订单

下一步¶

做市商指南 — 程序化下单与撤单的端到端教程
核心概念 — 了解订单类型、生命周期和费用
API 参考 — 完整 API 文档
订单类型 — 了解限价单、兑换等

不支持 permit 的代币额度不足时，请使用授权与交易广播，等待确认后重新报价，再执行签名步骤。按目标输出金额兑换请使用 Exact Output 流程。

普通 Swap 重试请保留完整签名请求，并遵循提交身份与重试。相同请求成功重试可返回原结果。