转账

本指南介绍如何将资金从你的钱包转账到外部地址。

发起提现请求

POST
/wallets/{wallet_id}/request-withdrawal

从钱包创建一个新的提现请求。该提现需要经过授权用户的审批。

请求头

  • Name
    X-Idempotency-Key
    Type
    header
    Recommended
    recommended
    Description

    用于标识此次提现的 UUID，确保它只被处理一次。如果在 24 小时内再次发送相同的 key，系统会返回原始请求的缓存响应，而不会创建重复的提现。

    请将该 key 与你自己系统中的提现记录绑定：如果你内部的提现或转账 ID 是 UUID，可直接使用；否则请在创建该记录时生成一次 UUID 并一同保存。每次重试都发送相同的 key。不要每次尝试都生成新的 key，因为每个新的 key 都会被视为一笔新的提现。

参数

  • Name
    asset_id
    Type
    string
    Required
    required
    Description

    要提现的资产的 UUID。

  • Name
    amount
    Type
    string
    Required
    required
    Description

    提现金额，使用十进制字符串格式。

  • Name
    recipient_address
    Type
    string
    Required
    required
    Description

    接收资金的区块链地址。

响应

  • Name
    id
    Type
    string
    Description

    提现请求的 UUID。

  • Name
    status
    Type
    string
    Description

    提现的当前状态：

    • PENDING_APPROVAL：等待授权用户审批
    • PENDING：已批准，等待处理
    • EXECUTED：交易已发送到区块链
    • SUCCESS：交易已在区块链上确认
    • REJECTED：提现被审批人拒绝
    • FAILED：交易执行失败
  • Name
    wallet_id
    Type
    string
    Description

    来源钱包的 UUID。

  • Name
    asset_id
    Type
    string
    Description

    被提现资产的 UUID。

  • Name
    amount
    Type
    string
    Description

    提现金额。

  • Name
    recipient_address
    Type
    string
    Description

    目标区块链地址。

  • Name
    creator_id
    Type
    string
    Description

    创建该提现请求的用户的 UUID。

  • Name
    withdrawal_approvals
    Type
    array
    Description

    授权用户的审批状态列表。

  • Name
    created_at
    Type
    string
    Description

    请求创建的时间戳。

  • Name
    updated_at
    Type
    string
    Description

    最后一次状态更新的时间戳。

提现流程如下：

  1. PENDING_APPROVAL → 等待所需的审批
  2. PENDING → 已批准，排队等待处理
  3. EXECUTED → 交易已发送到区块链
  4. SUCCESS → 交易已确认

如果被拒绝或失败：

  • REJECTED → 审批人拒绝了该提现
  • FAILED → 交易执行失败

请求

POST
/wallets/:wallet_id/request-withdrawal
import { FystackSDK, Environment } from "@fystack/sdk"
  
const apiCredentials = {
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET
}


const sdk = new FystackSDK({
  credentials: apiCredentials,
  environment: Environment.Sandbox,
  logger: true
})


const response = await sdk.requestWithdrawal(
  "e0851607-417a-475a-b399-5f3aa262b81d",
  {
    assetId: "f1be472d-1338-43ff-b547-06faba7ecce7",
    amount: "0.001",
    recipientAddress: "0xe6EBF81E9C225BbCEa9b5399E0D0d0f29f30f119"
  }
)

Response

200
{
  "success": true,
  "message": "success",
  "code": 0,
  "data": {
    "id": "0de79230-a820-4bd4-b020-883d395faa87",
    "wallet_id": "e0851607-417a-475a-b399-5f3aa262b81d",
    "asset_id": "f1be472d-1338-43ff-b547-06faba7ecce7",
    "amount": "1000",
    "recipient_address": "0x7c2BbE2e02af09F1cf9aFd4A79EC201DC841675a",
    "status": "PENDING_APPROVAL",
    "creator_id": "075243c1-962e-4803-83da-d73c78b8b060",
    "withdrawal_approvals": [
      {
        "id": "9a85c312-7d3b-4c6f-9f4e-123456789abc",
        "withdrawal_id": "0de79230-a820-4bd4-b020-883d395faa87",
        "user_id": "075243c1-962e-4803-83da-d73c78b8b060",
        "status": "PENDING",
        "created_at": "2025-08-11T17:37:29.815148+07:00",
        "updated_at": "2025-08-11T17:37:29.815148+07:00"
      },
      {
        "id": "8b74d123-9e5f-4a2d-8c3b-987654321def",
        "withdrawal_id": "0de79230-a820-4bd4-b020-883d395faa87",
        "user_id": "165243c1-962e-4803-83da-d73c78b8b070",
        "status": "APPROVED",
        "created_at": "2025-08-11T17:37:29.815148+07:00",
        "updated_at": "2025-08-11T17:38:15.623147+07:00"
      }
    ],
    "created_at": "2025-08-11T17:37:29.815148+07:00",
    "updated_at": "2025-08-11T17:37:29.815148+07:00"
  }
}

