账户端点¶

获取余额¶

获取账户的钱包余额和 Vault 余额汇总。

GET /balances

身份验证： 需要 API Key

查询参数¶

参数	类型	必填	说明
`owner_address`	address	是	必须与已认证的 API Key 所有者匹配
`include_zero`	boolean	否	默认 `false`。`false` 时会过滤 `total` 为零的代币以保持响应有界；设为 `true` 可包含全部白名单代币。

响应¶

{
  "owner_address": "0x...",
  "balances": [
    {
      "token": "0xDcAEcdd8Db64f4316A11917Ad0162DEBD935285b",
      "symbol": "USDC",
      "decimals": 6,
      "wallet_balance": "1250000000",
      "vault_available": "400000000",
      "vault_frozen": "100000000",
      "vault_total": "500000000",
      "total": "1750000000"
    }
  ],
  "updated_at": "2026-04-15T09:12:34.567890+00:00",
  "wallet_balance_available": true
}

字段	类型	说明
`token`	address	ERC-20 合约地址
`symbol`	string	代币符号
`decimals`	integer	该代币的精度，用于把原始字符串转换成人类可读值
`wallet_balance`	string	用户钱包余额（原始 uint256 十进制字符串）
`vault_available`	string	Vault 中可用于交易的余额（原始 uint256 十进制字符串）
`vault_frozen`	string	Vault 中冻结在未结订单中的余额（原始 uint256 十进制字符串）
`vault_total`	string	`vault_available + vault_frozen`
`total`	string	`wallet_balance + vault_total`
`wallet_balance_available`	boolean	如果钱包余额 RPC 调用失败则为 `false`

所有余额字段都返回原始 uint256 十进制字符串。请结合每一行的 decimals 字段自行转换为人类可读单位。Vault 余额为权威数据，钱包余额为尽力而为。

示例¶

const response = await fetch(
  'https://api.sera.cx/api/v1/balances?owner_address=0x...',
  { headers: { 'Authorization': 'Bearer sera_key:secret' } }
);
const { balances } = await response.json();

for (const bal of balances) {
  console.log(`${bal.symbol}: available=${bal.vault_available}, frozen=${bal.vault_frozen}`);
}

充值辅助端点¶

请先通过 GET /config 获取当前的 vault_address 和 sor_address。现在充值流程使用三个辅助端点：

如不使用 permit，先调用 POST /approve 构建 ERC-20 授权交易。
调用 POST /deposit 构建 depositFund(...) 或 depositFundWithPermit(...)。
本地签名后，通过 POST /tx/send 广播授权或充值交易。

如果代币支持 EIP-2612，您可以在 POST /deposit 中直接传入 permit_signature 与 permit_deadline，从而跳过单独的授权交易。若需要在客户端探测 permit 能力，请使用 GET /permit/metadata。

构建充值交易¶

POST /deposit

身份验证： 需要 API Key

请求体¶

{
  "token": "0xDcAEcdd8Db64f4316A11917Ad0162DEBD935285b",
  "owner": "0x...",
  "amount": "1000000000",
  "permit_signature": "0x...",
  "permit_deadline": 1713254400,
  "permit_amount": "1000000000"
}

字段	类型	必填	说明
`token`	address	是	要充值的 ERC-20 代币地址
`owner`	address	是	充值人地址，必须与已认证 API Key 的所有者一致
`amount`	string	是	原始 uint256 代币数量
`permit_signature`	hex string	否	用于内联授权的 EIP-2612 permit 签名；支持标准 65 字节与紧凑 64 字节两种十六进制编码
`permit_deadline`	integer	否	permit 中签名使用的截止时间
`permit_amount`	string	否	permit 的原始授权额度；省略时默认等于 `amount`

未提供 permit 字段时，构建器会生成 depositFund(token, owner, amount)；提供 permit 字段时，会改为生成 depositFundWithPermit(...)。

响应¶

{
  "tx": {
    "to": "0xd0fc92d8eF9bE26D7288fCa1D6458f675e72B83a",
    "data": "0x...",
    "value": "0x0",
    "chainId": "0xaa36a7",
    "nonce": "0x2b",
    "gas": "0x13880",
    "type": "0x2",
    "maxFeePerGas": "0x...",
    "maxPriorityFeePerGas": "0x..."
  }
}

构建授权交易¶

POST /approve

身份验证： 需要 API Key

请求体¶

{
  "token": "0xDcAEcdd8Db64f4316A11917Ad0162DEBD935285b",
  "owner": "0x...",
  "spender": "0x5d6ffA9b9710C7Ab69105496a0fD8C48DfF40110",
  "amount": "1000000000"
}

spender 只能是 GET /config 返回的实时 Vault 或 SOR 地址；其他目标都会被拒绝。

响应¶

{
  "tx": {
    "to": "0xDcAEcdd8Db64f4316A11917Ad0162DEBD935285b",
    "data": "0x...",
    "value": "0x0",
    "chainId": "0xaa36a7",
    "nonce": "0x2a",
    "gas": "0xc350",
    "type": "0x2",
    "maxFeePerGas": "0x...",
    "maxPriorityFeePerGas": "0x..."
  }
}

