充提 API (Deposit & Withdraw)

API 版本: v1 | 基础路径: https://api.axblade.io/api/v1

---

概述

架构图

┌─────────────────────────────────────────────────────────────────┐
│                        用户客户端 (前端/APP)                      │
└─────────────────────────────────────────────────────────────────┘
                                  │
                 ┌────────────────┼────────────────┐
                 │                │                │
                 ▼                ▼                ▼
         ┌───────────┐    ┌───────────┐    ┌───────────┐
         │   认证    │    │   充值    │    │   提现    │
         │ EIP-712   │    │  链上交易  │    │ 后端签名  │
         └───────────┘    └───────────┘    └───────────┘
                 │                │                │
                 ▼                ▼                ▼
         ┌─────────────────────────────────────────────┐
         │            AXBlade 后端 API                  │
         └─────────────────────────────────────────────┘
                                  │
                                  ▼
         ┌─────────────────────────────────────────────┐
         │       AXBladeVault 智能合约                  │
         │   0xFDe43f8e6e082975d246844DEF4fE8E704403d43 │
         └─────────────────────────────────────────────┘

关键地址

名称	地址	网络
Vault 合约	0xFDe43f8e6e082975d246844DEF4fE8E704403d43	Arbitrum Sepolia
USDT 代币	0x572E474C3Cf364D085760784F938A1Aa397a8B9b	Arbitrum Sepolia
Chain ID	421614	Arbitrum Sepolia

API 接口概览

功能	方法	路径	认证
准备充值	POST	/deposit/prepare	是
充值历史	GET	/deposit/history	是
请求提现	POST	/withdraw/request	是
提现历史	GET	/withdraw/history	是
提现详情	GET	/withdraw/:id	是
取消提现	DELETE	/withdraw/:id/cancel	是
确认提现	POST	/withdraw/:id/confirm	是
余额查询	GET	/account/balances	是

---

充值流程

流程图

┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│  客户端   │────▶│ 准备充值  │────▶│ Approve  │────▶│ Deposit  │
│          │     │  API     │     │  USDT    │     │  合约    │
└──────────┘     └──────────┘     └──────────┘     └──────────┘
                                        │                │
                                        ▼                ▼
                                  ┌──────────┐     ┌──────────┐
                                  │ 链上交易  │     │ 事件监听  │
                                  │  确认    │     │ 更新余额  │
                                  └──────────┘     └──────────┘

步骤 1: 准备充值

请求:

POST /api/v1/deposit/prepare
Authorization: Bearer <token>
Content-Type: application/json

{
  "token": "USDT",
  "amount": "100.00"
}

响应:

{
  "contract_address": "0xFDe43f8e6e082975d246844DEF4fE8E704403d43",
  "token_address": "0x572E474C3Cf364D085760784F938A1Aa397a8B9b",
  "amount": "100.00",
  "estimated_gas": 100000
}

步骤 2: 授权 USDT

// 检查授权额度
const allowance = await usdtContract.allowance(userAddress, vaultAddress);

// 如果授权不足，进行授权
if (allowance < amount) {
  const approveTx = await usdtContract.approve(
    vaultAddress,
    ethers.MaxUint256  // 或具体金额
  );
  await approveTx.wait();
}

步骤 3: 调用合约充值

const vault = new ethers.Contract(vaultAddress, vaultAbi, signer);

// 充值 100 USDT (6位小数)
const amountWei = ethers.parseUnits("100", 6);
const referralCode = ethers.ZeroHash; // 无推荐码

const tx = await vault.deposit(amountWei, referralCode);
const receipt = await tx.wait();

---

提现流程

流程图

┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│  客户端   │────▶│ 请求提现  │────▶│ 获取签名  │────▶│ 调用合约  │
│          │     │  API     │     │ 后端签名  │     │ withdraw │
└──────────┘     └──────────┘     └──────────┘     └──────────┘
                      │                │                │
                      ▼                ▼                ▼
                ┌──────────┐     ┌──────────┐     ┌──────────┐
                │ 余额检查  │     │ EIP-712  │     │ 签名验证  │
                │ PnL验证  │     │  签名    │     │ 转账USDT │
                └──────────┘     └──────────┘     └──────────┘

步骤 1: 请求提现

请求:

POST /api/v1/withdraw/request
Authorization: Bearer <token>
Content-Type: application/json

{
  "token": "USDT",
  "amount": "50.00"
}

响应 (成功):

{
  "withdraw_id": "550e8400-e29b-41d4-a716-446655440000",
  "token": "0x572e474c3cf364d085760784f938a1aa397a8b9b",
  "amount": "50.00",
  "backend_signature": "0x1234...abcd",
  "nonce": 1,
  "expiry": 1703581200,
  "vault_address": "0xFDe43f8e6e082975d246844DEF4fE8E704403d43"
}

响应 (余额不足):

{
  "error": "余额不足。请求提现: 50.00, 实际可提: 30.00 (可用: 40.00, 未实现盈亏: -10.00)。原因: 2 个持仓, 未实现亏损 10.00"
}

步骤 2: 调用合约提现

const vault = new ethers.Contract(vaultAddress, vaultAbi, signer);

const tx = await vault.withdraw(
  withdrawResponse.token,           // token 地址
  ethers.parseUnits("50", 6),       // amount (USDT 6位小数)
  withdrawResponse.nonce,           // nonce
  withdrawResponse.expiry,          // deadline
  withdrawResponse.backend_signature // 后端签名
);

