dHEDGE Trading Widget API Docs

Get started

Requirements:

Widget library has some vital peerDependencies as a core tool stack. Make sure having all those dependencies installed in app before starting the integration:

"@tanstack/react-query": "^5.28.4",
"react": ">=18.2.0",
"viem": "^2.8.14",
"wagmi": "^2.5.11"

1. Installation:

npm i @dhedge/trading-widget

2. Providers hierarchy

import { WagmiProvider } from 'wagmi';
import { TradingPanelProvider, TradingWidget } from '@dhedge/trading-widget';

• Setup Wagmi Provider on top level or use existing one in your app
• Setup TradingPanelProvider
• Setup TradingWidget

3. Minimum required config

See bare minimum setup example: packages/trading-widget/src/examples/simple-example.tsx

4. Styling

import '@dhedge/trading-widget/style.css'

Initially widget takes full parent width

See TradingWidget -> theme config to manage customization

API

TradingPanelProvider

Top level provider component. Headless part of trading logic. API handles params to setup initialState and actions. See below for more details

| name | type | default value | description | |-----------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|-----------------------------------------------------------------------------------| | onUpdatePoolConfigDepositMethod | (payload: { address: Address; method: 'deposit' \| 'depositWithCustomCooldown' }) => void | undefined | triggers on deposit method change | | onUpdateSendTokenInput | (payload: Partial<{ address: Address; symbol: string; value: string; decimals: number; isLoading?: boolean }>) => void | undefined | triggers on send token change | | onUpdateTradingSettings | (payload: Partial<{ slippage: number \| 'auto'; minSlippage?: number isInfiniteAllowance: boolean; isMultiAssetWithdrawalEnabled: boolean; isMaxSlippageLoading: boolean }>) => void | undefined | triggers on trading settings change | | onSetTradingType | (payload: 'deposit' \| 'withdraw') => void | undefined | triggers on trading type change | | onUpdateTradingMeta | (payload: Partial<{ approvingStatus: 'pending' \| 'success' }>) => void | undefined | triggers on trading meta change | | onUpdateTradingModal | (payload: Partial<{ isOpen: boolean; status: 'Success' \| 'None' \| 'Mining' \| 'Wallet' }>) => void | undefined | triggers on trading modal change | | onUpdateTransactions | (payload: AddTransaction | UpdateTransaction | RemoveTransaction) => void | undefined | triggers on transaction action change | | onUpdateEntryFee | (payload: Partial<Record<DepositMethodName, number>>) => void | undefined | triggers on transaction action change | | onTransactionError | (error: Error, action: TransactionAction | undefined, chainId?: ChainId, txHash?: Address) => void | undefined | triggers on transaction error | | onTransactionSuccess | (data: WaitForTransactionReceiptReturnType, action: TransactionAction | undefined, link?: string) => void | undefined | triggers on transaction success | | onTransactionEstimationError | (error: EstimationError, address: Address, chainId?: ChainId, account?: Address) => void | undefined | triggers on transaction estimation error | | onTokenSelector | (payload: { isOpen: boolean; entity: 'token' \| 'pool' }) => void | undefined | triggers on token selector change | | onLog | (eventName: string, payload?: Record<string, unknown>) => void | undefined | triggers on log event | | onSimulateTransaction | (payload: { chainId: ChainId; from: Address: to: Address; input: string; gas: number; value?: string }) => Promise<{ link?: string; simulation: { status: boolean; error_message: string } } | null> | undefined | triggers to simulate transaction and get error details after failed tx estimation |

Source: packages/trading-widget/src/core-kit/providers/index.tsx

Default values: undefined

