> ## Documentation Index
> Fetch the complete documentation index at: https://docs.delora.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Widget Events

> Callback hooks emitted by TradeWidget.

`TradeWidget` exposes callbacks for quote resolution, wallet connections, transaction lifecycle reporting, and error handling.

## Example

```tsx theme={null}
<TradeWidget
  config={{}}
  onQuote={(payload) => {
    console.log("quote", payload);
  }}
  onConnect={(payload) => {
    console.log("wallet connected", payload);
  }}
  onTxSubmitted={(payload) => {
    console.log("submitted", payload.action, payload.txHash);
  }}
  onTxConfirmed={(payload) => {
    console.log("confirmed", payload.action, payload.txHash);
  }}
  onError={(payload) => {
    console.error(payload.source, payload.message);
  }}
/>
```

## Supported callbacks

| Callback        | When it fires                                                                                            | Payload                         |
| --------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------- |
| `onQuote`       | After a new quote is resolved                                                                            | `TradeWidgetQuotePayload`       |
| `onConnect`     | After a wallet connection succeeds                                                                       | `TradeWidgetConnectPayload`     |
| `onApprove`     | When the widget submits a standalone approval transaction                                                | `TradeWidgetTransactionPayload` |
| `onSwap`        | When the widget submits a swap transaction                                                               | `TradeWidgetTransactionPayload` |
| `onTxSubmitted` | When any approval or swap transaction is submitted                                                       | `TradeWidgetTransactionPayload` |
| `onTxConfirmed` | When a submitted transaction is confirmed                                                                | `TradeWidgetTransactionPayload` |
| `onError`       | When metadata, configuration, selection, quote, wallet, balances, execution, or unsupported errors occur | `TradeWidgetErrorPayload`       |

## Event behavior notes

* `onQuote` is deduplicated, so identical resolved quotes are not emitted repeatedly
* `onQuote` can fire after the initial quote load, a manual refresh, or an auto-refresh when the resolved quote changed
* `onConnect` only reports `namespace`, `address`, and `walletName`; it does not identify whether the connection came from the origin or destination side
* `onApprove` and `onSwap` are submission hooks, not simple button-click hooks
* `onTxSubmitted` is the generic submission event for both `approve` and `swap`
* `onTxConfirmed` is the generic confirmation event for both `approve` and `swap`
* `onError` with `source: "quote"` and `statusCode: 429` can come either from the Delora API or from the widget's own local quote cooldown

In batched EVM flows that combine approval and swap into a single EIP-5792 call, the widget may only emit the swap-side transaction event because there is no separate approval transaction hash.

The widget also applies a local quote lifecycle around refreshes:

* successful quotes auto-refresh every 60 seconds while the selection stays stable
* auto-refresh stops after 5 consecutive refresh cycles
* more than 15 quote requests within 5 seconds triggers a local cooldown
* the cooldown lasts 5 seconds
* during that window, `onError` can emit a quote error with `statusCode: 429` even if the backend did not return 429

## Error sources

`onError` can report the following `source` values:

* `metadata`
* `configuration`
* `quote`
* `selection`
* `wallet`
* `balances`
* `execution`
* `unsupported`

The payload can also include `status`, `statusCode`, and the original error object.