Account Transfers API

Transfer funds between spot and perpetuals accounts via the API.

The account transfer API provides an endpoint for transferring funds between spot and perpetuals accounts. A transfer request returns 202 Accepted when the request is accepted; you are notified of completion on the transfer_updates WebSocket channel.

POST /accounts/transfer

Initiate a fund transfer between spot and perpetuals accounts. The request returns 202 Accepted when accepted, and you are notified of completion on the transfer_updates WebSocket channel.

Authentication: Required (JWT or API Key)

Request Body:

{
  "app_session_id": "your-session-id",
  "source_account_type": "spot",
  "dest_account_type": "perps",
  "asset_symbol": "USDT",
  "amount": "1000.50"
}

Request Parameters:

Parameter	Type	Required	Options	Description
app_session_id	string	Yes	—	User's session ID (shared between spot and perps accounts)
source_account_type	string	Yes	spot, perps	Source account type
dest_account_type	string	Yes	spot, perps	Destination account type
asset_symbol	string	Yes	—	Stablecoin asset to transfer (e.g., "USDT"). Only stablecoin assets that are active on both spot and perps sides are allowed.
amount	string	Yes	Positive decimal	Amount to transfer (decimal format)

Asset Restrictions:

• Only stablecoin assets can be transferred between spot and perps accounts.

• The asset must be active as a stablecoin on both the spot and perps sides.

• Use GET /perpetual/transfer-assets to fetch the list of transferable stablecoin assets.

Perpetual → Spot (perps as source):

When transferring from a perps account to spot, the maximum transferable amount is capped per request:

transferable_max = max(0, min(total_balance - locked_balance, available_balance)) × 80%

• available_balance follows balance-query semantics (it includes unrealized PnL where applicable).

• If amount exceeds transferable_max, the transfer is rejected with an insufficient-balance error.

Balance Notifications:

• After a successful transfer, both the source and destination accounts emit balance update events over WebSocket so clients can refresh displayed balances without polling.

• Spot balance updates are delivered on the spot_account.balance_update channel.

• Perps balance updates are delivered on the perpetuals_account.balance_update channel.

Response (202 Accepted):

{
  "transfer_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Transfer initiated successfully. You will be notified when the transfer completes."
}

Response Fields:

Field	Type	Description
transfer_id	string	Unique UUID for tracking the transfer
message	string	Human-readable status message

Status Codes:

• 202 - Transfer request accepted and queued for processing

• 400 - Invalid request parameters (non-stablecoin asset, invalid amount, etc.)

• 401 - Authentication failed (missing or invalid JWT/API key)

• 500 - Internal server error

• 503 - Transfer validation service temporarily unavailable

Error Responses:

400 Bad Request - Invalid parameters:

{
  "error": "invalid_amount",
  "message": "Amount must be positive"
}

Possible error codes:

• invalid_request_format - Malformed JSON or missing required fields

• invalid_amount - Amount is zero, negative, or invalid decimal

• invalid_source_type - Source account type must be 'spot' or 'perps'

• invalid_dest_type - Destination account type must be 'spot' or 'perps'

• same_account_type - Source and destination types cannot be the same

• invalid_asset - Asset is not supported for spot-perps transfer (not a stablecoin, not active, or not found)

• amount_below_minimum - Amount is below minimum transfer amount for the asset

401 Unauthorized:

{
  "error": "missing_wallet_address",
  "message": "Wallet address not found in authentication context"
}

500 Internal Server Error:

{
  "error": "transfer_failed",
  "message": "Failed to initiate transfer. Please try again or contact support."
}

Transfer Lifecycle:

After a transfer is accepted:

1. The request is validated and accepted, returning 202 Accepted with a transfer_id.

2. Funds are debited from the source account, then credited to the destination account.

3. When the transfer completes (or fails), the client is notified in real time on the transfer_updates WebSocket channel.

Transfer States:

State	Description
pending	Transfer initiated, waiting for source processing
source_completed	Funds deducted from source account
dest_completed	Funds added to destination account (final success state)
failed	Transfer failed before any funds were moved

WebSocket Notification:

When the transfer completes (or fails), you receive a real-time notification:

{
  "channel": "transfer_updates",
  "data": {
    "transfer_id": "550e8400-e29b-41d4-a716-446655440000",
    "owner_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "app_session_id": "your-session-id",
    "source_type": "spot",
    "dest_type": "perps",
    "asset_symbol": "USDT",
    "amount": "1000.50",
    "state": "dest_completed",
    "completed_at": "2026-02-16T10:30:45.123456Z"
  }
}

Important Notes:

• Stablecoin Only: Only stablecoin assets that are active on both the spot and perps sides can be transferred

• Perp → Spot cap: Outgoing perpetuals transfers are limited per request to 80% of min(total - locked, available) (see Perpetual → Spot above); plan amount accordingly or split into multiple transfers

• Real-time Updates: Subscribe to WebSocket transfer_updates channel for completion notifications. Balance update notifications are also pushed to spot_account.balance_update and perpetuals_account.balance_update channels.

• Source and destination types must be different (cannot transfer within the same account type)

Example Request:

curl -X POST https://trade.api.yellow.pro/accounts/transfer \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "app_session_id": "your-session-id",
    "source_account_type": "spot",
    "dest_account_type": "perps",
    "asset_symbol": "USDT",
    "amount": "1000.00"
  }'