身份验证¶

Sera 使用两种身份验证模式：

API Key：用于账户读取接口和交易构建辅助接口。
EIP-712 签名：用于交易、取消、提款和 API Key 管理。

实际使用中，公共工具类端点包括：

GET /health、GET /system/time、GET /tokens、GET /markets 和 GET /config
POST /swap/quote 与 POST /verify-signature

需要 API Key 的读取与构建类端点包括：

GET /orders、GET /orders/{order_id}、GET /fills、GET /fills/{order_id} 与 GET /balances
GET /permit/metadata
各类交易构建端点，例如 POST /approve、POST /deposit、POST /tx/send、POST /transfer 和 POST /transfer/send

API Key¶

API Key 是只读凭证，格式如下：

Authorization: Bearer {api_key}:{api_secret}

端点摘要：

方法	路径	签名位置
`POST`	`/api-keys`	请求体中的 EIP-712 载荷（`action=create`）
`GET` 或 `POST`	`/api-keys` 或 `/api-keys/list`	查询参数或请求体中的 EIP-712 载荷（`action=list`）
`DELETE` 或 `POST`	`/api-keys` 或 `/api-keys/revoke`	查询参数或请求体中的 EIP-712 载荷（`action=revoke_<api_key>`）
`POST`	`/api-keys/revoke-all`	请求体中的 EIP-712 载荷（`action=revoke_all`）
`POST`	`/api-keys/self-revoke`	使用待撤销 Key 自身的 Bearer 凭据
`POST`	`/api-keys/verify`	无（待验证的 Key 在请求体中）

创建 API Key¶

API Key 通过签署 EIP-712 ManageApiKey 消息来创建。

const domain = {
  name: 'Sera',
  version: '1',
  chainId: 11155111,
  verifyingContract: '0xd0fc92d8eF9bE26D7288fCa1D6458f675e72B83a'
};

const types = {
  ManageApiKey: [
    { name: 'owner', type: 'address' },
    { name: 'action', type: 'string' },
    { name: 'timestamp', type: 'uint256' }
  ]
};

const timestamp = Math.floor(Date.now() / 1000);
const signature = await signer.signTypedData(domain, types, {
  owner: walletAddress,
  action: 'create',
  timestamp
});

const response = await fetch('https://api.sera.cx/api/v1/api-keys', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    owner_address: walletAddress,
    action: 'create',
    timestamp,
    signature,
    label: 'Trading bot'
  })
});

const { api_key, api_secret } = await response.json();

说明：

签名中的时间戳必须在服务器时间前后 5 分钟内。
一个钱包最多可同时拥有 10 个活跃 API Key。
api_secret 只会返回一次，必须自行安全保存。

列出 API Key¶

const timestamp = Math.floor(Date.now() / 1000);
const signature = await signer.signTypedData(domain, types, {
  owner: walletAddress,
  action: 'list',
  timestamp
});

const url = new URL('https://api.sera.cx/api/v1/api-keys');
url.searchParams.set('owner_address', walletAddress);
url.searchParams.set('action', 'list');
url.searchParams.set('timestamp', String(timestamp));
url.searchParams.set('signature', signature);

const keys = await fetch(url).then(r => r.json());

如果客户端更适合使用 JSON 请求体而不是签名查询参数，也可以调用 POST /api-keys/list，并在请求体中提交同样的 owner_address、action、timestamp 和 signature 字段。

撤销 API Key¶

const action = `revoke_${apiKeyToRevoke}`;
const timestamp = Math.floor(Date.now() / 1000);
const signature = await signer.signTypedData(domain, types, {
  owner: walletAddress,
  action,
  timestamp
});

const url = new URL('https://api.sera.cx/api/v1/api-keys');
url.searchParams.set('owner_address', walletAddress);
url.searchParams.set('api_key', apiKeyToRevoke);
url.searchParams.set('action', action);
url.searchParams.set('timestamp', String(timestamp));
url.searchParams.set('signature', signature);

await fetch(url, { method: 'DELETE' });

如果客户端更适合使用 JSON 请求体而不是签名查询参数，也可以调用 POST /api-keys/revoke，并在请求体中提交相同字段以及 api_key。

批量撤销所有 API Key¶

