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

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

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:

{
  "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 mainnet) or 1481 (Stellar testnet)
Decimals	7, not 18

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.

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.

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.