Skip to main content

Swap Widget API V1 Reference

Prop NameProp TypeDefault ValueDescription
providerJsonRpcProvider or Eip1193ProviderundefinedAn EIP-1193 provider. See Web3 provider.
jsonRpcUrlMap{ [chainId: number]: string[] }JSON_RPC_FALLBACK_ENDPOINTSMapping of your JSON-RPC endpoint URLs indexed by chainId, used to provide trade quotes prior to the user connecting a wallet. If none are provided for a chain, the widget will fallback to public JSON-RPC endpoints, which are unreliable and rate-limited. See JSON-RPC Endpoints.

Optional Parameters

Prop NameProp TypeDefault ValueDescription
convenienceFeenumberundefinedOptionally, you may charge a convenience fee on top of swaps executed through your web app. The allowed range is 1 to 100 basis points paid in the output token of a swap, consistent with the Pegasys v3 Periphery contract.
convenienceFeeRecipient{[chainId: number]: string}undefinedThe address to receive the convenience fee on each network. Required if convenienceFee is provided.
defaultChainIdnumber57You may specify which chainId you want to prompt a user to connect their wallet to. See a list of all chains supported on widget.
defaultInputTokenAddress{[chainId: number]: string}string or 'NATIVE'Address of the token to be selected by default in the input field (e.g. USDC) for each network chain ID. If left empty the widget will use the native token of the connected chain as default. This can be explicitly defined by the special string 'NATIVE'. For convenience you may pass a single string instead of a chainId mapping. In this case, the widget will assume that string corresponds to an L1 Ethereum address with chaindId=1. Any addresses provided in this parameter must be included in the tokenList.
defaultInputAmountnumber0Default amount for the input field (e.g. 1 ETH). This value will respect the decimals of the defaultInputTokenAddress. This parameter is valid only if defaultInputTokenAddress is also set. This parameter is mutually exclusive with defaultOutputTokenAmount, so you may set only one of defaultInputTokenAmount and defaultOutputTokenAmount.
defaultOutputTokenAddress{[chainId: number]: string}string or undefinedAddress of the token to be selected by default in the input field (e.g. USDC) for each network chain ID. None if left empty. Any addresses provided in this parameter must be included in the tokenList.
defaultOutputAmountnumber0Default amount for the input field (e.g. 100 USDC). This value will respect the decimals of the defaultOutputTokenAddress. This parameter is mutually exclusive with defaultInputTokenAmount, so you may set only one of defaultInputTokenAmount and defaultOutputTokenAmount.
hideConnectionUIbooleanfalseHide the widget's built-in wallet connection UI, including the connected account chip & 'Connect wallet to swap' button.
localeSupportedLocaleen-USSpecifies an explicit locale to use for the widget interface. This can be set to one of the values exported by the library in SUPPORTED_LOCALES.
onConnectWalletClick() => void or () => Promise<boolean>undefinedIf passed, allows you to add custom behavior when the user clicks on the 'Connect your wallet to swap' button. To manage displaying the widget's built-in wallet connection modal, return a resolved promise with resolve(true/false).
onSwitchChain(addChainParameter: AddEthereumChainParameter) => void or Promise<void>undefinedAn integration hook called when the user tries to switch chains. If the hook returns a Promise, it is assumed the integrator is attempting to switch the chain, and no further attempts will be made. If that Promise rejects, the error will be ignored so as not to crash the widget.
onErrorErrorHandlerundefinedAn error handler which receives any Javascript errors that occur in the widget. This can be used for collecting error metrics.
onReviewSwapClick() => void or () => Promise<boolean>undefinedIf passed, allows you to add custom behavior when the user clicks on the 'review swap' button. To manage progression to the review screen (i.e. to add a pre-swap warning speedbump), return a resolved promise with resolve(true/false).
onTokenSelectorClick(f: Field) => void \| (f: Field) => Promise<boolean \| void>undefinedA click handler fired with the selected Field ('INPUT'\|'OUTPUT') when the user clicks on a token selector dropdown. To manage progression to the native token selector view (i.e. to utilize your own external token selector UI), return a resolved promise with resolve(true/false).
onTxFail(error: Error, data: any) => voidundefinedAn error handler which receives error data for on-chain transaction failures. Does not include when user cancels a transaction or if a transaction isn't able to be submitted.
onTxSubmit(txHash: string, data: any) => voidundefinedA handler that receives the transaction hash and related data when a user submits a transaction.
onTxSuccess(txHash: string, data: any) => voidundefinedA handler that receives the transaction hash and related data when a transaction succeeds on-chain.
routerUrlstringundefinedOptionally provide a base URL to your own hosted instance of the Pegasys Router API. If none is provided, the optimal trade route is computed by running the @pegasys-fi/smart-order-router package locally in the browser; this can take a few seconds to load & is slower. You also may be able to find more optimal routes using the Router API! See more about deploying the Router API.
themeThemelightThemeSpecifies a custom theme (colors, font, and border radii). See Customizing the Theme.
tokenListstringTokenInfo[]Specifies the set of tokens that appear by default in the token selector list. Accepts either a URI of a token list as defined by the Token Lists standard, or an inline array of tokens. If none is provided, the Pegasys Labs default token list will be used. See Customizing the Default Token List.
widthnumber or string360Specifies the width of the widget. If specified as a number, this is in pixels; otherwise, it is interpreted as a CSS <length> data type. Recommended width is 360px. Minimum width is 300px. See Customizing the Width.
brandedFooterbooleantrueEnables the "Powered by Pegasys" footer at the bottom of the widget.
dialogHTMLDivElementundefinedSpecifies the element to portal widget dialogs (e.g. Summary, Transaction dialogs) into.
dialogOptionsDialogOptionsundefinedSpecifies more custom dialog behavior, like transition animations.

Subscribing to Events

During the lifecycle of the swap widget, most of the events you will need are available on the web3 provider. For example, the below snippet shows how to listen for events when the wallet account changes or a new wallet connects. You can see more event examples in the MetaMask docs.

// Subscribe to messages
interface ProviderMessage {
type: string;
data: unknown;
}

ethereum.on(
'message',
handler: (message: ProviderMessage) => void
);
Questions?

Join the Discord channel to ask questions and get support from the Pegasys community.