帳戶端點¶

取得餘額¶

取得帳戶的錢包和 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..."
}