通过一次签名撤销该钱包下所有有效的 API Key。action 是固定字符串 revoke_all。适合在凭据疑似泄漏、设备丢失或钱包轮换流程中使用 — 一次钱包弹窗代替 N 次签名。

const timestamp = Math.floor(Date.now() / 1000);
const signature = await signer.signTypedData(domain, types, {
  owner: walletAddress,
  action: 'revoke_all',
  timestamp
});

const res = await fetch('https://api.sera.cx/api/v1/api-keys/revoke-all', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    owner_address: walletAddress,
    action: 'revoke_all',
    timestamp,
    signature
  })
});

// 200: { "status": "ok", "revoked_api_keys": ["sera_...", "sera_..."], "count": 2 }
// 200: { "status": "ok", "revoked_api_keys": [], "count": 0 }   // 无有效 Key
// 409: 签名重放（已使用过）— 用新的 timestamp 重新签名

自撤销（Bearer 鉴权）¶

无需钱包签名即可撤销当前正在使用的 API Key。使用 Authorization: Bearer {api_key}:{api_secret} 鉴权；请求体中的 api_key 必须等于 Bearer 中的 api_key（只能撤销自己当前登录使用的 Key — 撤销同一钱包下的其它 Key 仍需用 DELETE /api-keys 加钱包签名）。

