Sending trigger events through the Fuul API

This guide shows how to send trigger events through the API

Fuul is designed to use onchain triggers, but projects can still have offchain conversions that they want to track or use to make payouts.

For security reasons, these events must be sent from the backend using the SEND: TRIGGER_EVENT API key.

If another type of key is used or if this is implemented on the frontend, the API key will be open to anyone who could maliciously perform conversion events.

import requests

url = "https://api.fuul.xyz/api/v1/events"

payload = {
    "args": {
    	"value": {
		"amount": "1000000",
		"currency": "USDC"
	},
	"revenue": {
		"amount": "100000",
		"currency": "USDC"
	}
    },
    "name": "trigger-event-name",
    "user_address": "0x95222290DD7278Aa3Ddd389Cc1E1d165CC4BAfe5",
    "dedup_id": "80652e61-986f-4d01-b4d5-1d3697fe36f4",
    "timestamp: "1710875677000"
}

headers = {
    "content-type": "application/json",
    "authorization": "Bearer my-fuul-key"
}

response = requests.post(url, json=payload, headers=headers)

name: the event name that was defined on the app when creating the trigger.

user_address: the user that acted. This value will be used by attributors to identify the user in the conversion event and match it with clicks and connect wallet events.

dedup_id: the unique identifier for the event. It can be any unique string that you generate and is used to prevent duplicate events from being sent.

timestamp: The timestamp of the event in milliseconds since epoch. If time isn't sent with the event, it's set to the request upload time.

args: key-value pairs of the arguments of the event. The values can be strings, numbers, or booleans. The keys can be any string, but the most common ones are standardized.

• value: an object with the amount and currency for the value of the transaction. This is only mandatory when the conversion payout is variable. This value will be multiplied by the variable payout percentage to get the corresponding payouts

• revenue: an object with the amount and currency for the revenue value for the project. This is not mandatory, but it will give projects insights from their campaigns. This metric will be available in the app's dashboards

• transaction_hash: the transaction hash of the event. This can be used when for any reason projects are reporting onchain events

• token_id: the token id (if any) implicated in the event

It’s crucial to ensure that the value parameters are correctly formatted.

The amount parameter on the valueandrevenue objects should be provided in the smallest possible unit of the respective currency. For Ethereum-based tokens, this unit is usually WEI.

Incorrect formatting may lead to unintended and potentially inaccurate results

You can also find the interactive API documentation here

Accepted currencies list

These are the accepted currencies:

• ETH

• USDC

• USDT

• DAI

• BTC

• MATIC (Polygon)

• OP

• ARB

• LINK

Sending Batch Events

Use this request to bulk-send events to Fuul. You have to build an array of event objects constructed as shown above.

import requests

url = "https://api.fuul.xyz/api/v1/events/batch"

payload = [
            myFirstEventObject, 
            ... , 
            myLastEventObject
]

headers = {
    "content-type": "application/json",
    "authorization": "Bearer my-fuul-key"
}

response = requests.post(url, json=payload, headers=headers)