Skip to main content
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

​
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)
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

​
Transaction Flow

1

Set up customer and wallets

Ensure customer exists with required crypto payment accounts
2

Create quote

Lock in the exchange rate for 5 minutes
3

Execute transaction

Create transaction using the quote ID
4

Monitor status

Track transaction until completion

​
Implementation Guide

​
Step 1: Prerequisites

Before initiating a transaction, ensure you have:
  1. Customer Account - Create a verified customer following the Customer Creation Guide
  2. Payment Accounts - Set up crypto wallets as described in the Payment Accounts Guide
A single Fern crypto wallet (EVM/SVM type) can hold multiple tokens across all supported chains

​
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: 
{
  "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"
  }
}
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
Destination Payment Account Requirements:
  • destinationPaymentAccountId: Fern or External crypto wallets payment accounts, can be used
Moving USDC from Ethereum to Solana (without sourcePaymentAccountId)
{
  "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"
  }
}
Swapping PAXG to USDC on Solana (using specific FERN_CRYPTO_WALLET):
{
  "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"
  }
}
You can optionally charge platform fees by including the developerFee field:
{
  "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"
  }
}
The developerFee field is completely optional. If you don’t want to charge your customers, simply omit this field entirely from your request.
  • 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
For complete api reference, see the Create Quote API Reference.

​
Step 3: Execute Transaction

After user confirmation, create a transaction using the quote ID: Request Body: 
{
  "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 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 to poll for status updates.
Transactions typically complete within minutes but may take longer during network congestion. Implement appropriate timeout and retry logic.

​
Automation

For recurring transactions or dollar-cost averaging strategies, use the Automation Rules API 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

API Reference

Complete API documentation for all endpoints

Customer Creation

Guide for onboarding customers with KYC

Payment Accounts

Managing crypto wallets and external accounts

Supported Currencies

Full list of supported tokens and chains

​
Support

Use the Support page to contact us.
Please include the below details to make it easier for our team to debug the issue:
  • quoteId
  • transactionId
  • customerId