# Sending Custom Events

Fuul natively tracks onchain actions, but projects can also send custom offchain events via the backend API — for any action that happens outside the blockchain and isn't covered by a native integration.

## Sending individual events

Send events via the [Send Event API endpoint](https://fuul.readme.io/reference/sendevent).

**cURL example:**

```bash
curl -X POST https://api.fuul.xyz/api/v1/events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-send-trigger-event-key" \
  -d '{
    "name": "custom_conversion",
    "user": {
      "identifier": "0x1234...",
      "identifier_type": "evm_address"
    },
    "args": {
      "value": {
        "amount": "1000000",
        "currency": {
          "identifier": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
          "identifier_type": "evm_address",
          "chain_identifier": 1
        }
      }
    }
  }'
```

### Event arguments (`args`)

The `args` object lets you attach metadata to each event. These are the standardized keys:

| Key                | Type   | Description                                                             |
| ------------------ | ------ | ----------------------------------------------------------------------- |
| `value`            | object | Transaction volume — used to calculate variable payouts by default      |
| `revenue`          | object | Revenue generated — used for analytics, optionally for variable payouts |
| `transaction_hash` | string | Onchain transaction hash (when reporting onchain events)                |
| `chain_id`         | number | Chain ID where the event occurred                                       |

### Value and revenue format

Both `value` and `revenue` follow the same structure. The `amount` must be in the **smallest unit** of the currency (e.g., WEI for ETH tokens):

```json
{
  "args": {
    "value": {
      "amount": "1000000",
      "currency": {
        "identifier": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "identifier_type": "evm_address",
        "chain_identifier": 1
      }
    },
    "revenue": {
      "amount": "100000",
      "currency": {
        "identifier": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "identifier_type": "evm_address",
        "chain_identifier": 1
      }
    }
  }
}
```

{% hint style="warning" %}
Amounts must be in the smallest unit (WEI for ERC-20 tokens). Incorrect formatting will lead to inaccurate payout calculations.
{% endhint %}

### Points and USD values

For Points or USD-denominated values, use the currency `name` directly:

```json
{
  "args": {
    "value": {
      "amount": "1000000",
      "currency": {
        "name": "POINT"
      }
    }
  }
}
```

| Currency name | Description       |
| ------------- | ----------------- |
| `POINT`       | Points (offchain) |
| `USD`         | US Dollar value   |

## Sending batch events

To send multiple events at once, build an array of event objects and use the [Send Batch Events endpoint](https://fuul.readme.io/reference/sendbatchevents).

```json
[
  {
    "name": "custom_conversion",
    "user": {
      "identifier": "0xabc123...",
      "identifier_type": "evm_address"
    },
    "args": {
      "value": {
        "amount": "1000000",
        "currency": {
          "identifier": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
          "identifier_type": "evm_address",
          "chain_identifier": 1
        }
      }
    }
  },
  {
    "name": "custom_conversion",
    "user": {
      "identifier": "0xdef456...",
      "identifier_type": "evm_address"
    },
    "args": {
      "value": {
        "amount": "2000000",
        "currency": {
          "identifier": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
          "identifier_type": "evm_address",
          "chain_identifier": 1
        }
      }
    }
  }
]
```

{% hint style="info" %}
You can also check the status of a previously sent event using the [Check Event Status endpoint](https://fuul.readme.io/reference/checkeventstatus).
{% endhint %}


---

# Agent Instructions: 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:

```
GET https://docs.fuul.xyz/developer-guide/sending-custom-events-through-the-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.