Cards

Card Withdrawals

Create card withdrawals to blockchain wallets and check the latest withdrawal status.

Flow Summary

The current withdrawal flow is:

Step 1. Make sure the source card is active
Use Card List first

Step 2. Create the withdrawal
POST /api/v2/card-withdrawals

Step 3. Check the latest withdrawal state
GET /api/v2/cards/{uuid}/withdraw-status

All routes below should be treated as protected routes and sent with:

Authorization: Bearer <access_token>

1. Create Card Withdrawal

POST /api/v2/card-withdrawals

Creates a withdrawal from a card to a blockchain wallet.

Request

{
  "source_card_uuid": "5e5d4990-2241-46dc-9dbd-8abcf97e6061",
  "wallet_address": "TP6fJc4Y7Qm6kQ1u1FfH2uZzGgQqV1kB2u",
  "amount": "50.00",
  "network": "TRC20"
}

Request rules

  • source_card_uuid is required and must be a UUID
  • wallet_address is required
  • amount is required
  • amount must be sent as a JSON string, not a JSON number
  • amount must parse as a decimal value greater than 0
  • network is required

Important backend behavior

  • The route is IP-rate-limited to 60 requests per minute
  • The source card must belong to the current user
  • The source card must be ACTIVE
  • The network must be a valid blockchain network enum
  • The current accepted values include TRC20 and ERC20
  • Only one pending withdrawal is allowed per user at a time
  • The submitted amount must be greater than the configured withdrawal fee
  • The service creates the withdrawal row first, then executes the withdrawal synchronously

2. Get Latest Withdrawal Status

GET /api/v2/cards/{uuid}/withdraw-status

Returns the raw status of the latest withdrawal for a specific card UUID.

Path parameter

  • uuid is required
  • uuid is the card UUID, not the withdrawal UUID

Returned statuses

The route returns the latest withdrawal status for the selected card, commonly:

  • PENDING
  • PROCESSING
  • SUCCESS
  • FAILED
  • NOT_FOUND

Notes

  • The response returns the latest available withdrawal status for that card
  • If no withdrawal exists yet, the route returns NOT_FOUND

Success response shape

{
  "status_code": 200,
  "message": "Success",
  "data": {
    "status": "PENDING"
  }
}
Copyright © 2026