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

# Crypto-to-Crypto Movement

> Learn how to execute cryptocurrency transactions across different chains

<Info>
  **Prerequisites**: Before implementing crypto transactions, ensure you have:

  * A verified Fern developer account with API key configured
  * An existing customer account with appropriate KYC verification
  * Crypto payment accounts (wallets) for source and destination
</Info>

## Overview

The Fern API enables seamless cryptocurrency transactions between different (supported) tokens and across multiple blockchain networks. This guide walks you through the conceptual flow of executing a crypto-to-crypto transaction.

## Transaction Types

Fern supports three types of crypto-to-crypto transactions, each serving different use cases:

**1. Crypto Transfer**: Transfer the same token between different accounts on the same blockchain (e.g., USDC → USDC on Ethereum)

**2. Crypto Bridge**: Move the same token from one blockchain to another (e.g., USDC from Ethereum → USDC on Solana)

**3. Crypto Swap**: Exchange one token for another on the same blockchain (e.g., PAXG → USDC on Solana)

<Info>
  The API flow remains consistent across all crypto-crypto transaction types - only the request parameters change.

  For more details on chains/crypto-currencies, check the [Coverage : Cryptocurrency & Chain Support](/coverage/cryptocurrency-support)
</Info>

## Transaction Flow

<Steps>
  <Step title="Set up customer and wallets">
    Ensure customer exists with required crypto payment accounts
  </Step>

  <Step title="Create quote">
    Lock in the exchange rate for 5 minutes
  </Step>

  <Step title="Execute transaction">
    Create transaction using the quote ID
  </Step>

  <Step title="Monitor status">
    Track transaction until completion
  </Step>
</Steps>

## Implementation Guide

### Step 1: Prerequisites

Before initiating a transaction, ensure you have:

1. **Customer Account** - Create a verified customer following the [Customer Creation Guide](/guides/create-and-verify-customers/api-verification)
2. **Payment Accounts** - Set up crypto wallets as described in the [Payment Accounts Guide](/guides/create-fern-wallets)

<Note>
  A single Fern crypto wallet (EVM/SVM type) can hold multiple tokens across all [supported chains](/coverage/cryptocurrency-support)
</Note>

### Step 2: Create Quote

Once the user decides to proceed, create a quote to lock in the exchange rate. Quotes are valid for 5 minutes and guarantee the rate during that window.

**Same-Chain Transfer Example:**

```json theme={null}
{
  "customerId": "customer_uuid",
  "source": {
    "sourcePaymentAccountId": "fern_crypto_wallet_payment_account_id",
    "sourcePaymentMethod": "ETHEREUM",
    "sourceCurrency": "USDC",
    "sourceAmount": "100.00"
  },
  "destination": {
    "destinationPaymentAccountId": "fern_or_external_crypto_wallet_payment_account_id",
    "destinationPaymentMethod": "ETHEREUM",
    "destinationCurrency": "USDC"
  }
}
```

<Note>
  **Source Payment Account Requirements:**

  * `sourcePaymentAccountId` is **OPTIONAL** - omitting it will make our system provide a new temp. wallet address to facilitate the transaction
  * When provided, it must be a `FERN_CRYPTO_WALLET` type payment account
</Note>

<Note>
  **Destination Payment Account Requirements:**

  * `destinationPaymentAccountId`: Fern or External crypto wallets payment accounts, can be used
</Note>

