> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fyatu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Request Withdrawal

> Request a withdrawal from your Fyatu business wallet to a registered address. POST /account/withdraw.

## Overview

Request a withdrawal to your registered withdrawal address. The withdrawal currency (USDT or USDC) and network are determined by your registered withdrawal address. The funds (amount + fee) are moved from your available balance to a hold balance pending confirmation, which can take up to 24 hours.

## Supported Currencies & Networks

Withdrawals support USDT and USDC on multiple networks:

| Currency | Networks                                     |
| -------- | -------------------------------------------- |
| `USDT`   | TRON, ETH, BSC, Polygon, Arbitrum, Avalanche |
| `USDC`   | TRON, ETH, BSC, Polygon, Arbitrum, Avalanche |

The currency and network are set when you register your withdrawal address.

## Prerequisites

Before requesting a withdrawal, you must:

1. **Register a withdrawal address** via `POST /account/withdrawal-address` (specify currency and network)
2. **Have your withdrawal address verified** (automatic for valid addresses)
3. **Have sufficient available balance** to cover amount + withdrawal fee

## Request Body

| Field    | Type   | Required | Description                             |
| -------- | ------ | -------- | --------------------------------------- |
| `amount` | number | Yes      | Amount to withdraw in USDT (before fee) |

## How It Works

1. **Validation**: System validates your withdrawal address is registered and verified
2. **Fee Calculation**: Withdrawal fee is calculated based on your business fee configuration
3. **Balance Check**: Ensures available balance >= amount + fee
4. **Limit Check**: Validates against daily and monthly withdrawal limits
5. **Hold Funds**: Moves total amount (amount + fee) from available balance to hold balance
6. **Create Transaction**: Creates a PENDING withdrawal transaction record

## Withdrawal Statuses

| Status       | Description                                            |
| ------------ | ------------------------------------------------------ |
| `PENDING`    | Withdrawal request submitted, awaiting processing      |
| `PROCESSING` | Withdrawal is being processed on the blockchain        |
| `COMPLETED`  | Withdrawal completed successfully, funds sent          |
| `FAILED`     | Withdrawal failed, funds returned to available balance |

## Example Usage

```javascript theme={null}
const response = await fetch('https://api.fyatu.com/api/v3/account/withdraw', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${accessToken}`
  },
  body: JSON.stringify({
    amount: 100.00
  })
});

const { data } = await response.json();