const receipt = await tx.wait();

步骤 3: 确认提现 (可选)

POST /api/v1/withdraw/550e8400-e29b-41d4-a716-446655440000/confirm
Authorization: Bearer <token>
Content-Type: application/json

{
  "tx_hash": "0xabc123..."
}

提现状态

状态	说明
pending	等待处理
signed	已签名，等待用户提交链上交易
submitted	用户已提交链上交易
confirmed	链上交易已确认
cancelled	已取消
failed	失败

---

历史记录查询

充值历史

GET /api/v1/deposit/history
Authorization: Bearer <token>

响应:

{
  "deposits": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "token": "USDT",
      "amount": "100.00",
      "tx_hash": "0xabc123...",
      "status": "confirmed",
      "created_at": 1703577600
    }
  ]
}

提现历史

GET /api/v1/withdraw/history
Authorization: Bearer <token>

响应:

{
  "withdrawals": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "token": "USDT",
      "amount": "50.00",
      "nonce": 1,
      "expiry": 1703581200,
      "backend_signature": "0x1234...abcd",
      "tx_hash": "0xdef456...",
      "status": "confirmed",
      "created_at": 1703578800
    }
  ]
}

余额查询

GET /api/v1/account/balances
Authorization: Bearer <token>

响应:

{
  "balances": [
    {
      "token": "USDT",
      "available": "150.00",
      "frozen": "50.00",
      "total": "200.00"
    }
  ]
}

---

EIP-712 签名规范

Domain 配置

const domain = {
  name: "AXBlade",
  version: "1",
  chainId: 421614,
  verifyingContract: "0xFDe43f8e6e082975d246844DEF4fE8E704403d43"
};

提现签名类型 (后端生成)

const withdrawTypes = {
  Withdraw: [
    { name: "user", type: "address" },
    { name: "token", type: "address" },
    { name: "amount", type: "uint256" },
    { name: "nonce", type: "uint256" },
    { name: "deadline", type: "uint256" }
  ]
};

---

合约 ABI

Vault 合约

[
  {
    "name": "deposit",
    "type": "function",
    "inputs": [
      { "name": "amount", "type": "uint256" },
      { "name": "referralCode", "type": "bytes32" }
    ]
  },
  {
    "name": "withdraw",
    "type": "function",
    "inputs": [
      { "name": "token", "type": "address" },
      { "name": "amount", "type": "uint256" },
      { "name": "nonce", "type": "uint256" },
      { "name": "deadline", "type": "uint256" },
      { "name": "signature", "type": "bytes" }
    ]
  }
]

---

错误处理

常见错误

错误	说明	解决方案
TIMESTAMP_EXPIRED	签名时间戳过期	重新获取 nonce 并签名
SIGNATURE_INVALID	签名验证失败	检查签名参数和钱包地址
INSUFFICIENT_BALANCE	余额不足	检查可用余额
WITHDRAWAL_NOT_FOUND	提现记录不存在	检查提现 ID
INVALID_STATUS	状态不正确	只能取消 signed 状态的提现

---

完整代码示例

TypeScript/JavaScript (ethers.js v6)

import { ethers } from 'ethers';

const API_BASE = 'https://api.axblade.io/api/v1';
const VAULT_ADDRESS = '0xFDe43f8e6e082975d246844DEF4fE8E704403d43';
const USDT_ADDRESS = '0x572E474C3Cf364D085760784F938A1Aa397a8B9b';

// 充值
async function deposit(amount: string, token: string): Promise<void> {
  // 1. 准备充值
  const prepareRes = await fetch(`${API_BASE}/deposit/prepare`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify({ token: 'USDT', amount })
  });

  const { contract_address, token_address } = await prepareRes.json();

  // 2. 检查并授权 USDT
  const usdt = new ethers.Contract(token_address, [
    'function approve(address,uint256) returns (bool)',
    'function allowance(address,address) view returns (uint256)'
  ], signer);

  const amountWei = ethers.parseUnits(amount, 6);
  const allowance = await usdt.allowance(userAddress, contract_address);

  if (allowance < amountWei) {
    const approveTx = await usdt.approve(contract_address, ethers.MaxUint256);
    await approveTx.wait();
  }

  // 3. 调用充值
  const vault = new ethers.Contract(contract_address, [
    'function deposit(uint256,bytes32)'
  ], signer);

  const tx = await vault.deposit(amountWei, ethers.ZeroHash);
  await tx.wait();
}

// 提现
async function withdraw(amount: string, token: string): Promise<void> {
  // 1. 请求提现签名
  const withdrawRes = await fetch(`${API_BASE}/withdraw/request`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify({ token: 'USDT', amount })
  });

  const {
    withdraw_id,
    token: tokenAddress,
    backend_signature,
    nonce,
    expiry,
    vault_address
  } = await withdrawRes.json();

  // 2. 调用合约提现
  const vault = new ethers.Contract(vault_address, [
    'function withdraw(address,uint256,uint256,uint256,bytes)'
  ], signer);

  const amountWei = ethers.parseUnits(amount, 6);
  const tx = await vault.withdraw(
    tokenAddress,
    amountWei,
    nonce,
    expiry,
    backend_signature
  );

  const receipt = await tx.wait();

  // 3. 确认提现
  await fetch(`${API_BASE}/withdraw/${withdraw_id}/confirm`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify({ tx_hash: receipt.hash })
  });
}

---

相关链接

• Arbiscan (Sepolia)
• Vault 合约
• USDT 合约