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

# Integration Guide

> Best practices for integrating trade and comment notifications with fatigue prevention

## Overview

The Clicker API provides real-time trade and comment data by delivering webhook events to the partner's backend. **Notification delivery and fatigue prevention are the responsibility of the integrating partner.** This guide shows examples of how the Clicker app uses a webhook's payload to filter notifications. Each webhook POST body contains `{ events: [...] }` — the field paths below reference fields within each event object.

## Automatic Filters

These filters could be implemented in the background on your side without surfacing to users in notification settings.

### Filter by trade freshness

**Event types:** `new-feed-item`, `comment-created`

**User story:** Stale trades aren't actionable. If there's a delivery backlog, users shouldn't get flooded with outdated notifications.

**Webhook payload field:** `feedItem.timestamp`

**Recommended automatic filter:** Don't send notifications for trades older than 5 minutes.

### Filter by comment timeliness

**Event types:** `comment-created`

**User story:** Comments on old trades are less relevant. Users want to see commentary while the trade context is still fresh.

**Webhook payload field:** `feedItem.timestamp`

**Recommended automatic filter:** Don't send comment notifications if the trade is older than 15 minutes.

### Rate limit by trader/token pair

**Event types:** `new-feed-item`, `comment-created`

**User story:** Active traders might make multiple swaps on the same token in a short period. Users don't need a notification for every single one.

**Webhook payload fields:** `feedItem.actor.address`, `feedItem.metadata.tokenAddress`

**App-specific data:** Timestamp of last notification sent for this trader/token pair

**Recommended automatic filter:** Max one notification per trader per token per 12-24 hours.

## User-Configurable Filters

These filters should be surfaced to users in notification settings.

### Filter by buy and/or sell trades

**Event types:** `new-feed-item`

**User story:** Users may be more interested in what traders are buying than selling.

**Webhook payload field:** `feedItem.metadata.trades[0].direction`

**Options:** Buy (toggle: on/off), Sell (toggle: on/off)

**Recommended default:** Buy on, sell off.

### Filter by buy and/or sell comments

**Event types:** `comment-created`

**User story:** Comments represent high-signal moments regardless of trade direction. A trader explaining why they're exiting a position is just as valuable as their entry thesis.

**Webhook payload field:** `feedItem.metadata.trades[0].direction`

**Options:** Buy comments (toggle: on/off), Sell comments (toggle: on/off)

**Recommended default:** Both on.

### Filter by dollar minimum

**Event types:** `new-feed-item`, `comment-created`

**User story:** Small trades are often noise - test transactions, minor rebalances, or low-conviction plays. Users want to see meaningful positions. Different users also have different portfolio sizes, so a \$100 trade is significant to some and irrelevant to others.

**Webhook payload field:** `feedItem.metadata.trades[0].usdCost`

**App-specific data:** User's configured dollar minimum setting

**Options:** \$10, \$100, \$250, \$500, \$1,000+

**Recommended default:** \$500.

### Filter by chain

**Event types:** `new-feed-item`, `comment-created`

**User story:** Users often focus on specific ecosystems and don't want notifications for chains they don't trade on.

**Webhook payload field:** `feedItem.metadata.tokenChain`

**Options:** Base (toggle: on/off), Ethereum (toggle: on/off), Solana (toggle: on/off)

**Recommended default:** All on.

## Recommended Data Flow

```
Webhook Event Received from Clicker API
        ↓
    Event Age Check
        ↓
    Chain Filter (user preference)
        ↓
    Trade Size Filter (user preference)
        ↓
    Buy/Sell Filter (user preference)
        ↓
    Cooldown/Rate Limit Check
        ↓
    Notification Delivered to User
```

## Summary

| Layer           | Responsibility                                                                         |
| :-------------- | :------------------------------------------------------------------------------------- |
| **Clicker API** | Delivers real-time trade and comment data with all relevant metadata                   |
| **Your App**    | Filters events, applies user preferences, enforces rate limits, delivers notifications |