钱包管理 API

钱包管理 API 提供商户账户余额查询、提现地址管理、发起提现等功能。所有钱包操作都需要特定的 API 权限。

概述

基础 URL

https://api.payve.io/api/v1

认证方式

Bearer Token (JWT)

所需权限

wallet:read, wallet:write

手续费率

1% (自动计算)

查询余额

获取商户账户的各币种余额信息。

GET/wallet/balance

查询参数

参数	类型	必填	说明
`currency`	string	❌	指定币种，不填返回所有币种余额
`network`	string	❌	指定网络，配合 currency 使用

响应示例

{
  "totalValueUSD": "10250.50",
  "balances": [
    {
      "currency": "USDT",
      "network": "TRON",
      "available": "5000.00000000",
      "pending": "100.00000000",
      "frozen": "0.00000000",
      "total": "5100.00000000",
      "valueUSD": "5100.00"
    },
    {
      "currency": "BTC",
      "network": "Bitcoin",
      "available": "0.12345678",
      "pending": "0.00100000",
      "frozen": "0.00000000",
      "total": "0.12445678",
      "valueUSD": "5150.50"
    }
  ],
  "updatedAt": "2024-01-15T10:30:00Z"
}

JSON

代码已折叠

共 24 行

余额字段说明

字段	说明
`available`	可用余额，可以立即提现
`pending`	待确认余额，区块链确认中
`frozen`	冻结余额，因风控或争议暂时冻结
`total`	总余额 = available + pending + frozen
`valueUSD`	以美元计价的价值（实时汇率）

查询交易历史

获取钱包的交易记录，包括收款和提现。

GET/wallet/transactions

查询参数

参数	类型	说明
`type`	string	交易类型（deposit, withdrawal, fee）
`currency`	string	币种筛选
`status`	string	状态筛选
`startDate`	string	开始日期
`endDate`	string	结束日期
`page`	integer	页码
`limit`	integer	每页数量

响应示例

