> For the complete documentation index, see [llms.txt](https://docs.fuul.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fuul.xyz/fuul-mcp-server/affiliates/affiliate-management.md).

# Affiliate Management

Register, update, and configure affiliates, audiences, and tiers directly from your AI assistant.

## 1. Get your API key

1. Go to [app.fuul.xyz](https://app.fuul.xyz) and log in
2. Go to **Settings → API Keys → New API Key**
3. Select the **`service_role`** scope
4. Give it any name and click **Create**

## 2. Add the key to your environment

```
FUUL_MCP_PROJECT_API_KEY=your_key_here
```

Then tell Claude where to find it:

> "My Fuul project API key is set as FUUL\_MCP\_PROJECT\_API\_KEY in my environment — use that for managing affiliates"

{% hint style="warning" %}
Never pass the key directly in the chat — set it as an environment variable.
{% endhint %}

## 3. Look up an affiliate

> "Get the profile for CryptoKing"

{% hint style="info" %}
Returns everything the platform knows about that affiliate: their wallet address, current status (Active, Paused, etc.), region, display name (alias), which tier they belong to, which audiences they're in, and any active tier protections.
{% endhint %}

## 4. Register a new affiliate

> "Add CryptoKing (0x1234...abcd) as an affiliate on this project"

Optional fields: `alias`, `region`, `status`, `note`, `audiences`, `tier_protection`.

{% hint style="info" %}
The MCP runs a `dry_run` first and shows you the affiliate profile it will create before confirming.
{% endhint %}

## 5. Update an affiliate

> "Set the alias for 0x1234...abcd to CryptoKing"

> "Set CryptoKing's status to inactive"

> "Assign CryptoKing to the VIP audience"

{% hint style="info" %}
You can update any combination of: `alias`, `region`, `status`, `note`, `audiences`, `tier_protection` (set to `null` to clear it).
{% endhint %}

**Tier protection** — locks the affiliate to a tier for a number of days, preventing automatic downgrades:

> "Protect CryptoKing on the influencers tier for 30 days"

{% hint style="info" %}
Requires `tier_id` and `protection_days` (1–365). Optionally pass `expires_at` to set a fixed expiry date instead.
{% endhint %}

**Tier approval** — manually approve an affiliate for one or more tiers:

> "Approve CryptoKing for the influencers\_v2 tier"

Requires the tier name or ID and the team member approving.

## 6. Update an audience definition

Audiences are user segments with optional conditions. You can update the name and conditions of an existing audience:

> "Rename the 'Demo Gold' audience to 'Diamond Partners'"

> "Update the 'Demo Bronze' audience conditions to match users holding the Loyalty NFT"

{% hint style="info" %}
If updating conditions, specify whether users need to match any or all of them.
{% endhint %}

## 7. Update a tier

Tiers define differentiated payout rates for specific groups of affiliates. Each tier is associated with an audience — a list of wallets that qualifies for that tier's rates. For example, you might have a static audience of 40 influencer wallets linked to a tier that pays a higher commission rate than the default.

You can update a tier's name, description, rank, or the audience it points to:

> "Rename the 'influencers' tier to 'Gold'"

> "Set the rank of the 'Gold' tier to 1"

> "Point the 'Gold' tier to the 'Top Influencers' audience"

{% hint style="info" %}
All write operations (`create`, `update`) follow the `dry_run` → `confirmed` flow — the MCP will show you a preview before making any changes.
{% endhint %}