Withdrawals

This guide explains how to withdraw funds from your wallets to external addresses.

POST/wallets/:wallet_id/request-withdrawal

Request withdrawal

Create a new withdrawal request from a wallet. The withdrawal will require approval from authorized users.

Required parameters

  • Name
    asset_id
    Type
    string
    Description

    The UUID of the asset to withdraw.

  • Name
    amount
    Type
    string
    Description

    The amount to withdraw in decimal string format.

  • Name
    recipient_address
    Type
    string
    Description

    The blockchain address to send funds to.

Response

  • Name
    id
    Type
    string
    Description

    The UUID of the withdrawal request.

  • Name
    status
    Type
    string
    Description

    Current status of the withdrawal:

    • PENDING_APPROVAL: Waiting for approvals from authorized users
    • PENDING: Approved and waiting to be processed
    • EXECUTED: Transaction has been sent to the blockchain
    • SUCCESS: Transaction has been confirmed on the blockchain
    • REJECTED: Withdrawal was rejected by an approver
    • FAILED: Transaction failed to execute
  • Name
    wallet_id
    Type
    string
    Description

    The UUID of the source wallet.

  • Name
    asset_id
    Type
    string
    Description

    The UUID of the asset being withdrawn.

  • Name
    amount
    Type
    string
    Description

    The withdrawal amount.

  • Name
    recipient_address
    Type
    string
    Description

    The destination blockchain address.

  • Name
    creator_id
    Type
    string
    Description

    The UUID of the user who created the withdrawal request.

  • Name
    withdrawal_approvals
    Type
    array
    Description

    List of approval statuses from authorized users.

  • Name
    created_at
    Type
    string
    Description

    Timestamp of when the request was created.

  • Name
    updated_at
    Type
    string
    Description

    Timestamp of the last status update.

The withdrawal process follows this flow:

  1. PENDING_APPROVAL → Waiting for required approvals
  2. PENDING → Approved and queued for processing
  3. EXECUTED → Transaction sent to blockchain
  4. SUCCESS → Transaction confirmed

Or if rejected/failed:

  • REJECTED → An approver rejected the withdrawal
  • FAILED → Transaction failed to execute

Request

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"
  }
)
GET/withdrawals/:withdrawal_id

Get withdrawal status

Get the current status of a withdrawal request.

Response

  • Name
    success
    Type
    boolean
    Description

    Indicates whether the request was successful.

  • Name
    data
    Type
    object
    Description

    Contains the withdrawal details.

  • Name
    id
    Type
    string
    Description

    The UUID of the withdrawal request.

  • Name
    status
    Type
    string
    Description

    Current status of the withdrawal.

  • Name
    amount
    Type
    string
    Description

    The withdrawal amount.

  • Name
    recipient_address
    Type
    string
    Description

    The destination blockchain address.

  • Name
    creator
    Type
    object
    Description

    Information about the user who created the withdrawal.

  • Name
    asset
    Type
    object
    Description

    Details about the asset being withdrawn.

  • Name
    transaction
    Type
    object
    Description

    Complete transaction details once executed.

Request

GET
/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(
  "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)