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

# Custom events

> Define and track custom events like swaps, deposits, and quests with structured properties using the Formo SDK Track API.

## Overview

The Formo SDK offers an easy-to-use event collection library that allows you to track custom events in your crypto app.

See the [Web SDK](/sdks/web#track-events) docs to get started.

***

## How to track custom events

While Formo autocaptures page views, wallet connects, and transactions, custom events let you track specific actions that matter to your app.

### When to use custom events

Track actions that aren't captured automatically:

| Action              | Why track it              |
| ------------------- | ------------------------- |
| Swap submissions    | Measure swap conversion   |
| Deposit completions | Track liquidity flows     |
| Feature usage       | Understand adoption       |
| Errors              | Debug user issues         |
| Key conversions     | Measure business outcomes |

### Step 1: Import the Formo SDK

<Tabs>
  <Tab title="React / Next.js">
    ```tsx theme={null}
    import { useFormo } from '@formo/analytics';

    function YourComponent() {
      const analytics = useFormo();

      // Now you can track events
    }
    ```
  </Tab>

  <Tab title="HTML Snippet">
    The `formo` object is available globally after the snippet loads:

    ```javascript theme={null}
    // Track an event
    window.formo.track('Swap Completed', { pair: 'ETH/USDC' });
    ```
  </Tab>
</Tabs>

### Step 2: Track a custom event

Use the `track` function with an event name and optional properties:

```typescript theme={null}
analytics.track('Swap Completed', {
  pool_id: 'ETH/USDC',
  amount: 1000,
  slippage: 0.5
});
```

**Event parameters:**

* **Event name** (required): Descriptive name for the action
* **Properties** (optional): Key-value pairs with additional context

### Step 3: Track with volume, revenue, or points

For events with monetary value, use the reserved `volume`, `revenue`, and `points` properties:

```typescript theme={null}
analytics.track('Swap Completed', {
  pair: 'ETH/USDC',
  volume: 5000,   // volume of the swap; can be positive or negative
  revenue: 25,    // revenue earned (e.g., fees); must be non-negative
  points: 100     // loyalty/reward points
});
```

See [Tracking volume, revenue, points](/data/events/track#tracking-volume-revenue-points) for the full field reference, including `currency` (defaults to USD). These values power revenue attribution, volume tracking, and points/rewards leaderboards in your dashboard.

### Step 4: View custom events

After tracking events:

1. Go to **Activity** in the Formo Dashboard
2. Filter by your custom event name
3. See all event occurrences

Custom events also appear in:

* [**Wallet Profiles**](/features/wallet-intelligence/wallet-profiles): user's activity history
* [**Funnels**](/features/product-analytics/funnels): as conversion steps
* [**Charts**](/features/product-analytics/charts): query with SQL

## Examples

### Tracking a swap flow

Track multiple events throughout a user flow:

```typescript theme={null}
// User clicks swap button
analytics.track('Swap Started', {
  pair: 'ETH/USDC',
  token_in: '0x...',
  token_out: '0x...',
  amount_in: 1,
  amount_out_estimate: 3000
});

// User approves token (if needed)
analytics.track('Token Approved', {
  token: '0x...',
  amount: 1,
  spender: '0x...'
});

// Swap completes successfully
analytics.track('Swap Completed', {
  pair: 'ETH/USDC',
  token_in: '0x...',
  token_out: '0x...',
  amount_in: 1,
  amount_out: 2998,
  volume: 2998,
  slippage: 0.07
});

// Or if swap fails
analytics.track('Swap Failed', {
  pair: 'ETH/USDC',
  token_in: '0x...',
  token_out: '0x...',
  error: 'Insufficient liquidity',
  error_code: 'INSUFF_LIQ'
});
```

### Tracking DeFi feature adoption

Measure which features users engage with:

```typescript theme={null}
// User opens a liquidity pool
analytics.track('Pool Opened', {
  pool_id: 'ETH/USDC',
  pool_address: '0x...',
  source: 'sidebar'
});

// User completes a key action in the pool
analytics.track('Liquidity Added', {
  pool_id: 'ETH/USDC',
  pool_address: '0x...',
  token_in: 'ETH',
  token_out: 'USDC'
});
```