Event Tracking

The widget sends lifecycle events to the depositOS API as deposits progress, giving you visibility into user behaviour and outcomes. They power the volume, transaction and conversion figures in the portal.

Enabling

Set config.apiKey. That's it — events flow automatically, attributed to your app.

const config: DepositOSConfig = {
  destChain: 42161,
  destToken: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
  destAddress: "0xYourTreasury",
  apiKey: "dos_live_…",
};

Attribution comes from the x-api-key header, not from anything in the payload. Without a valid key, events are not recorded against your app.

Event Types

| Event | When it fires | |---|---| | widget_loaded | The widget renders in the user's browser | | quote_requested | A price quote is requested | | quote_received | A quote comes back | | quote_failed | A quote could not be produced | | tx_initiated | The user starts a transaction | | tx_completed | The transaction succeeds | | tx_failed | The transaction fails |

Private-mode flows emit a parallel set: private_quote_requested, private_quote_received, private_quote_failed, private_swap_creating, private_swap_created, private_swap_completed, private_swap_failed.

Payload

Each event is a JSON object. Every field except event_type is optional and varies by event.

{
  "event_type": "tx_completed",
  "session_id": "…",
  "wallet_address": "0x…",
  "source_chain": 1,
  "source_token": "0x…",
  "dest_chain": 42161,
  "dest_token": "0x…",
  "amount": "100.5",
  "amount_usd": 100.42,
  "fee_bps": 30,
  "tx_hash": "0x…",
  "status": "success",
  "metadata": {}
}

| Field | Type | Description | |---|---|---| | event_type | string | One of the types above. Required. | | session_id | string | Correlates events within one widget session. | | wallet_address | string | Connected wallet, when there is one. | | source_chain / source_token | number / string | What the user paid with. | | dest_chain / dest_token | number / string | What they received. | | amount | string | Human-readable amount. | | amount_usd | number | Best-effort USD value; drives volume reporting. | | fee_bps | number | Total fee applied, in basis points. | | tx_hash | string | Destination transaction hash, on completion. | | error_message | string | Present on *_failed events. |

Tracking Orders

Use the orderRef config property to associate widget events with your internal order system, so deposits can be reconciled against your own records:

const config: DepositOSConfig = {
  // ...
  orderRef: "order-789",
  apiKey: "dos_live_…",
};

Viewing Events

Your app's events, volume and conversion funnel live in the portal. Select your app to see the analytics dashboard and a searchable event log.