> 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/developer-guide/sending-custom-events-through-the-api.md).

# 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"  // evm_address | solana_address | xrpl_address | sui_address | email | uuid
    },
    "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 %}