await fetch('https://api.sera.cx/api/v1/api-keys/self-revoke', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${apiKey}:${apiSecret}`
  },
  body: JSON.stringify({ api_key: apiKey })
});

验证 API Key¶

校验 api_key/api_secret 对是否有效，且不消耗速率限制、不产生副作用。成功时返回所属钱包地址。

const res = await fetch('https://api.sera.cx/api/v1/api-keys/verify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ api_key: apiKey, api_secret: apiSecret })
});

// 200: { "valid": true, "owner_address": "0x..." }
// 401: { "detail": "Invalid api_key or api_secret" }
// 503: { "detail": "Service temporarily unavailable; please retry" }（鉴权后端不可达）

EIP-712 域¶

公共 API 按 Sepolia 上的 Sera 合约域来验证签名：

const domain = {
  name: 'Sera',
  version: '1',
  chainId: 11155111,
  verifyingContract: '0xd0fc92d8eF9bE26D7288fCa1D6458f675e72B83a'
};

请通过 GET /config 获取当前部署的 chain_id、sera_address、vault_address 和 sor_address，不要把这些值硬编码在客户端中。

过期时间规则¶

所有已签名订单请求都必须带 expiration，而兑换报价请求也使用同一套有界未来时间戳来生成后续签名 Intent。

expiration 必须严格大于当前时间。
expiration 最多只能比当前服务器时间晚 365 天减去 300 秒的时钟偏差保护。
缺失、为 0、已过期或过远的值都会在进入撮合或结算前直接被拒绝。

请使用 GET /system/time 推导这些时间戳，并预留一点客户端缓冲，不要卡在边界时间上签名。

订单请求中的 UUID 绑定¶

限价单现在同时携带两个关联标识符：

order_id：人类可读的 UUID4 字符串。
uuid_int：嵌入链上签名 Order.uuid 字段中的十进制 uint256。

API 会校验这两个标识符是否编码的是同一个订单。请先从 GET /health 读取当前 executor_id，然后按照下面的组合布局生成 uuid_int：

[255:252] executor_id | [251:124] full UUID4 bits | [123:12] group_id | [11:0] leg_id

独立限价单¶

普通限价单的规则：

leg_id = 0
group_id = order_id 的前 112 位

function uuidStringToBigInt(uuid) {
  return BigInt(`0x${uuid.replace(/-/g, '')}`);
}

function encodeStandaloneUuid(orderId, executorId) {
  const raw = uuidStringToBigInt(orderId);
  const group = raw >> 16n;
  return ((BigInt(executorId) << 252n) | (raw << 124n) | (group << 12n)).toString();
}

有效示例：

{
  "order_id": "00000000-0000-4000-8000-000000000001",
  "uuid_int": "6427948336465191935941739505432058208337171677044006212075520"
}

虚拟流动性批次¶

对于 VL 批次：

所有同组订单共享同一个 group_id
group_id 来自 order 0
leg_id 依次为 0, 1, 2, ...

function encodeVlUuid(orderId, executorId, legId, groupOrderId) {
  const raw = uuidStringToBigInt(orderId);
  const group = uuidStringToBigInt(groupOrderId) >> 16n;
  return ((BigInt(executorId) << 252n) | (raw << 124n) | (group << 12n) | BigInt(legId)).toString();
}

订单签名¶

链上签名的 Order 结构如下：

const types = {
  Order: [
    { name: 'user', type: 'address' },
    { name: 'expiration', type: 'uint48' },
    { name: 'feeBps', type: 'uint48' },
    { name: 'recipient', type: 'address' },
    { name: 'fromToken', type: 'address' },
    { name: 'toToken', type: 'address' },
    { name: 'fromAmount', type: 'uint256' },
    { name: 'toAmount', type: 'uint256' },
    { name: 'initialDepositAmount', type: 'uint256' },
    { name: 'uuid', type: 'uint256' }
  ]
};

在 POST /orders 请求中，使用交易对身份字段，而不是直接的“支出/接收”字段：

from_address 是市场的基础代币地址。
to_address 是市场的报价代币地址。
bid 用 to_address 买入 from_address。
ask 卖出 from_address，换取 to_address。

这些地址请通过 GET /tokens 获取，展示用交易对标签请通过 GET /markets 获取。

示例：

const orderData = {
  user: walletAddress,
  expiration: Math.floor(Date.now() / 1000) + 86400,
  feeBps: 0,
  recipient: ethers.ZeroAddress,
  fromToken: '0x...',
  toToken: '0x...',
  fromAmount: '1085000000',
  toAmount: '1000000000',
  initialDepositAmount: 0,
  uuid: BigInt(uuidInt)
};

const signature = await signer.signTypedData(domain, types, orderData);

兑换的 Intent 签名¶

POST /swap/quote 会返回 route_params。请按返回结果原样签名。

const types = {
  Intent: [
    { name: 'taker', type: 'address' },
    { name: 'inputToken', type: 'address' },
    { name: 'outputToken', type: 'address' },
    { name: 'maxInputAmount', type: 'uint256' },
    { name: 'minOutputAmount', type: 'uint256' },
    { name: 'recipient', type: 'address' },
    { name: 'initialDepositAmount', type: 'uint256' },
    { name: 'uuid', type: 'uint256' },
    { name: 'deadline', type: 'uint48' }
  ]
};

const signature = await signer.signTypedData(domain, types, quote.route_params);

取消签名¶

CancelOrder¶

CancelOrder.orderId 使用的是组合 uuid_int，不是 UUID 字符串。

const types = {
  CancelOrder: [
    { name: 'owner', type: 'address' },
    { name: 'orderId', type: 'uint256' }
  ]
};

const signature = await signer.signTypedData(domain, types, {
  owner: walletAddress,
  orderId: BigInt(uuidInt)
});

CancelVLBatch¶

const types = {
  CancelVLBatch: [
    { name: 'owner', type: 'address' },
    { name: 'vlBatchId', type: 'string' }
  ]
};

提款签名¶

const types = {
  WithdrawIntent: [
    { name: 'user', type: 'address' },
    { name: 'tokens', type: 'address[]' },
    { name: 'amounts', type: 'uint256[]' },
    { name: 'recipient', type: 'address' },
    { name: 'deadline', type: 'uint256' },
    { name: 'uuid', type: 'uint256' }
  ]
};

提交前验证签名¶

const response = await fetch('https://api.sera.cx/api/v1/verify-signature', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    owner_address: walletAddress,
    side: 'bid',
    amount: '1000.0',
    price: '1.085',
    from_address: EURC_ADDRESS,
    to_address: USDC_ADDRESS,
    order_id: '00000000-0000-4000-8000-000000000001',
    uuid_int: '6427948336465191935941739505432058208337171677044006212075520',
    signature,
    expiration: Math.floor(Date.now() / 1000) + 86400
  })
});

时钟同步¶

请使用 GET /system/time 计算 expiration 和 deadline，使用 GET /health 读取生成 uuid_int 所需的最新 executor_id，并使用 GET /config 获取最新的 EIP-712 合约地址。