广播已签名的授权或充值交易¶

POST /tx/send

身份验证： 需要 API Key

请求体¶

{
  "raw_tx": "0x..."
}

响应¶

{
  "tx_hash": "0x..."
}

POST /tx/send 只接受选择器与目标地址组合在允许列表内的已签名授权/充值交易。

对于 approve，编码后的 spender 还必须是 GET /config 返回的实时 Vault 或 SOR 地址。如果提交的是 EIP-7702 的 type-4 交易，则每个授权 delegate 都必须在当前部署的允许列表内，否则请求会被拒绝。

提款（联合签名）¶

请求服务器联合签名以进行即时提款。Sera 的智能合约要求即时提款需要两个签名 — 您的签名和服务器的签名 — 以防止未经授权的提款。这是一个三步流程：获取联合签名、构建交易、然后广播。

第一步：获取服务器联合签名¶

POST /withdraw

身份验证： EIP-712 WithdrawIntent 签名

请求体¶

{
  "intent": {
    "user": "0x...",
    "tokens": ["0xDcAEcdd8Db64f4316A11917Ad0162DEBD935285b"],
    "amounts": ["1000000000"],
    "recipient": "0x...",
    "deadline": "1704153600",
    "uuid": "123456789"
  },
  "user_signature": "0x..."
}

字段	类型	说明
`intent.user`	address	提款用户的钱包
`intent.tokens`	address[]	要提取的代币地址（1-20 个）
`intent.amounts`	string[]	每种代币的金额（原始单位）
`intent.recipient`	address	代币发送目标地址
`intent.deadline`	string	Unix 时间戳截止时间（uint256 字符串）。必须在未来，且不超过 365 天减去 300 秒的时钟漂移保护值。
`intent.uuid`	string	用于防重放的唯一标识符（uint256 字符串）
`user_signature`	string	EIP-712 WithdrawIntent 签名

tokens 和 amounts 长度必须相等，且包含 1 至 20 项；每个 amount 必须为正 uint256 字符串。

响应¶

{
  "success": true,
  "executor_signature": "0x..."
}

第二步：构建提款交易¶

POST /withdraw/build

身份验证： 可选

请求体¶

{
  "intent": {
    "user": "0x...",
    "tokens": ["0xDcAEcdd8Db64f4316A11917Ad0162DEBD935285b"],
    "amounts": ["1000000000"],
    "recipient": "0x...",
    "deadline": "1704153600",
    "uuid": "123456789"
  },
  "user_signature": "0x...",
  "executor_signature": "0x..."
}

字段	类型	说明
`intent`	object	与第一步相同的 WithdrawIntent
`user_signature`	string	您的 EIP-712 签名
`executor_signature`	string	第一步获得的服务器联合签名

响应¶

{
  "tx": {
    "to": "0x...",
    "data": "0x...",
    "value": "0x0",
    "chainId": 11155111,
    "nonce": 44,
    "gas": 150000,
    "gasPrice": "1000000000"
  }
}

第三步：广播已签名交易¶

POST /withdraw/send

身份验证： 可选

请求体¶

{
  "raw_tx": "0x..."
}

响应¶

{
  "tx_hash": "0x..."
}

POST /withdraw/send 只接受调用 executeInstantWithdrawDualSig(...) 且目标合约为来自 GET /config 的当前 Sera 合约地址的已签名交易。如果提交的是 EIP-7702 的 type-4 交易，则每个授权 delegate 都必须在当前部署的允许列表内，否则请求会被拒绝。

用钱包签署第二步的交易，然后将已签名的十六进制提交到此端点。

紧急提款¶

如果 Sera API 不可用，您可以通过智能合约直接使用两步流程提款：

在 Sera 合约上调用 emergencyWithdraw(token, amount) 以发起提款请求
等待约 24 小时（约 7200 个区块）
使用相同参数再次调用 emergencyWithdraw(token, amount) 以执行

详情请参阅 Sera.sol 合约参考。

ERC-20 转账¶

无需自己的 RPC 连接即可构建和广播 ERC-20 代币转账。仅接受 /tokens 注册表中列出的代币。

构建转账¶

POST /transfer

身份验证： 需要 API Key

请求体¶

{
  "token": "0xDcAEcdd8Db64f4316A11917Ad0162DEBD935285b",
  "to": "0x...",
  "amount": "1000000000",
  "from_address": "0x..."
}

字段	类型	必填	说明
`token`	address	是	ERC-20 代币合约地址（必须在代币注册表中）
`to`	address	是	接收者地址
`amount`	string	是	原始代币单位的金额
`from_address`	address	是	发送者钱包地址

响应¶

{
  "tx": {
    "to": "0x...",
    "data": "0x...",
    "value": "0x0",
    "chainId": 11155111,
    "nonce": 45,
    "gas": 60000,
    "gasPrice": "1000000000"
  }
}

广播转账¶

POST /transfer/send

身份验证： 需要 API Key

请求体¶

{
  "raw_tx": "0x..."
}

字段	类型	必填	说明
`raw_tx`	string	是	已签名的交易十六进制（0x 前缀）

响应¶

{
  "tx_hash": "0x..."
}