> 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 | stellar_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   |

### Stellar assets

An event's value can be denominated in a Stellar asset. The currency is named by its Soroban contract address, using a different identifier type from the one used for users:

```json
{
  "args": {
    "value": {
      "amount": "10000000",
      "currency": {
        "identifier": "CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA",
        "identifier_type": "stellar_contract",
        "chain_identifier": 148
      }
    }
  }
}
```

| Field              | Value                                                                          |
| ------------------ | ------------------------------------------------------------------------------ |
| `identifier`       | The asset's Soroban contract address — a 56-character StrKey starting with `C` |
| `identifier_type`  | `stellar_contract`                                                             |
| `chain_identifier` | `148` (Stellar pubnet)                                                         |
| Decimals           | **7**, not 18                                                                  |

{% hint style="warning" %}
**`stellar_contract` names a currency. `stellar_address` names a user.** They are not interchangeable, and each is rejected in the other's position. The asset in `value.currency` is a `C…` contract address; the person in `user.identifier` is a `G…` account address. See [Stellar signatures](/developer-guide/tracking-referrals-in-your-app.md#stellar-signatures).
{% endhint %}

{% hint style="warning" %}
Stellar StrKeys are **uppercase base32 and case-sensitive**. Never lowercase one the way you might an EVM address — you will reference a currency that does not exist.

Stellar assets use **7 decimals**. An amount written with 18 decimals is off by 10^11.
{% endhint %}

## 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 %}