<AccordionGroup>
  <Accordion title="Cross-Chain Bridge Example">
    Moving USDC from Ethereum to Solana (without `sourcePaymentAccountId`)

    ```json theme={null}
    {
      "customerId": "customer_uuid",
      "source": {
        "sourcePaymentMethod": "ETHEREUM",
        "sourceCurrency": "USDC",
        "sourceAmount": "100.00"
      },
      "destination": {
        "destinationPaymentAccountId": "fern_or_external_crypto_wallet_payment_account_id",
        "destinationPaymentMethod": "SOLANA",
        "destinationCurrency": "USDC"
      }
    }
    ```
  </Accordion>

  <Accordion title="Crypto Swap Example">
    Swapping PAXG to USDC on Solana (using specific FERN\_CRYPTO\_WALLET):

    ```json theme={null}
    {
      "customerId": "customer_uuid",
      "source": {
        "sourcePaymentAccountId": "fern_crypto_wallet_payment_account_id",
        "sourcePaymentMethod": "SOLANA",
        "sourceCurrency": "PAXG",
        "sourceAmount": "0.05"
      },
      "destination": {
        "destinationPaymentAccountId": "fern_or_external_crypto_wallet_payment_account_id",
        "destinationPaymentMethod": "SOLANA",
        "destinationCurrency": "USDC"
      }
    }
    ```
  </Accordion>

  <Accordion title="Adding Developer Fees (Optional)">
    You can optionally charge platform fees by including the `developerFee` field:

    ```json theme={null}
    {
      "customerId": "customer_uuid",
      "source": {
        "sourcePaymentAccountId": "fern_crypto_wallet_payment_account_id",
        "sourcePaymentMethod": "ETHEREUM",
        "sourceCurrency": "USDC",
        "sourceAmount": "100.00"
      },
      "destination": {
        "destinationPaymentAccountId": "fern_or_external_crypto_wallet_payment_account_id",
        "destinationPaymentMethod": "ETHEREUM",
        "destinationCurrency": "USDC"
      },
      "developerFee": {
        "developerFeeType": "USD",
        "developerFeeAmount": "1.00"
      }
    }
    ```

    <Note>
      The `developerFee` field is completely optional. If you don't want to charge your customers, simply omit this field entirely from your request.
    </Note>
  </Accordion>
</AccordionGroup>

<Accordion title="Quote Response Fields">
  * `id` - Unique quote identifier (use this to create transaction)
  * `status` - Quote status (ACTIVE, EXPIRED, EXECUTED)
  * `sourceAmount` - Amount to be debited
  * `destinationAmount` - Amount user will receive
  * `exchangeRate` - Rate locked for this quote
  * `fernFee` - Fern's processing fee
  * `networkFee` - Blockchain network fees
  * `developerFee` - Your platform fee (if configured)
  * `expiresAt` - Quote expiration timestamp
</Accordion>

For complete api reference, see the [Create Quote API Reference](/api-reference/quotes/create).

### Step 3: Execute Transaction

After user confirmation, create a transaction using the quote ID:

**Request Body:**

```json theme={null}
{
  "quoteId": "quote_uuid",
  "correlationId": "your_internal_reference_id"
}
```

The `correlationId` is optional but recommended for tracking transactions in your system.

See the [Create Transaction API Reference](/api-reference/transactions/create-transaction) for details.

### Step 4: Monitor Transaction

Track the transaction status to update your user interface accordingly. Transaction statuses include:

* `PENDING` - Transaction created, awaiting processing
* `PROCESSING` - Transaction in progress
* `COMPLETED` - Transaction successful
* `FAILED` - Transaction failed
* `CANCELLED` - Transaction cancelled

Use the [Get Transaction API Reference](/api-reference/transactions/get-transaction) to poll for status updates.

<Warning>
  Transactions typically complete within minutes but may take longer during network congestion. Implement appropriate timeout and retry logic.
</Warning>

## Automation

For recurring transactions or dollar-cost averaging strategies, use the [Automation Rules API](/guides/automate-fund-transfers-with-automation-rules) to set up:

* **Time-based transactions**: Execute transactions on a schedule (daily, weekly, monthly)
* **Threshold-based transactions**: Trigger transactions when certain balance conditions are met

## Related Resources

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api-reference">
    Complete API documentation for all endpoints
  </Card>

  <Card title="Customer Creation" icon="user-plus" href="/guides/create-and-verify-customers/api-verification">
    Guide for onboarding customers with KYC
  </Card>

  <Card title="Payment Accounts" icon="wallet" href="/guides/create-fern-wallets">
    Managing crypto wallets and external accounts
  </Card>

  <Card title="Supported Currencies" icon="coins" href="/coverage/cryptocurrency-support">
    Full list of supported tokens and chains
  </Card>
</CardGroup>

## Support

Use the [Support](/help-and-support) page to contact us.

<Note>
  Please include the below details to make it easier for our team to debug the issue:

  * quoteId
  * transactionId
  * customerId
</Note>