Overview

This functionality is also only available on version 4.25.0 of the SDK and above.

Dashboard Setup

Follow these steps to enable exchange funding from Dashbaord:

1. Go to the funding tab
2. Toggle the exchange you would like to enable and click the gear icon
3. Enable the Exchange Transfer toggle for funding directly from exchange
4. Enable OAuth for the exchange: for most platforms you’ll need to complete the OAuth setup though some exchanges may let you initiate transfers via an in‑app popup without a full OAuth flow.
5. Save the settings. Note that it could take up to 5 minutes for the settings cache to refresh on your site.

SDK Views

Once enabled in Dashboard and the settings have propagated, your end users would be able to link their Exchange account to their user profile and initiate the transfer.

1. In the user profile widget, click on Deposit
2. Click on From Exchange
3. Click on the desired exchange and you will be taken immediately to the transfer flow

Headless Implementation

For developers looking to implement a headless version of the Fund from Exchange feature, you can use the useExchangeAccounts hook. This hook provides programmatic access to exchange account management, transaction history, and transfer operations.

Exchange Transfer Events

The exchangeTransfer endpoint publishes two types of events depending on the outcome of the transfer operation:

user.exchangeTransfer.success

Published when: An exchange transfer is successfully initiated.

Data payload: The complete ExchangeTransferResponse object containing:

{
  id: string;                    // UUID of the transfer
  exchangeAccountId?: string;    // UUID of the exchange account
  status?: string;               // Current status of the transaction (e.g., "pending")
  amount: number;                // The amount transferred
  currency: string;              // Chain symbol that funds are transferred in (e.g., "USDC")
  createdAt?: Date;              // Timestamp when the transfer was created
}

Example:

{
  "id": "3c04e35e-8e5a-5ff1-9155-00675db4ac02",
  "exchangeAccountId": "123456",
  "status": "pending",
  "amount": 1,
  "currency": "USDC",
  "createdAt": "2024-01-15T10:30:00.000Z"
}

user.exchangeTransfer.failed

Published when: An exchange transfer fails for any reason.

Data payload: The raw error object that caused the failure. The error can be one of several types:

Examples:

CustomError:

{
  "message": "MFA verification failed",
  "code": "TRANSFER_MFA_FAILED",
  "additionalMessages": ["Invalid MFA code provided"]
}

Generic error:

{
  "message": "Failed to execute exchange transfer"
}

Event Metadata

Both events include the following metadata:

• environmentId: The project environment ID
• userId: The ID of the user performing the transfer
• eventName: Either "user.exchangeTransfer.success" or "user.exchangeTransfer.failed"

Webhook Integration

To receive these events in real-time, you can configure webhooks in your Developer Dashboard. Select the following event types to subscribe to exchange transfer events:

• user.exchangeTransfer.success
• user.exchangeTransfer.failed

Webhook Payload Example

When configured, your webhook endpoint will receive POST requests with the following structure:

{
  "eventId": "2a92c161-3167-44ad-8fce-4c6cdaed8129",
  "messageId": "5a2a5360-bb7e-4ea6-9bd3-0146bf2f734f",
  "webhookId": "a86acea4-e050-4846-8e4f-0ae039f6e37c",
  "eventName": "user.exchangeTransfer.success",
  "environmentId": "123e4567-e89b-12d3-a456-426614174000",
  "environmentName": "sandbox",
  "timestamp": "2024-01-15T10:30:59.210Z",
  "data": {
    "id": "3c04e35e-8e5a-5ff1-9155-00675db4ac02",
    "exchangeAccountId": "123456",
    "status": "pending",
    "amount": 1,
    "currency": "USDC",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

Event Handling Best Practices

1. Idempotency: Use the messageId field to handle duplicate events safely
2. Status Tracking: Monitor transfer status changes to update your application state
3. Error Handling: Implement proper error handling for failed transfers
4. Signature Validation: Always validate webhook signatures using your webhook secret

For more information on webhook setup and security, see the Webhooks documentation.