| name | type | default value | description | |--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------| | poolAddress | Address | AddressZero | Current active pool address | | poolConfigMap | Record<Address, PoolConfig> | {} | Map of pool configs available for trading | | settings | { slippage: number \| 'auto'; minSlippage?: number; isInfiniteAllowance: boolean; isMultiAssetWithdrawalEnabled: boolean; isMaxSlippageLoading: boolean } | { slippage: 'auto'; isInfiniteAllowance: false; isMultiAssetWithdrawalEnabled: true; isMaxSlippageLoading: false } | Panel settings | | type | 'deposit' | 'withdraw' | 'deposit' | Trading type | | input | { sendToken: { address: Address; symbol: string; value: string; decimals: number; isLoading?: boolean }; receiveToken: { address: Address; symbol: string; value: string; decimals: number; isLoading?: boolean } } | poolConfigMap[poolAddress] | Send/receive tokens pair | | entryFee | { deposit: number; depositWithCustomCooldown: number; } | { deposit: 0; depositWithCustomCooldown: 0.1 } | Entry fee config map | | meta | { approvingStatus?: 'pending' \| 'success' } | {} | Trading meta info | | modal | { isOpen: boolean; status: 'Success' \| 'None' \| 'Mining' \| 'Wallet'; action: 'deposit' \| 'withdraw' \| 'approve \| 'oraclesUpdate'; link?: string; sendToken: TradingToken | null; receiveToken: TradingToken | null } | { isOpen: false,status: 'None', receiveToken: null, sendToken: null } | Trading modal state | | transactions | { action: 'deposit' \| 'withdraw' \| 'approve'; symbol: string; chainId: ChainId; txHash?: Address }[] | [] | Pending transactions | | poolFallbackData | { address: Address; managerLogicAddress?: Address; poolCompositions: PoolComposition[]; tokenPrice?: string; apy?: { value: number; currency: 'USD' \| 'ETH' } } | { address: AddressZero } | Current active pool fallback data to override or extend contract's response |

Source: packages/trading-widget/src/core-kit/providers/index.tsx

Default values: packages/trading-widget/src/core-kit/providers/index.tsx

TradingWidget

UI configuration provider. Manages params to configure custom styling, components, translations and basic trading params. Decomposed into config, components, theme and translation params. See below for more details

params

| name | type | default value | description | |------------------------------------|----------------------------------------------------------------|------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------| | isGeoBlocked | boolean | false | Restricts depositing action button and conditionally renders GeoBlockAlert component | | depositQuoteDiffWarningThreshold | number | 1 | Deposit slippage absolute percent value warning threshold, Affects styling to warn user | | depositQuoteDiffErrorThreshold | number | 3 | Deposit slippage absolute percent value error threshold, Affects styling to warn user | | defaultDepositSlippage | number | 0 | Initial deposit slippage absolute percent. Further adjustments are available in panel settings | | defaultDepositSlippageScale | number[] | [0] | Initial deposit slippage absolute percent. Further adjustments are available in panel settings | | defaultWithdrawSlippageScale | number[] | [0.1, 0.3, 0.5, 1, 1.5, 3] | Initial withdraw slippage absolute percent. Further adjustments are available in panel settings | | defaultLockTime | string | '24 hours' | Formatted default deposit lock time to be displayed in panel (Long lockup period is used to bypass entry fee and can be managed in panel settings) | | customLockTime | string | '15 minutes' | Formatted custom deposit lock time alternative to be displayed in panel | | stablePrecision | number | 3 | Number of decimals to be displayed in stables (e.g USDC balance) | | defaultPrecision | number | 6 | Number of decimals to be displayed in token values | | stakingChainId | number | 10 (Optimism) | ChainId to be used in staking logic | | termsOfUseAccepted | boolean | true | Requires user to confirm terms of use by rendering DepositTermsOfUse component before deposit action | | standalone | boolean | true | Handles token selection in SPA mode | | chainConfig | Partial<Record<ChainId, { name: string; iconPath: string }>> | {} | Sets map of chain name and iconPath |

actions

| name | type | default value | description | |--------------------------------------|------------------------------------------------------------------|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | onConnect | () => void | () => {} | Widget has built-in Connect Wallet action button that triggers onConnect callback assuming starting of abstract wallet connection process. After all the only requirement is to get connected wallet inside wagmi's useAccount hook to make trading operations possible | | onAcceptTermsOfUse | () => void | () => {} | Callback is triggered after user's approval of Terms of Use statements assuming switching of external config.termsOfUseAccepted param to true state |

Source: packages/trading-widget/src/trading-widget/providers/config-provider

Default values: packages/trading-widget/src/trading-widget/providers/config-provider/config-provider.defaults.ts

| name | type | default value | description | |-----------------------|-------------------------------------|---------------|-----------------------------------------------------------------------------------------------------------------| | GeoBlockAlert | ComponentType | undefined | Component replaces deposit button while isGeoBlocked config param is set to true | | DepositMetaInfo | ComponentType | undefined | Component is injected into deposit meta part of widget layout nearby TransactionOverviewDisclosure | | WithdrawMetaInfo | ComponentType | undefined | Component is injected into withdraw meta part of widget layout nearby WithdrawTransactionOverviewDisclosure | | ExtraActionButton | ComponentType | undefined | Component is injected below deposit action button and rendered if isGeoBlocked config param is set to false | | Image | ComponentType | <img> | Component optionally can be used to pass nextjs Image component to be used for assets rendering | | LogoSpinner | ComponentType<SVGProps> | <Spinner> | Component is injected into widget pending transaction overlay. Assume using of spinning animation | | DepositTermsOfUse | ComponentType | undefined | Component is injected into TermsOfUseOverlay to extend default terms of use statement points |

Source: packages/trading-widget/src/trading-widget/providers/component-provider/component-provider.tsx

Default values: undefined

global

color

path: global.color[name]

| name | type | default value | description | |----------------------------|------------|----------------------------------------------|---------------------------------------| | colorTextPrimary | string | #ffffff | Primary text color | | colorTextPrimaryHover | string | #ffffffCC | Primary hover text color | | colorBorderPrimary | string | global?.color?.colorTextPrimary ?? #ffffff | Primary border color | | colorTextSecondary | string | #9DA2AD | Secondary text color | | colorBgPrimary | string | #1B2432 | Primary bg color | | colorBgSecondary | string | #2B313E | Secondary bg color | | colorTextAccent | string | #ffffff | Accent text color | | colorTextAccentHover | string | #ffffffCC | Accent hover text color | | colorBgAccentFrom | string | #73D393 | Accent bg gradient from color | | colorBgAccentTo | string | #34855E | Accent bg gradient to color | | colorBgAccentFromHover | string | #73D393CC | Accent hover bg gradient from color | | colorBgAccentToHover | string | #162435 | Accent hover bg gradient to color | | colorTextNeutral | string | #9DA2AD80 | Neutral text color | | colorBgNeutral | string | #9DA2AD33 | Neutral bg color | | colorTextLoading | string | #ffffff99 | Loading text color | | colorTextError | string | #EF4444 | Error text color | | colorTextWarning | string | #AFA58D | Warning text color | | colorIcon | string | global?.color?.colorTextPrimary ?? #ffffff | Warning text color |

size

path: global.size[name]

| name | type | default value | description | |------------------------|--------------|----------------------------------------------|------------------------| | gap | string | 0.25rem | General flex gap | | spacer | string | 4px | General spacer | | fontSizeBase | string | 16px | Font size base | | lineHeightBase | string | 24px | Line height base | | fontSizeXs | string | 12px | Font size xs | | lineHeightXs | string | 16px | Line height xs | | fontSizeSm | string | 14px | Font size sm | | lineHeightSm | string | 20px | Line height sm | | fontSizeLg | string | 18px | Font size lg | | lineHeightLg | string | 28px | Line height lg | | iconSize | string | 20px | Icon size base | | iconSizeSm | string | 24px | Icon size sm | | iconSecondarySize | string | 16px | Icon secondary size | | iconSecondarySizeSm | string | 16px | Icon secondary size sm | | labelFontSize | string | config?.global?.size?.fontSizeXs ?? 12px | Label font size | | labelLineHeight | string | config?.global?.size?.lineHeightXs ?? 16px | Label font size | | labelLineHeight | string | config?.global?.size?.lineHeightXs ?? 16px | Label font size |

style

path: global.style[name]

| name | type | default value | description | |----------------------------------------------------|----------------|---------------|------------------------------| | radiusPrimary | string | 1rem | General border radius | | radiusSecondary | string | 1rem | Secondary border radius | | fontWeightLight | string | 300 | Font weight light | | fontWeightMedium | string | 500 | Font weight medium | | fontWeightBold | string | 700 | Font weight bold | | actionOpacity | string | 1 | Action element opacity | | actionOpacityHover | string | 0.8 | Action hover element opacity |

component

popup

path: component.popup[name]

| name | type | default value | description | |----------------------|------------------|---------------------------------------------------------|------------------| | color.colorText | string | config?.global?.color?.colorTextSecondary ?? #9DA2AD | Popup text color | | color.colorBg | string | config?.global?.color?.colorBgSecondary ?? #2B313E | Popup bg color | | color.colorBorder | string | config?.global?.color?.colorTextSecondary ?? #9DA2AD | Popup bg color | | size.fontSize | string | config?.global?.size?.fontSizeXs ?? 12px | Popup font size |

popupList

path: component.popupList[name]

| name | type | default value | description | |-------------------------|------------------|----------------------------------------------------------|-------------------------------| | color.itemBgEven | string | transparent | Popup list even item bg color | | color.itemBgOdd | string | #2A3648 | Popup list odd item bg color | | color.headerBg | string | #1B2432 | Popup list header bg color |

tabGroup

path: component.tabGroup[name]

| name | type | default value | description | |-----------|------------------|----------------------------------|--------------------------| | size.px | string | global.size.spacer * 3 | Tab group padding inline |

tabContent

path: component.tabContent[name]

| name | type | default value | description | |------------|------------------|---------------------------|----------------------------| | size.pt | string | global.size.spacer * 3 | Tab content padding top | | size.px | string | 0px | Tab content padding inline | | size.pb | string | global.size.spacer * 9 | Tab content padding bottom | | size.gap | string | global.size.spacer * 2 | Tab content flex gap |

tab

path: component.tab[name]

| name | type | default value | description | |--------------------------|---------------------|--------------------------------------|-----------------------| | size.px | string | global.size.spacer * 9 | Tab padding inline | | size.py | string | global.size.spacer * 3 | Tab padding block | | size.fontSize | string | global.size.fontSizeSm | Tab font size | | color.colorBg | string | global.color.colorBgNeutral | Tab bg color | | color.colorText | string | global.color.colorTextNeutral | Tab text color | | color.selectColorText | string | global.color.colorTextPrimary | Tab select text color | | color.colorTextHover | string | global.color.colorTextPrimaryHover | Tab hover text color | | style.fontWeight | string | global.style.fontWeightBold | Tab font weight | | style.lineHeight | string | global.size.lineHeightSm | Tab line height |

balance

path: component.balance[name]

| name | type | default value | description | |------------------------|---------------------|------------------------------------|---------------------------| | size.px | string | global.size.spacer * 3 | Balance padding inline | | size.gap | string | global.size.gap | Balance flex gap | | size.fontSize | string | global.size.fontSizeLg | Balance font size | | size.lineHeight | string | global.size.lineHeightLg | Balance line height | | size.priceFontSize | string | global.size.fontSizeBase | Balance price font size | | size.priceLineHeight | string | global.size.lineHeightBase | Balance price line height | | color.colorText | string | global.color.colorTextPrimary | Balance text color | | color.priceColorText | string | global.color.colorTextSecondary | Balance price text color |

inputGroup

path: component.inputGroup[name]

| name | type | default value | description | |----------------|---------------------|---------------------------------------|----------------------------| | size.px | string | global.size.spacer * 3 | Input group padding inline | | size.gap | string | global.size.gap | Input group flex gap |

input

path: component.input[name]

| name | type | default value | description | |----------------------------|-------------------------|-------------------------------------|-----------------------------| | size.px | string | global.size.spacer * 3 | Input padding inline | | size.py | string | global.size.spacer * 2 | Input padding block | | size.gap | string | global.size.gap * 2 | Input flex gap | | size.priceGap | string | global.size.gap * 2 | Input flex gap | | size.iconSize | string | global.size.iconSize | Input icon size | | size.iconSizeSm | string | global.size.iconSizeSm | Input icon size sm | | size.labelFontSize | string | global.size.fontSizeSm | Input label line height | | size.labelLineHeight | string | global.size.lineHeightSm | Input label font size | | size.fontSize | string | global.size.fontSizeSm | Input font size | | size.lineHeight | string | global.size.lineHeightSm | Input line height | | size.fontSizeLg | string | global.size.fontSizeLg | Input font size lg | | size.lineHeightLg | string | global.size.lineHeightLg | Input line height lg | | size.tokenFontSize | string | global.size.fontSizeXs | Input token font size | | size.tokenLineHeight | string | global.size.lineHeightXs | Input token line height | | size.tokenFontSizeSm | string | global.size.fontSizeBase | Input token font size sm | | size.tokenLineHeightSm | string | global.size.lineHeightBase | Input token line height sm | | size.buttonPx | string | global.size.spacer * 2 | Input button padding inline | | size.buttonPy | string | global.size.spacer | Input button padding block | | size.buttonFontSize | string | global?.size?.fontSizeXs | Input button font size | | size.buttonLineHeight | string | global?.size?.lineHeightXs | Input button line height | | color.textColor | string | global.color.colorTextPrimary | Input text color | | color.loadingTextColor | string | global.color.colorTextLoading | Input loading text color | | color.bgColor | string | global.color.colorBgNeutral | Input bg color | | color.bgColorFocus | string | transparent | Input bg color | | color.borderColor | string | #4C505B | Input border color | | color.borderColorFocus | string | global.color.colorTextPrimary | Input border focus color | | color.placeholderColor | string | global.color.colorTextSecondary | Input placeholder color | | color.buttonBgColor | string | global.color.colorBgSecondary | Input button bg color | | color.buttonBorderColor | string | global.color.colorBgAccentTo | Input button border color | | color.buttonTextColor | string | global.color.colorTextPrimary | Input button text color | | style.radius | string | global.style.radiusPrimary | Input border radius | | style.labelFontWeight | string | global.style.fontWeightLight | Input label font weight | | style.fontWeight | string | global.style.fontWeightLight | Input font weight | | style.tokenFontWeight | string | global.style.fontWeightLight | Input token font weight | | style.buttonRadius | string | 30px | Input button border radius |

tooltip

path: component.tooltip[name]

| name | type | default value | description | |--------------------------|-------------------|-----------------------------------------------------------|------------------| | color.colorBg | string | #12171F | Tooltip bg color |

switch

path: component.switch[name]

| name | type | default value | description | |----------------------------|-------------------|------------------------------------------------------------|---------------------------| | color.colorBgChecked | string | #152E4D | Switch checked bg color | | color.colorBg | string | #4C505B | Switch unchecked bg color |

actionButton

path: component.actionButton[name]

| name | type | default value | description | |----------------------------------|---------------------|---------------------------------------|--------------------------------------------| | size.borderWidth | string | 1px | Action button border width | | color.colorBgFrom | string | global.color.colorBgAccentFrom | Action button bg gradient color from | | color.colorBgTo | string | global.color.colorBgAccentTo | Action button bg gradient color to | | color.colorBgFromHover | string | global.color.colorBgAccentFromHover | Action button hover bg gradient color from | | color.colorBgToHover | string | global.color.colorBgAccentTo | Action button hover bg gradient color to | | color.colorBorder | string | global.color.colorBgAccentFrom | Action button border color | | color.colorText | string | global.color.colorTextAccent | Action button text color | | color.colorText | string | global.color.colorTextAccent | Action button text color | | color.outlineColorBorder | string | #ffffff33 | Action outline button border color | | color.outlineColorBorderHover | string | #ffffffCC | Action outline button hover border color | | color.outlineColorText | string | global.color.colorTextPrimary | Action outline button text color |

meta

path: component.meta[name]

| name | type | default value | description | |-----------------------|---------------------|----------------------------------------|----------------------| | size.gap | string | global.size.gap | Meta flex gap | | size.px | string | global.size.spacer * 3 | Meta padding inline | | color.linkTextColor | string | global.color.colorBgAccentFrom | Meta link text color | | color.panelBgHover | string | config.global.color.colorBgNeutral | Meta panel hover bg |

Source: packages/trading-widget/src/trading-widget/providers/theme-provider/theme-provider.tsx

Default values: undefined

| name | type | default value | description | |---------------------------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------| | depositSlippageWarning | string | Includes entry fee. We recommend 2-3%, but usually it will be < 1%. Slippage may be amplified by the leverage. See the docs for more info. | | | withdrawSlippageWarning | string | Slippage only applies to single asset withdrawals and withdrawals from vaults with debt positions in Aave. | | | minSlippageWarning | string | Flexible min slippage value that is likely enough to process the transaction. | | | highSlippageWarning | string | We recommend using another asset to trade with lower slippage. | | | recommendedMinSlippage | string | Recommended Min Slippage | | | projectedDailyEarningsTooltip | string | Projected daily earnings are based on the current APY and may differ from actual earnings. | | | dailyEarnings | string | Daily Earnings | | | projectedYearlyEarningsTooltip | string | Projected yearly earnings are based on the current APY and may differ from actual earnings. | | | yearlyEarnings | string | Yearly Earnings | | | fullReceiveDetails | string | See full details influencing what you will receive. | | | tradeDetails | string | Trade details | | | maxSlippage | string | Max slippage | | | minReceiveAmount | string | You will receive no less than this amount. | | | minReceived | string | Minimum Received | | | estimatedMultiAssetFractions | string | Estimated multi asset fractions | | | infinite | string | Infinite | | | tokenAllowance | string | Token Allowance | | | entryFee | string | Entry Fee | | | entryFeeExplanation | string | When you deposit, the token takes a small entry fee. This fee helps cover the costs when we rebalance the underlying funds, and it's shared among all token holders. | | | easySwapperEntryFee | string | Entry fee is charged when a cooldown of {time} is selected. Bypass Entry Fee at trading settings. | | | amountToBeApproved | string | Amount of {symbol} tokens to be approved. Can be customized in settings. | | | minDepositUsd | string | Minimum deposit in USD. | | | minDeposit | string | Minimum Deposit | | | tokensLockTime | string | Purchased tokens will have a {lockTime} lock. | | | slippageTolerance | string | Slippage tolerance | | | bypassEntryFee | string | Bypass Entry Fee | | | entryFeeSwitchWarning | string | By removing the entry fee, your position is locked for up to {defaultLockTime} instead of the normal {customLockTime}. | | | tokenAmountToApprove | string | Amount of tokens to be approved. | | | auto | string | Auto | | | autoSlippageDescription | string | App is testing different slippage ranges, starting low and increasing until it's likely to pass | | | lengthenLockup | string | Lengthen lockup to remove entry fee | | | deposit | string | Buy | | | withdraw | string | Sell | | | yourBalance | string | Your Balance | | | max | string | Max | | | allAssets | string | All Assets | | | all | string | All | | | payWith | string | Pay with | | | buyEstimated | string | Buy (estimated) | | | sell | string | Sell | | | receiveEstimated | string | Receive (estimated) | | | confirmInWallet | string | Please confirm in wallet | | | pending | string | Pending... | | | approve | string | Approve | | | connectWallet | string | Connect Wallet | | | minimumPurchase | string | Minimum purchase is ${value} | | | poolIsInactive | string | {poolSymbol} token is no longer active. Please withdraw from them. | | | poolIsPrivate | string | This vault is currently private | | | updateOracles | string | Update Oracles | | | confirmMaxSlippage | string | Confirm {slippagePercentage}% max slippage | | | withdrawalWindowDisabled | string | You can sell your {tokenSymbol} tokens during withdrawal window period starting from {startTime} | | | withdrawCooldown | string | You can sell your {tokenSymbol} tokens in {cooldownEndTime} | | | termsOfUse | string | Terms Of Use | | | termOfUseDepositListTitle | string | Please know the following before depositing | | | termOfUseDepositAssetSlippage | string | When exiting, investors receive single asset or the underlying vault assets. Withdraw slippage can be customized in withdraw settings | | | termOfUseDepositBugs | string | There may be interface bugs on the platform | | | termOfUseDepositDowntime | string | There may be interface downtime (planned and unplanned) | | | termOfUseDepositAuditRisk | string | Smart contracts are audited but a risk is still present | | | termOfUseDepositAccept | string | Accept & Deposit |