Skip to main content

​
Overview

The Crocante Swap feature allows you to instantly convert one cryptocurrency to another without leaving the platform. The swap functionality uses the SwapModal component and integrates with the useSwapData and useTokenSwap hooks for real-time conversion rates and execution.

​
Accessing the Swap Feature

1

Navigate to Portfolio

From your portfolio dashboard, locate the action buttons in the header area.
2

Click Swap

Click the Swap button (identified by the swap icon) to open the swap modal. This button is managed by the SwapAction component.
3

Swap Modal Opens

The SwapModal component (domain/portfolio/components/header-actions/swap-modal.tsx) appears with input fields for conversion.

​
Performing a Token Swap

​
Step-by-Step Swap Process

1

Select Source Token

In the Send field, choose the cryptocurrency you want to convert from. The dropdown shows:
  • Token symbol and name
  • Token icon
  • Your available balance for that token
The token list is populated by useSwapData which fetches available balances via useAvailables.
2

Select Destination Token

In the Receive field, select the cryptocurrency you want to receive. Only compatible conversion pairs are shown based on useConversionPairs data.
You cannot swap a token for itself. The Swap button will be disabled if source and destination tokens are the same.
3

Enter Amount

Type the amount you want to swap in the Send field. You can:
  • Manually enter an amount
  • Click MAX to use your full available balance
  • Click MIN to use the minimum swap amount (if applicable)
4

Review Conversion

As you type, the Receive field automatically calculates the amount you’ll receive using real-time conversion rates from useTokenSwap.The conversion uses the convertTo function:
const convertedReceive = convertTo(tokenValue);
5

Review Fees

Below the Swap button, you’ll see the transaction fee displayed:
(Fee: 0.5 USDC)
The fee is calculated as:
Number(commissionRate) * Number(value)
6

Execute Swap

Click Swap to execute the transaction. The button shows:
  • Swap: When ready to execute
  • Swapping…: During transaction processing (with loading spinner)
The swap is executed via the handleSwap function with your user ID.

​
Understanding Conversion Rates

​
Real-Time Rate Updates

The swap modal uses the useTokenSwap hook to provide:
  • Live Conversion Rates: Fetched from /api/conversion-pairs endpoint
  • Bidirectional Conversion: Calculate from source-to-destination or destination-to-source
  • Automatic Recalculation: Rates update when you switch tokens or change focus between fields
The conversion rate automatically refreshes at intervals defined by POLL_AVAILABLES_INTERVAL to ensure you always get current market rates.

​
Conversion Functions

Two conversion functions are available:
  1. convertTo(value): Converts from source token to destination token
  2. convertFrom(value): Converts from destination token back to source token
// User edits the Send field
const handleChangeValue = (tokenValue: string) => {
  setValue(tokenValue);
  if (tokenValue) {
    const convertedReceive = convertTo(tokenValue);
    setValueReceive(convertedReceive);
  }
};

​
Swap Token Direction

​
Reverse the Swap

You can quickly reverse the swap direction without re-entering amounts:
1

Click Swap Direction Button

Click the circular button with the arrow icon between the Send and Receive fields.
2

Tokens Switch

The source and destination tokens swap positions, and amounts are recalculated:
handleSwapSelectors(tokenLabel, tokenSwapLabel);
3

Amounts Update

The conversion amounts automatically update based on the reversed direction.
The swap direction button shows different icons:
  • Arrow Down: Default state
  • Arrow Up-Down: On hover, indicating the swap action

​
Validation and Requirements

​
Swap Conditions

The Swap button is only enabled when ALL conditions are met:
  1. Valid Amount: Amount is greater than zero and within your available balance
  2. Minimum Amount: Meets the minimum swap amount (minAmount) if specified
  3. Different Tokens: Source and destination tokens are different
  4. Commission Rate Available: Fee structure is loaded
  5. Conversion Rate Available: Live rates are fetched successfully
const conditionsSuccess =
  isValidValue &&
  assetSelector.options[assetSelector.selectedIndex]?.id !==
    assetSwapSelector.options[assetSwapSelector.selectedIndex]?.id &&
  commissionRate &&
  minAmount;

​
Validation Checks

The useValueVerifier hook validates your input:
  • Minimum: Cannot be below the minimum swap amount
  • Maximum: Cannot exceed your available balance
  • Non-Zero: Must enter an amount greater than zero
If your amount exceeds your available balance, the Swap button will be disabled and you cannot proceed.

​
Swap Fees

​
Fee Structure

Crocante charges a commission on each swap:
  • Fee Display: Shown below the Swap button in the destination token
  • Fee Calculation: commissionRate × swap amount
  • Fee Token: Always charged in the destination (receive) token
The fee percentage varies by token pair. Check the fee display before confirming your swap.

​
Advanced Features

​
Dual Input Editing

You can edit either the Send or Receive field:
When you edit the Send field:
  1. Type your desired send amount
  2. The Receive field automatically calculates what you’ll get
  3. Fees are deducted from the receive amount
The modal tracks which field has focus using inputReceiveFocused state to determine which calculation to perform.

​
Quick Amount Selection

MAX Button

Click MAX in the Send field to use your entire available balance for the swap.

MIN Button

Click MIN (when available) to set the minimum required swap amount.

​
Conversion Pairs

​
Supported Pairs

The available conversion pairs are determined by:
  • Backend Configuration: /api/conversion-pairs endpoint
  • Dynamic Loading: Pairs update based on platform liquidity
  • Token Availability: You can only swap tokens you currently hold
The useConversionPairs hook fetches available pairs: 
conversionPairs[selectedTokenFrom]?.forEach((currency) => {
  // Build list of destination tokens
});
If a destination token is not showing in the dropdown, that conversion pair may not be currently supported or available.

​
Transaction Processing

​
Swap Status Indicators

1

Ready to Swap

Button displays: Swap with fee information below
2

Processing

Button displays: Swapping… with animated spinner
<Loader2 className="w-5 h-5 text-muted-foreground animate-spin" />
3

Completion

Modal closes and your portfolio updates with new balances
Do not close the modal while a swap is processing. Wait for the transaction to complete.

​
Best Practices

Check Rates

Compare the conversion rate with external markets to ensure competitive pricing.

Review Fees

Always check the fee amount before confirming your swap - it varies by token pair.

Sufficient Balance

Ensure you have enough balance to cover both the swap amount and any fees.

Network Updates

After swapping, allow a moment for your portfolio balances to refresh.

​
Troubleshooting

​
Swap Button Disabled

Check these conditions:
  • Amount is greater than zero
  • Amount doesn’t exceed available balance
  • Source and destination tokens are different
  • Amount meets minimum swap requirement
  • Conversion rates have loaded (no loading spinner)

​
Conversion Pair Not Available

  • Try swapping through an intermediate token (e.g., BTC → USDC → ETH)
  • Check if the destination token is currently supported
  • Contact support if a previously available pair is missing

​
Incorrect Amounts Displayed

  • Wait for conversion rates to load (indicated by loading spinner)
  • Refresh the page to reload latest rates
  • Check if you’re editing the correct field (Send vs. Receive)

​
Swap Failed

  • Verify you have sufficient balance
  • Ensure your session hasn’t expired
  • Check network connectivity
  • Try again in a few moments
  • Contact support if the issue persists

Managing Assets

View your portfolio and monitor balances after swapping

Deposit & Withdrawal

Add more funds to swap or withdraw converted assets

Build docs developers (and LLMs) love

Get started for freeTalk to us