swapToken

Open the swap form with pre-filled tokens. The user will be able to modify the swap before executing the transaction.

Usage

import { sdk } from '@farcaster/miniapp-sdk'
 
await sdk.actions.swapToken({ 
  sellToken,
  buyToken,
  sellAmount,
  display: {
    headline: "5,000,000 tokens",
    subline: "Required to participate",
  },
})

Parameters

sellToken (optional)

• Type: string

CAIP-19 asset ID

For example, Base USDC: eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

buyToken (optional)

• Type: string

CAIP-19 asset ID

For example, OP ETH: eip155:10/native

sellAmount (optional)

• Type: string

Sell token amount, as numeric string

For example, 1 USDC: 1000000

display (optional)

• Type: { headline?: string; subline?: string }

Optional copy for the host swap UI so required amounts and outcomes are easy to see before the user confirms. headline is intended for a prominent primary line (for example formatted token totals); subline can explain what the swap is for. Farcaster clients that support this field show it in the swap sheet; others ignore it. Numeric sellAmount remains the source of truth for the transaction.

Return Value

type SwapTokenDisplayHints = {
  headline?: string;
  subline?: string;
};
 
type SwapTokenDetails = {
  /**
   * Array of tx identifiers in order of execution.
   * Some swaps will have both an approval and swap tx.
   */
  transactions: `0x${string}`[];
};
 
type SwapTokenErrorDetails = {
  /**
   * Error code.
   */
  error: string;
  /**
   * Error message.
   */
  message?: string;
};
 
export type SwapErrorReason = "rejected_by_user" | "swap_failed";
 
export type SwapTokenResult =
  | {
      success: true;
      swap: SwapTokenDetails;
    }
  | {
      success: false;
      reason: SwapErrorReason;
      error?: SwapTokenErrorDetails;
    };