Overview

/**
* List of supported chains and their router addresses.
*/
supportedChains: CHAIN_MAP[];

/**
* Returns the supported token list for a given chain.
* @param chainId Chain ID.
* @returns Map of lowercased symbol -> Token.
*/
supportedTokens(chainId: number): Promise<Map<string, Token>>;

/**
* Returns supported protocols.
* @param chainId Chain ID.
* @returns Mapping of AMM name -> protocol identifier.
*/
supportedProtocols(chainId: number): Promise<Record<string, ProtocolId>>;

/**
* Fetches the best route from the API.
* @param params Route parameters object.
* @returns Route response.
* @throws Error if the chain is not supported.
*/
getBestRoute(
    params: getBestRouteParams,
): Promise<RouteResponse>;

type getBestRouteParams = {
  amount: AmountType;
  tokenInAddress: string;
  tokenOutAddress: string;
  chainId: number;
  options?: Partial<RouteOverrides>;
  integrationData?: IntegrationData;
};

type IntegrationData = {
  integratorAddress: string;
  integratorFeePercentageBps?: number; // 0-500, maximum 5%
  integratorSurplusPercentageBps?: number; // 0-5000, maximum 50%
};

type RouteOverrides = {
  reverse: boolean;
  direct: boolean;
  excludeProtocols: number[]; // Array of protocol IDs
};

/**
* Legacy method that builds a route and calldata to prepare a transaction.
* Note: This will be deprecated; prefer `buildRouteAndCalldata`.
* @param params Transaction parameters object.
* @returns Starknet `Call` or EVM calldata/transaction structure.
*/
buildTransaction(
    params: buildTransactionParams,
): Promise<Call | unknown>;

type buildTransactionParams = {
  inputAmount: AmountType;
  tokenInAddress: string;
  tokenOutAddress: string;
  slippage: number;
  destination: string;
  chainId: number;
  options?: Partial<RouteOverrides>;
  integrationData?: IntegrationData;
};

/**
* Returns the best route and executable calldata in a single call.
* @param params Route and calldata parameters object.
* @returns Route and calldata structure (includes Starknet swap call when applicable).
*/
buildRouteAndCalldata(
    params: buildRouteAndCalldataParams,
): Promise<RouteAndCalldataResponse>;

type buildRouteAndCalldataParams = {
  inputAmount: AmountType;
  tokenInAddress: string;
  tokenOutAddress: string;
  slippage: number;
  destination: string;
  chainId: number;
  options?: Partial<RouteOverrides>;
  integrationData?: IntegrationData;
};

/**
* Builds Starknet approve call parameters.
* @param amount Amount to approve (will be converted to hex).
* @param tokenAddress ERC-20 token address.
*/
buildApproveStarknet(amount: AmountType, tokenAddress: string): Promise<Call>;

/**
* Performs EVM approve if needed and returns the result.
* @param amount Amount to approve.
* @param tokenAddress ERC-20 token address.
* @param account Wallet/signer used for the transaction.
* @param chainId Chain ID.
* @returns `true` if allowance is sufficient or approve succeeded.
*/
buildApproveEVM(
    amount: AmountType,
    tokenAddress: string,
    account: Wallet,
    chainId?: number,
): Promise<boolean>;

/**
* Fetches best routes in batch for multiple inputs (Starknet and Base for now).
* @param amounts List of input amounts.
* @param tokenInAddresses Input token addresses.
* @param tokenOutAddresses Output token addresses.
* @param chainId Chain ID.
* @param options Optional route parameters.
* @returns List of route responses.
*/
getBestRouteBatch(
    amounts: bigint[] | string[] | number[] | BigNumberish[],
    tokenInAddresses: string[],
    tokenOutAddresses: string[],
    chainId: number,
    options?: Partial<RouteOverrides>,
): Promise<RouteResponse[]>;

/**
* Builds calldata/call list for batch transactions (Starknet for now).
* @param inputAmounts Input amounts.
* @param tokenInAddresses Input token addresses.
* @param tokenOutAddresses Output token addresses.
* @param slippage Slippage percentage.
* @param destination Receiver address.
* @param chainId Chain ID.
* @param options Optional parameters.
* @returns Array of Starknet `Call`s or chain-specific payload.
*/
buildBatchTransaction(
    inputAmounts: AmountType[],
    tokenInAddresses: string[],
    tokenOutAddresses: string[],
    slippage: number,
    destination: string,
    chainId: number,
    options?: Partial<RouteOverrides>,
): Promise<Call[] | unknown>;