📡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.

1. Get your API key

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

1. Go to 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

Never pass the key directly in the chat — set it as an environment variable.

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, stellar_address, email, etc.
dedup_id	A unique ID for this event — used to prevent duplicates

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).

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.

Rate limit: 10 requests/minute.

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?"

Use this before resending a single event to avoid a 409 duplicate error — if it already exists, don't send it again.

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

Use this when an event was received but rewards didn't appear — it shows exactly where in the pipeline things stopped.