{
  "data": [
    {
      "id": "tx_abc123",
      "type": "deposit",
      "currency": "USDT",
      "network": "TRON",
      "amount": "100.00000000",
      "fee": "1.00000000",
      "netAmount": "99.00000000",
      "status": "completed",
      "txHash": "0x742d35cc...",
      "from": "TRX9Q8ybY6...",
      "to": "TN3W4H6rK2...",
      "orderId": "pay_xyz789",
      "createdAt": "2024-01-15T10:00:00Z",
      "completedAt": "2024-01-15T10:05:00Z"
    },
    {
      "id": "tx_def456",
      "type": "withdrawal",
      "currency": "USDT",
      "network": "TRON",
      "amount": "50.00000000",
      "fee": "0.50000000",
      "netAmount": "49.50000000",
      "status": "processing",
      "to": "TN3W4H6rK2...",
      "createdAt": "2024-01-15T11:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

JSON

代码已折叠

共 38 行

提现地址管理

获取提现地址列表

GET/wallet/addresses

{
  "addresses": [
    {
      "id": "addr_abc123",
      "label": "主钱包",
      "address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
      "network": "TRON",
      "currency": "USDT",
      "isWhitelisted": true,
      "isDefault": true,
      "createdAt": "2024-01-01T00:00:00Z",
      "lastUsedAt": "2024-01-15T10:00:00Z",
      "verifiedAt": "2024-01-01T00:10:00Z"
    }
  ],
  "total": 5
}

JSON

代码已折叠

共 17 行

添加提现地址

POST/wallet/addresses

请求参数

参数	类型	必填	说明
`address`	string	✅	钱包地址
`network`	string	✅	区块链网络
`currency`	string	✅	支持的币种
`label`	string	✅	地址标签/备注
`isDefault`	boolean	❌	设为默认地址
`verificationCode`	string	✅	邮箱验证码

请求示例

{
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0b0d0",
  "network": "Ethereum",
  "currency": "USDT",
  "label": "冷钱包地址",
  "isDefault": false,
  "verificationCode": "123456"
}

安全提示：添加新地址需要邮箱验证。地址添加后 24 小时内不能用于提现。

删除提现地址

DELETE/wallet/addresses/{addressId}

需要提供邮箱验证码：

{
  "verificationCode": "123456"
}

发起提现

创建提现申请

POST/wallet/withdrawals

请求参数

参数	类型	必填	说明
`amount`	string	✅	提现金额
`currency`	string	✅	币种
`network`	string	✅	区块链网络
`addressId`	string	✅*	提现地址 ID
`address`	string	✅*	提现地址（与 addressId 二选一）
`memo`	string	❌	备注/标签（某些币种需要）
`verificationCode`	string	✅	验证码（邮箱/2FA）

请求示例

{
  "amount": "1000.00",
  "currency": "USDT",
  "network": "TRON",
  "addressId": "addr_abc123",
  "verificationCode": "123456"
}

响应示例

{
  "withdrawalId": "wd_xyz789",
  "status": "pending",
  "amount": "1000.00000000",
  "fee": "10.00000000",
  "netAmount": "990.00000000",
  "currency": "USDT",
  "network": "TRON",
  "address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
  "estimatedArrival": "2024-01-15T11:00:00Z",
  "createdAt": "2024-01-15T10:30:00Z",
  "limits": {
    "minimumAmount": "10.00",
    "maximumAmount": "100000.00",
    "dailyRemaining": "99000.00",
    "monthlyRemaining": "900000.00"
  }
}

JSON

代码已折叠

共 18 行

查询提现状态

GET/wallet/withdrawals/{withdrawalId}

{
  "withdrawalId": "wd_xyz789",
  "status": "completed",
  "amount": "1000.00000000",
  "fee": "10.00000000",
  "netAmount": "990.00000000",
  "currency": "USDT",
  "network": "TRON",
  "address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
  "txHash": "0x742d35cc6634c0532925a3b844bc9e7595f0b0d0",
  "confirmations": 20,
  "createdAt": "2024-01-15T10:30:00Z",
  "processedAt": "2024-01-15T10:35:00Z",
  "completedAt": "2024-01-15T10:40:00Z"
}

JSON

代码已折叠

共 15 行

取消提现

只能取消状态为 pending 的提现申请。

POST/wallet/withdrawals/{withdrawalId}/cancel

{
  "reason": "用户取消",
  "verificationCode": "123456"
}

提现限额

查询提现限额

GET/wallet/limits

{
  "limits": {
    "USDT": {
      "TRON": {
        "minimumAmount": "10.00",
        "maximumAmount": "100000.00",
        "dailyLimit": "100000.00",
        "dailyUsed": "1000.00",
        "dailyRemaining": "99000.00",
        "monthlyLimit": "1000000.00",
        "monthlyUsed": "100000.00",
        "monthlyRemaining": "900000.00"
      },
      "Ethereum": {
        "minimumAmount": "50.00",
        "maximumAmount": "50000.00",
        "dailyLimit": "50000.00",
        "dailyUsed": "0.00",
        "dailyRemaining": "50000.00",
        "monthlyLimit": "500000.00",
        "monthlyUsed": "0.00",
        "monthlyRemaining": "500000.00"
      }
    },
    "BTC": {
      "Bitcoin": {
        "minimumAmount": "0.001",
        "maximumAmount": "10.00",
        "dailyLimit": "10.00",
        "dailyUsed": "0.00",
        "dailyRemaining": "10.00",
        "monthlyLimit": "100.00",
        "monthlyUsed": "0.00",
        "monthlyRemaining": "100.00"
      }
    }
  },
  "kycLevel": 0,
  "nextLevelBenefits": {
    "level": 1,
    "dailyLimitIncrease": "5x",
    "monthlyLimitIncrease": "5x",
    "feeDiscount": "10%"
  }
}

JSON

代码已折叠

共 45 行

手续费计算

预估提现手续费

POST/wallet/estimate-fee

请求参数

{
  "amount": "1000.00",
  "currency": "USDT",
  "network": "TRON",
  "type": "withdrawal"
}

响应示例

{
  "amount": "1000.00",
  "platformFee": "10.00",
  "platformFeeRate": "1%",
  "networkFee": "1.00",
  "totalFee": "11.00",
  "netAmount": "989.00",
  "estimatedArrival": "10-30 minutes",
  "exchangeRate": null
}

结算管理

自动结算设置

配置自动结算规则，将不同币种自动转换为指定币种。

POST/wallet/settlement/config

{
  "enabled": true,
  "targetCurrency": "USDT",
  "targetNetwork": "TRON",
  "schedule": "daily",
  "time": "00:00",
  "minimumAmount": "100.00",
  "autoWithdraw": false,
  "withdrawAddress": "addr_abc123"
}

手动结算

立即执行结算，将账户余额转换为指定币种。

POST/wallet/settlement/execute

{
  "sourceCurrencies": ["BTC", "ETH", "BNB"],
  "targetCurrency": "USDT",
  "targetNetwork": "TRON",
  "verificationCode": "123456"
}

提现状态说明

状态	说明
`pending`	待处理 - 提现申请已提交
`reviewing`	审核中 - 人工审核（大额提现）
`approved`	已批准 - 审核通过，准备处理
`processing`	处理中 - 正在广播交易
`sent`	已发送 - 交易已广播到区块链
`completed`	已完成 - 提现成功到账
`failed`	失败 - 提现失败
`cancelled`	已取消 - 用户或系统取消
`rejected`	已拒绝 - 审核拒绝

安全建议

1. 地址白名单

强烈建议启用地址白名单功能：

// 只允许提现到白名单地址
const withdrawal = await createWithdrawal({
  amount: '1000.00',
  currency: 'USDT',
  network: 'TRON',
  addressId: 'addr_abc123', // 使用预先添加的地址 ID
  verificationCode: '123456'
});

2. 双重验证

对于大额提现，建议启用 2FA：

// 获取 2FA 验证码
const verificationCode = await get2FACode();
 
// 提交提现请求
const withdrawal = await createWithdrawal({
  amount: '10000.00',
  currency: 'USDT',
  network: 'TRON',
  addressId: 'addr_abc123',
  verificationCode: verificationCode
});

JAVASCRIPT

代码已折叠

共 11 行

3. 限额管理

合理设置提现限额，降低风险：

日限额：防止单日大额损失
单笔限额：限制单次提现金额
地址限额：对不同地址设置不同限额

4. 监控告警

设置提现监控和告警：

// 监控异常提现
function monitorWithdrawals(withdrawal) {
  // 大额提现告警
  if (withdrawal.amount > 10000) {
    sendAlert('Large withdrawal detected', withdrawal);
  }
  
  // 频繁提现告警
  if (getRecentWithdrawalsCount() > 10) {
    sendAlert('Frequent withdrawals detected');
  }
  
  // 新地址提现告警
  if (isNewAddress(withdrawal.address)) {
    sendAlert('Withdrawal to new address', withdrawal);
  }
}

JAVASCRIPT

代码已折叠

共 17 行

错误码

钱包相关的特定错误码：

错误码	说明	解决方案
`3001`	余额不足	检查可用余额
`3002`	地址格式无效	验证地址格式
`3003`	超出提现限额	降低金额或提升 KYC
`3004`	地址不在白名单	添加地址到白名单
`3005`	提现金额过小	提高提现金额
`3006`	地址验证失败	重新验证地址
`3007`	提现暂时禁用	联系客服
`3008`	网络暂不可用	稍后重试或换网络

示例代码

完整的提现流程

const PayveAPI = require('@payve/sdk');
 
async function processWithdrawal() {
  const api = new PayveAPI({
    apiKey: process.env.PAYVE_API_KEY,
    apiSecret: process.env.PAYVE_API_SECRET
  });
  
  try {
    // 1. 检查余额
    const balance = await api.wallet.getBalance('USDT');
    console.log('Available balance:', balance.available);
    
    if (parseFloat(balance.available) < 1000) {
      throw new Error('Insufficient balance');
    }
    
    // 2. 检查限额
    const limits = await api.wallet.getLimits('USDT', 'TRON');
    console.log('Daily remaining:', limits.dailyRemaining);
    
    // 3. 预估手续费
    const estimate = await api.wallet.estimateFee({
      amount: '1000.00',
      currency: 'USDT',
      network: 'TRON'
    });
    console.log('Net amount:', estimate.netAmount);
    
    // 4. 发起提现
    const withdrawal = await api.wallet.createWithdrawal({
      amount: '1000.00',
      currency: 'USDT',
      network: 'TRON',
      addressId: 'addr_abc123',
      verificationCode: '123456'
    });
    console.log('Withdrawal created:', withdrawal.withdrawalId);
    
    // 5. 轮询状态
    let status = 'pending';
    while (status !== 'completed' && status !== 'failed') {
      await sleep(5000);
      const result = await api.wallet.getWithdrawal(withdrawal.withdrawalId);
      status = result.status;
      console.log('Status:', status);
    }
    
    return withdrawal;
  } catch (error) {
    console.error('Withdrawal failed:', error);
    throw error;
  }
}

JAVASCRIPT

代码已折叠

共 54 行

概述

查询余额

查询参数

响应示例

余额字段说明

查询交易历史

查询参数

响应示例

提现地址管理

获取提现地址列表

添加提现地址

请求参数

请求示例

删除提现地址

发起提现

创建提现申请

请求参数

请求示例

响应示例

查询提现状态

取消提现

提现限额

查询提现限额

手续费计算

预估提现手续费

请求参数

响应示例

结算管理

自动结算设置

手动结算

提现状态说明

安全建议

1. 地址白名单

2. 双重验证

3. 限额管理

4. 监控告警

错误码

示例代码

完整的提现流程

相关文档