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

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"
    },
    "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
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.

Querying conversions

You can retrieve conversions configured for your project and check whether a specific user has completed them.

Listing conversions

List all conversions with their triggers and payout configuration (API reference):

// GET /v1/conversions

Each conversion in the response includes:

Field	Description
name	Conversion display name
triggers	Array of triggers that feed into this conversion
payout_terms	Array of payout configurations, each containing payout_groups with reward rates

Showing trigger names and reward rates

Each conversion includes its associated triggers and payout_terms. You can use these to display what each conversion rewards to end users and referrers.

Triggers — access triggers[].name to show which action the conversion tracks:

{
  "triggers": [
    {
      "name": "Hold Debt token of EVK Vault eUSDT0-4 - plasma",
      "triggerType": "token-holder"
    }
  ]
}

Payout rates — access payout_terms[].payout_groups[] to show how much each participant earns. Rates are expressed as a percentage of the trigger volume:

{
  "payout_terms": [
    {
      "calculation_strategy": "variable",
      "trigger_amount_source": "volume",
      "payout_groups": [
        {
          "name": "Default Tier",
          "end_user_amount_percentage": 0.02,
          "affiliate_amount_percentage": 0.003,
          "audience": null
        },
        {
          "name": "KOL",
          "end_user_amount_percentage": 0.02,
          "affiliate_amount_percentage": 0.01,
          "audience": { "name": "KOL" }
        }
      ]
    }
  ]
}

In this example, the Default Tier pays 2% to end users and 0.3% to referrers on the tracked volume. KOLs earn the same end user rate but 1% as referrers.

Payout groups with an audience field apply only to users in that audience segment. The group with "audience": null is the default tier for all users. See Managing audiences for how to assign users to segments.

Checking conversion status

Check whether a user has completed specific conversions — useful for showing progress or unlocking UI elements (API reference):

// GET /v1/conversions/status?user_identifier=0x1234...&user_identifier_type=evm_address