⚙️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.

cURL example:

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

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