Swap Widget API V1 Reference

Recommended Parameters

Prop Name	Prop Type	Default Value	Description
provider	JsonRpcProvider or Eip1193Provider	undefined	An EIP-1193 provider. See Web3 provider.
jsonRpcUrlMap	{ [chainId: number]: string[] }	JSON_RPC_FALLBACK_ENDPOINTS	Mapping 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 Name	Prop Type	Default Value	Description
convenienceFee	number	undefined	Optionally, 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}	undefined	The address to receive the convenience fee on each network. Required if convenienceFee is provided.
defaultChainId	number	57	You 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.
defaultInputAmount	number	0	Default 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 undefined	Address 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.
defaultOutputAmount	number	0	Default 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.
hideConnectionUI	boolean	false	Hide the widget's built-in wallet connection UI, including the connected account chip & 'Connect wallet to swap' button.
locale	SupportedLocale	en-US	Specifies 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>	undefined	If 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>	undefined	An 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.
onError	ErrorHandler	undefined	An 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>	undefined	If 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>	undefined	A 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) => void	undefined	An 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) => void	undefined	A handler that receives the transaction hash and related data when a user submits a transaction.
onTxSuccess	(txHash: string, data: any) => void	undefined	A handler that receives the transaction hash and related data when a transaction succeeds on-chain.
routerUrl	string	undefined	Optionally 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.
theme	Theme	lightTheme	Specifies a custom theme (colors, font, and border radii). See Customizing the Theme.
tokenList	string	TokenInfo[]	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.
width	number or string	360	Specifies 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.
brandedFooter	boolean	true	Enables the "Powered by Pegasys" footer at the bottom of the widget.
dialog	HTMLDivElement	undefined	Specifies the element to portal widget dialogs (e.g. Summary, Transaction dialogs) into.
dialogOptions	DialogOptions	undefined	Specifies 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.