⚙️Sending Custom Events

Fuul natively tracks onchain actions, but projects can also send custom offchain events to trigger rewards — for example, social media actions, Discord activity, or any backend event.

Custom events must be sent from the backend using the send:trigger_event API key. Never use this key in the frontend — it would allow anyone to send fake conversion events.

Sending individual events

Send events via the Send Event API endpoint.

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
github_username	string	GitHub username of the acting user
discord_username	string	Discord username of the acting user

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

{
  "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
      }
    }
  }
}

Amounts must be in the smallest unit (WEI for ERC-20 tokens). Incorrect formatting will lead to inaccurate payout calculations.

Points and USD values

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

{
  "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.

[
  {
    "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
        }
      }
    }
  }
]

You can also check the status of a previously sent event using the Check Event Status endpoint.