> For the complete documentation index, see [llms.txt](https://docs.fuul.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fuul.xyz/fuul-mcp-server/sending-events.md).

# Sending Events

The Fuul MCP lets you send custom conversion events directly from your AI assistant — the same events you'd send via the API, but without writing code. This is useful for testing your trigger setup, importing historical conversions, or sending events in bulk from a spreadsheet or CSV.

For full details on event payloads and the `args` format, see [Sending Custom Events](/developer-guide/sending-custom-events-through-the-api.md).

## 1. Get your API key

Before sending events, you need a project API key with the right permission:

1. Go to [app.fuul.xyz](https://app.fuul.xyz) and log in
2. Go to **Settings → API Keys → New API Key**
3. Select the **`send:trigger_event`** scope
4. Give it any name and click **Create**

## 2. Add the key to your environment

Add the key to your `.env` file so the MCP can access your project:

```
FUUL_MCP_PROJECT_API_KEY=your_key_here
```

{% hint style="warning" %}
Never pass the key directly in the chat — set it as an environment variable.
{% endhint %}

Then tell Claude where to find it:

> "My Fuul project API key is set as FUUL\_MCP\_PROJECT\_API\_KEY in my environment — use that for sending events"

From this point on, Claude will use it automatically on every event call.

## 3. Send a single event

> "Send a 'trade' event for user 0xABC... with a value of 100 USDC on Ethereum"

Required fields:

| Field                  | Description                                                    |
| ---------------------- | -------------------------------------------------------------- |
| `name`                 | The trigger's event name — must match exactly (case-sensitive) |
| `user_identifier`      | The user's wallet address or email                             |
| `user_identifier_type` | `evm_address`, `solana_address`, `email`, etc.                 |
| `dedup_id`             | A unique ID for this event — used to prevent duplicates        |

{% hint style="info" %}
The `dedup_id` is critical: if you send the same event twice with the same `dedup_id`, the second call returns a 409 and the event is not recorded again. Always use a unique identifier (e.g. a transaction hash or a UUID tied to the source record).
{% endhint %}

Rate limit: **100 requests/minute**.

## 4. Send events in bulk

> "Send these 50 events from this CSV"

The MCP can send up to **100 events per batch call**. Duplicate `dedup_id` values within the batch are silently skipped — the response tells you how many events were actually ingested.

{% hint style="info" %}
Rate limit: **10 requests/minute**.
{% endhint %}

## 5. Check if an event was processed

After sending, you can verify that an event was received and processed:

> "Did user 0xABC... trigger the 'trade' event?"

{% hint style="info" %}
Use this before resending a single event to avoid a 409 duplicate error — if it already exists, don't send it again.
{% endhint %}

## 6. Trace the full pipeline

To see exactly what happened downstream — trigger execution, attribution, payout, and balance movement — provide the `dedup_id` and event name:

> "Show me the full pipeline for the last event I sent"

This returns:

| Field                | Description                                                             |
| -------------------- | ----------------------------------------------------------------------- |
| `trigger_executions` | Whether the trigger fired and its status (`Accepted`, `Rejected`, etc.) |
| `attributions`       | Which conversion was matched and whether it was confirmed               |
| `payouts`            | Amounts and currencies credited                                         |
| `movements`          | The resulting balance changes                                           |

{% hint style="info" %}
Use this when an event was received but rewards didn't appear — it shows exactly where in the pipeline things stopped.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.fuul.xyz/fuul-mcp-server/sending-events.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.