获取提现状态

GET
/wallets/{wallet_id}/withdrawals/{withdrawal_id}

获取提现请求的当前状态。

响应

  • Name
    success
    Type
    boolean
    Description

    表示请求是否成功。

  • Name
    data
    Type
    object
    Description

    包含提现详情。

  • Name
    id
    Type
    string
    Description

    提现请求的 UUID。

  • Name
    status
    Type
    string
    Description

    提现的当前状态。

  • Name
    amount
    Type
    string
    Description

    提现金额。

  • Name
    recipient_address
    Type
    string
    Description

    目标区块链地址。

  • Name
    creator
    Type
    object
    Description

    创建该提现的用户信息。

  • Name
    asset
    Type
    object
    Description

    被提现资产的详情。

  • Name
    transaction
    Type
    object
    Description

    执行后的完整交易详情。

请求

GET
/wallets/:wallet_id/withdrawals/:withdrawal_id
import { FystackSDK, Environment } from "@fystack/sdk"
  
const apiCredentials = {
  apiKey: process.env.API_KEY,
  apiSecret: process.env.API_SECRET
}


const sdk = new FystackSDK({
  credentials: apiCredentials,
  environment: Environment.Sandbox,
  logger: true
})


// Get withdrawal status
const withdrawal = await sdk.getWithdrawalStatus(
  "e0851607-417a-475a-b399-5f3aa262b81d",
  "4cebc6c3-1e46-4166-ab59-86a59971215f"
)


// Check withdrawal status
if (withdrawal.status === 'SUCCESS') {
  console.log('Transaction hash:', withdrawal.transaction.tx_hash)
  console.log('Amount:', withdrawal.amount)
  console.log('Asset:', withdrawal.asset.symbol)
}


// Check approval status
const approvals = withdrawal.withdrawal_approvals
const pendingApprovals = approvals.filter(a => a.status === 'PENDING')
const approvedCount = approvals.filter(a => a.status === 'APPROVED').length


console.log('Pending approvals:', pendingApprovals.length)
console.log('Approved count:', approvedCount)

Response

200
{
  "success": true,
  "message": "success",
  "code": 0,
  "data": {
    "id": "4cebc6c3-1e46-4166-ab59-86a59971215f",
    "created_at": "2025-07-29T21:44:23.763113+07:00",
    "updated_at": "2025-07-29T21:45:07.204964+07:00",
    "amount": "0.000001622515351558",
    "status": "SUCCESS",
    "recipient_address": "0xf2acfF1D9d576E9b8B7C7d58A449F599A9A54edA",
    "creator_id": "075243c1-962e-4803-83da-d73c78b8b060",
    "creator": {
      "id": "075243c1-962e-4803-83da-d73c78b8b060",
      "username": "Dev team"
    },
    "asset_id": "a469642e-5466-4d69-834d-537f33ee5c81",
    "asset": {
      "id": "a469642e-5466-4d69-834d-537f33ee5c81",
      "name": "Ethereum Sepolia",
      "symbol": "ETH",
      "decimals": 18,
      "logo_url": "https://icons.iconarchive.com/icons/cjdowner/cryptocurrency-flat/512/Ethereum-ETH-icon.png",
      "is_native": true,
      "address_type": "evm",
      "network_id": "23d13c03-1f3c-4e2a-9aef-1771a244b7f6"
    },
    "withdrawal_approvals": [
      {
        "id": "dfa94b32-83f5-4808-8091-9a3c270d4f1d",
        "status": "PENDING",
        "user": {
          "username": "Thi Nguyen",
          "email": "nguyendanganhthi247@gmail.com"
        }
      },
      {
        "id": "776303fd-762e-4593-9f66-93631dd226e0",
        "status": "APPROVED",
        "user": {
          "username": "Dev team",
          "email": "devteam@fystack.io"
        }
      }
    ],
    "transaction": {
      "tx_hash": "0xa1ec8bab32baebad1211e838d655777640e78102b39b008bd00a8b3e5d1f3c00",
      "status": "confirmed",
      "block_number": 8868747,
      "from_address": "0xA793457d84CFD255Ed68295984300C4f799E759F",
      "to_address": "0xf2acfF1D9d576E9b8B7C7d58A449F599A9A54edA",
      "amount": "0.000001622515351558",
      "tx_fee": "0.000001296799854",
      "price_native_token": "3808.475025265875",
      "direction": "out",
      "type": "withdrawal",
      "method": "transfer"
    }
  }
}