@perawallet/swap/dist/index.d.mts

Algorand swap utilities and widget integration

import { Transaction } from 'algosdk';

/** Search param keys that can be passed to the widget for configuration */
declare enum SwapWidgetSearchParamKey {
    /** When set to `true`, the widget will always try to
     * communicate with the parent app to get the txns signed */
    USE_PARENT_SIGNER = "useParentSigner",
    /** Should be passed if `useParentSigner` is `true`, (otherwise it will be ignored)
     * the widget will use this address as the signer of the txns */
    ACCOUNT_ADDRESS = "accountAddress",
    /** The preferred Algorand network that will be used by the widget */
    NETWORK = "network",
    /** The preferred theme of the widget */
    THEME = "theme",
    /** ID of the asset to be used as the input asset for the swap, default = ALGO */
    ASSET_IN = "assetIn",
    /** ID of the asset to be used as the output asset for the swap, default = USDC */
    ASSET_OUT = "assetOut",
    /** Background color of the widget, default = #FFFFFF */
    IFRAME_BACKGROUND = "iframeBg"
}
type WidgetAppTheme = "light" | "dark";
type WidgetNetwork = "mainnet" | "testnet";
interface WidgetConfig {
    /** The preferred Algorand network that will be used by the widget */
    network?: WidgetNetwork;
    /** The preferred theme of the widget */
    theme?: WidgetAppTheme;
    /** ID of the asset to be used as the input asset for the swap, default = ALGO */
    assetIn?: string | number;
    /** ID of the asset to be used as the output asset for the swap, default = USDC */
    assetOut?: string | number;
    /** Background color of the widget, default = #FFFFFF */
    iframeBg?: string;
    /** When set to `true`, the widget will always try to
     * communicate with the parent app to get the txns signed */
    useParentSigner?: boolean;
    /** Should be passed if `useParentSigner` is `true`, (otherwise it will be ignored)
     * the widget will use this address as the signer of the txns */
    accountAddress?: string;
}
interface WidgetThemeColorVariables {
    theme: WidgetAppTheme | null;
    iframeBg: string | null;
}
type WidgetThemeVariables = WidgetThemeColorVariables;
type SwapProvider = "tinyman" | "tinyman-swap-router" | "vestige-v4";
type SwapType = "fixed-input" | "fixed-output";
type VerificationTier = "verified" | "unverified" | "suspicious";
interface Asset {
    asset_id: number;
    name: string;
    logo: string;
    unit_name: string;
    fraction_decimals: number;
    usd_value: string | null;
    is_verified: boolean;
    verification_tier: VerificationTier;
    type: "standard_asset" | "collectible" | "dapp_asset";
}
interface SwapQuote {
    id: number;
    quote_id_str: string;
    provider: SwapProvider;
    swap_type: SwapType;
    swapper_address: string;
    asset_in: Asset;
    asset_out: Asset;
    amount_in: string;
    amount_in_with_slippage: string;
    amount_in_usd_value: null | string;
    amount_out: string;
    amount_out_with_slippage: string;
    amount_out_usd_value: null | string;
    slippage: string;
    price: string;
    price_impact: string;
    pera_fee_amount: string;
    exchange_fee_amount: string;
}
interface CreateQuoteBody {
    providers: SwapProvider[];
    swapper_address: string;
    swap_type: SwapType;
    asset_in_id: number;
    asset_out_id: number;
    amount: string;
    slippage: string;
}
interface SwapTransactionGroup {
    purpose: "opt-in" | "swap" | "fee";
    transaction_group_id: string;
    transactions: string[];
    signed_transactions: string[];
}
interface PrepareTransactionsResponse {
    swap_id: number;
    swap_version: string;
    transaction_groups: SwapTransactionGroup[];
}
interface UpdateSwapStatusBody {
    status: "failed" | "in_progress";
    submitted_transaction_ids?: string[];
    reason?: "other" | "user_cancelled" | "invalid_submission" | "blockchain_error";
    platform?: string;
    swap_version?: "v1" | "v2";
}
interface GetAssetsResponse {
    next: string | null;
    previous: string | null;
    results: Asset[];
}
interface TxnSignRequestMessage {
    message: {
        type: 'TXN_SIGN_REQUEST';
        txGroups: Uint8Array[][];
    };
}
interface TxnSignResponseMessage {
    message: {
        type: 'TXN_SIGN_RESPONSE';
        signedTxns: Uint8Array[];
    };
}
interface FailedTxnSignMessage {
    message: {
        type: 'FAILED_TXN_SIGN';
        error: Error;
    };
}
interface TxnSignRequestTimeoutMessage {
    message: {
        type: 'TXN_SIGN_REQUEST_TIMEOUT';
    };
}
interface SwapSuccessMessage {
    message: {
        type: 'SWAP_SUCCESS';
        data: Uint8Array[];
    };
}
type WidgetMessage = TxnSignRequestMessage | TxnSignResponseMessage | FailedTxnSignMessage | TxnSignRequestTimeoutMessage | SwapSuccessMessage;

