> 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 %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.fuul.xyz/fuul-mcp-server/affiliates/affiliate-management.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.