console.log(`Withdrawal ID: ${data.withdrawalId}`);
console.log(`Amount: ${data.amount} ${data.currency}`);
console.log(`Fee: ${data.fee}`);
console.log(`Total Deducted: ${data.totalAmount}`);
console.log(`To Address: ${data.address} (${data.network})`);
console.log(`Status: ${data.status}`);
console.log(`Est. Completion: ${data.estimatedCompletion}`);
```

## Error Responses

| Error Code                      | Description                                |
| ------------------------------- | ------------------------------------------ |
| `WITHDRAWAL_ADDRESS_MISSING`    | No withdrawal address registered           |
| `WITHDRAWAL_ADDRESS_UNVERIFIED` | Withdrawal address not yet verified        |
| `INSUFFICIENT_BALANCE`          | Not enough available balance               |
| `WITHDRAWAL_LIMIT_EXCEEDED`     | Daily or monthly withdrawal limit exceeded |
| `WALLET_INACTIVE`               | Wallet is suspended or inactive            |


## OpenAPI

````yaml v3/openapi.json POST /account/withdraw
openapi: 3.1.0
info:
  title: FYATU API v3
  description: >-
    FYATU API v3 with JWT authentication for Collections, Payouts, and Card
    Issuing.
  version: 3.0.0
  contact:
    name: FYATU Support
    url: https://fyatu.com
    email: support@fyatu.com
servers:
  - url: https://api.fyatu.com/api/v3
    description: Production
security: []
tags:
  - name: Authentication
    description: JWT token management endpoints
  - name: Account
    description: Business account, wallet, and address management
  - name: Collections
    description: Accept payments from customers via checkout sessions
  - name: Refunds
    description: Issue refunds for completed collections
  - name: Payouts
    description: Send money to Fyatu account holders
  - name: Cardholders
    description: Cardholder management for card issuing programs
  - name: Cards
    description: Issue, fund, freeze, and manage virtual cards
  - name: Webhooks
    description: Webhook configuration and management
paths:
  /account/withdraw:
    post:
      tags:
        - Account
      summary: Request Withdrawal
      description: >-
        Request a withdrawal of USDT to your registered withdrawal address.
        Funds are moved from available balance to hold balance pending
        confirmation (up to 24 hours).
      operationId: requestWithdrawal
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WithdrawalRequest'
            example:
              amount: 100
      responses:
        '200':
          description: Withdrawal request submitted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WithdrawalRequestResponse'
              example:
                success: true
                status: 200
                message: >-
                  Withdrawal request submitted successfully. Processing can take
                  up to 24 hours.
                data:
                  withdrawalId: WD1A2B3C4D5E6F7G8H
                  amount: 100
                  fee: 2
                  totalAmount: 102
                  currency: USDT
                  address: TYourTronAddressHere1234567890123
                  network: TRON
                  status: PENDING
                  estimatedCompletion: '2026-01-06T10:30:00+00:00'
                  balance:
                    available: 898
                    hold: 102
                    total: 1000
                meta:
                  requestId: req_abc123def456
                  timestamp: '2026-01-05T10:30:00+00:00'
        '400':
          description: Validation error or withdrawal requirements not met
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                noAddress:
                  summary: No withdrawal address
                  value:
                    success: false
                    status: 400
                    message: >-
                      No withdrawal address registered. Please register a
                      withdrawal address first.
                    error:
                      code: WITHDRAWAL_ADDRESS_MISSING
                unverified:
                  summary: Address not verified
                  value:
                    success: false
                    status: 400
                    message: >-
                      Withdrawal address is not verified. Please verify your
                      withdrawal address first.
                    error:
                      code: WITHDRAWAL_ADDRESS_UNVERIFIED
                limitExceeded:
                  summary: Withdrawal limit exceeded
                  value:
                    success: false
                    status: 400
                    message: Daily withdrawal limit exceeded
                    error:
                      code: WITHDRAWAL_LIMIT_EXCEEDED
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: Insufficient balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                status: 402
                message: >-
                  Insufficient balance. Required: $102.00 (amount: $100.00 +
                  fee: $2.00), Available: $50.00
                error:
                  code: INSUFFICIENT_BALANCE
        '403':
          description: Wallet inactive
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                status: 403
                message: Wallet is not active
                error:
                  code: WALLET_INACTIVE
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - BearerAuth: []
components:
  schemas:
    WithdrawalRequest:
      type: object
      required:
        - amount
      properties:
        amount:
          type: number
          description: Amount to withdraw in USDT (before fee)
          example: 100
          minimum: 0.01
    WithdrawalRequestResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        status:
          type: integer
          example: 200
        message:
          type: string
        data:
          $ref: '#/components/schemas/WithdrawalRequestData'
        meta:
          $ref: '#/components/schemas/Meta'
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        status:
          type: integer
          example: 401
        message:
          type: string
          example: Invalid credentials
        error:
          $ref: '#/components/schemas/Error'
        meta:
          $ref: '#/components/schemas/Meta'
    WithdrawalRequestData:
      type: object
      properties:
        withdrawalId:
          type: string
          description: Unique withdrawal ID
        amount:
          type: number
          description: Requested withdrawal amount
        fee:
          type: number
          description: Withdrawal fee
        totalAmount:
          type: number
          description: Total amount deducted (amount + fee)
        currency:
          type: string
          example: USDT
        address:
          type: string
          description: Destination withdrawal address
        network:
          type: string
          description: Network (TRON, ETH, BSC, POLYGON, ARBITRUM, AVALANCHE)
        status:
          type: string
          enum:
            - PENDING
            - PROCESSING
            - COMPLETED
            - FAILED
        estimatedCompletion:
          type: string
          format: date-time
          description: Estimated completion time
        balance:
          type: object
          properties:
            available:
              type: number
              description: Available balance after withdrawal
            hold:
              type: number
              description: Amount currently on hold
            total:
              type: number
              description: Total balance
    Meta:
      type: object
      properties:
        requestId:
          type: string
          description: Unique request ID for tracking
          example: req_abc123def456
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the response
    Error:
      type: object
      properties:
        code:
          type: string
          description: Error code for programmatic handling
          example: AUTH_INVALID_CREDENTIALS
        details:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
          description: Validation error details (for VALIDATION_ERROR)
    ValidationError:
      type: object
      properties:
        field:
          type: string
          description: Field that failed validation
          example: appId
        message:
          type: string
          description: Validation error message
          example: AppId is required
  responses:
    Unauthorized:
      description: Authentication required or token invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            status: 401
            message: Unable to identify business
            error:
              code: AUTH_TOKEN_INVALID
            meta:
              requestId: req_abc123
              timestamp: '2026-01-05T10:30:00+00:00'
    ServerError:
      description: Server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            status: 500
            message: Failed to generate deposit address. Please try again later.
            error:
              code: SERVER_ERROR
            meta:
              requestId: req_abc123
              timestamp: '2026-01-05T10:30:00+00:00'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT access token obtained from /auth/token

````