/**
 * PeraSwap class for managing swap operations and widget generation
 */
declare class PeraSwap {
    private network;
    private baseURL;
    private referrerUrl?;
    constructor(network?: 'mainnet' | 'testnet', referrerUrl?: string);
    /**
     * Update the network for all subsequent operations
     */
    updateNetwork(network: 'mainnet' | 'testnet'): void;
    /**
     * Get the current network
     */
    getNetwork(): 'mainnet' | 'testnet';
    /**
     * Create a swap quote
     */
    createQuote(body: CreateQuoteBody, signal?: AbortSignal): Promise<{
        results: SwapQuote[];
    }>;
    /**
     * Update the status of a swap
     */
    updateSwapStatus(swapId: string, body: UpdateSwapStatusBody): Promise<any>;
    /**
     * Prepare transactions for a swap
     */
    prepareTransactions(quoteId: string, depositAddress?: string): Promise<PrepareTransactionsResponse>;
    /**
     * Get available assets for swapping
     */
    getAvailableAssets(params: {
        asset_in_id: number;
        q?: string;
    }): Promise<{
        results: Asset[];
    }>;
    /**
     * Get assets by IDs or search query
     */
    getAssets(params: {
        asset_ids?: string[];
        q?: string;
    }): Promise<GetAssetsResponse>;
    /**
     * Get ALGO price in USD
     */
    getAlgoPrice(): Promise<{
        exchange_price: string;
    }>;
    /**
     * Get asset information by ID
     */
    getAsset(assetId: number): Promise<Asset | null>;
    /**
     * Search for assets by name
     */
    searchAssets(query: string): Promise<Asset[]>;
}

interface WidgetControllerConfig {
    onTxnSignRequest?: (data: {
        txGroups: Transaction[][];
    }) => Promise<Uint8Array[]>;
    onTxnSignRequestTimeout?: () => void;
    onSwapSuccess?: (response: Uint8Array[]) => void;
}
declare class WidgetController {
    private config;
    constructor(config?: WidgetControllerConfig);
    /**
     * Generate a URL for the Pera Swap Widget iframe
     */
    static generateWidgetUrl(config?: WidgetConfig): string;
    /**
     * Create an iframe element with the swap widget
     */
    static createWidgetIframe(config?: WidgetConfig, options?: {
        width?: string;
        height?: string;
        className?: string;
        id?: string;
    }): HTMLIFrameElement;
    /**
     * Send message to widget iframe
     */
    static sendMessageToWidget({ data, targetWindow }: {
        data: {
            message: {
                type: string;
                [key: string]: unknown;
            };
        };
        targetWindow?: Window | null;
    }): void;
    /**
     * Add event listeners for widget communication
     */
    addWidgetEventListeners(): void;
    /**
     * Remove event listeners
     */
    removeWidgetEventListeners(): void;
    /**
     * Handle messages from the widget
     */
    private handleMessage;
}

export { type Asset, type CreateQuoteBody, type FailedTxnSignMessage, type GetAssetsResponse, PeraSwap, type PrepareTransactionsResponse, type SwapProvider, type SwapQuote, type SwapSuccessMessage, type SwapTransactionGroup, type SwapType, SwapWidgetSearchParamKey, type TxnSignRequestMessage, type TxnSignRequestTimeoutMessage, type TxnSignResponseMessage, type UpdateSwapStatusBody, type VerificationTier, type WidgetAppTheme, type WidgetConfig, WidgetController, type WidgetControllerConfig, type WidgetMessage, type WidgetNetwork, type WidgetThemeColorVariables, type WidgetThemeVariables };