From 0cd3133268bb8c759032c8af68def5a5631efd48 Mon Sep 17 00:00:00 2001 From: Matias Poblete <86752543+MattPoblete@users.noreply.github.com> Date: Thu, 12 Feb 2026 08:17:50 -0300 Subject: [PATCH 1/2] =?UTF-8?q?=F0=9F=93=9D=20Add=20guide=20for=20setting?= =?UTF-8?q?=20partner=20fees?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- apps/docs/SUMMARY.md | 1 + .../setting-partner-fees.md | 334 ++++++++++++++++++ 2 files changed, 335 insertions(+) create mode 100644 apps/docs/api-integration-guide/guides-and-tutorials/setting-partner-fees.md diff --git a/apps/docs/SUMMARY.md b/apps/docs/SUMMARY.md index 47e1cd14..a6b6c947 100644 --- a/apps/docs/SUMMARY.md +++ b/apps/docs/SUMMARY.md @@ -32,6 +32,7 @@ * [Using the Factory (Advanced)](api-integration-guide/creating-a-defindex-vault/using-the-factory-advanced.md) * [Guides and Tutorials](api-integration-guide/guides-and-tutorials/README.md) * [Beginner Guide](api-integration-guide/guides-and-tutorials/beginner-guide.md) + * [Setting Partner Fees](api-integration-guide/guides-and-tutorials/setting-partner-fees.md) * [Additional Resources](api-integration-guide/guides-and-tutorials/additional-resources.md) * [Troubleshooting](api-integration-guide/troubleshooting.md) diff --git a/apps/docs/api-integration-guide/guides-and-tutorials/setting-partner-fees.md b/apps/docs/api-integration-guide/guides-and-tutorials/setting-partner-fees.md new file mode 100644 index 00000000..865d62cb --- /dev/null +++ b/apps/docs/api-integration-guide/guides-and-tutorials/setting-partner-fees.md @@ -0,0 +1,334 @@ +--- +description: ⏱️ 7 min read +--- + +# Setting Partner Fees + +## 📖 What You'll Learn + +This guide walks you through the complete fee management lifecycle for a deployed DeFindex vault: + +* **Check** the current fee configuration of your vault +* **Update** the vault fee rate (in basis points) +* **Change** the fee receiver address +* **Distribute** accumulated fees to the appropriate parties + +--- + +## 🎯 Prerequisites + +Before starting, make sure you have: + +* **Manager role** on the vault (or Fee Receiver role for specific operations) +* An **API key** from DeFindex (see [Getting Started with API](../api.md)) +* Your **vault address** on mainnet or testnet +* A way to **sign transactions** (Freighter Wallet, Stellar Laboratory, etc.) + +--- + +## 📐 Understanding BPS (Basis Points) + +DeFindex uses **basis points (BPS)** to express fee percentages. One basis point equals 0.01%. + +| BPS Value | Percentage | Description | +|-----------|------------|----------------------| +| 100 | 1% | Low fee | +| 500 | 5% | Moderate fee | +| 1000 | 10% | Common fee | +| 3000 | 30% | Standard partner fee | +| 5000 | 50% | High fee | +| 9000 | 90% | Maximum allowed | + +**Key constants:** + +* `SCALAR_BPS = 10,000` → 10,000 BPS = 100% +* **Maximum vault fee**: 9,000 BPS (90%) +* Fees are only charged on **yield generated**, never on deposited capital + +--- + +## Step 1: Check Current Fee Configuration 🔍 + +Before making changes, verify the current fee settings on your vault. + +### Get Vault Info (includes fee rates) + +```bash +curl -X GET "https://api.defindex.io/vault/YOUR_VAULT_ADDRESS?network=mainnet" \ + -H "Authorization: Bearer YOUR_JWT_TOKEN" +``` + +The response includes fee configuration: + +```json +{ + "name": "My Yield Vault", + "address": "CABC...XYZ", + "feesBps": { + "vaultFee": 3000, + "defindexFee": 500 + } +} +``` + +**🔍 What this tells you:** + +* `vaultFee`: The partner's fee rate in BPS (3000 = 30%) +* `defindexFee`: The DeFindex protocol fee rate in BPS (500 = 5%) + +### Get Current Fee Receiver + +```bash +curl -X GET "https://api.defindex.io/vault/YOUR_VAULT_ADDRESS/get/fee-receiver?network=mainnet" \ + -H "Authorization: Bearer YOUR_JWT_TOKEN" +``` + +Response: + +```json +{ + "address": "GFEE_RECEIVER_ADDRESS..." +} +``` + +--- + +## Step 2: Update the Vault Fee (BPS) 💰 + +To change the fee rate on your vault, use the `lock-fees` endpoint. This endpoint serves a **dual purpose**: it locks any accrued fees AND updates the fee rate. + +### Build the Transaction + +```bash +curl -X POST "https://api.defindex.io/vault/YOUR_VAULT_ADDRESS/lock-fees?network=mainnet" \ + -H "Authorization: Bearer YOUR_JWT_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "new_fee_bps": 3000, + "caller": "GMANAGER_ADDRESS..." + }' +``` + +**Parameters:** + +| Parameter | Type | Description | +|---------------|--------|------------------------------| +| `new_fee_bps` | number | New fee rate in BPS (0–9000) | +| `caller` | string | Manager wallet address | + +**🔍 What this does:** + +1. **Locks** any currently accrued fees at the previous rate +2. **Updates** the vault fee rate to the new value +3. Returns an **unsigned XDR** transaction + +### Sign and Submit + +The response contains an unsigned XDR transaction: + +```json +{ + "xdr": "AAAAAgAAAA..." +} +``` + +**Sign the transaction** using Freighter, Stellar Laboratory, or your preferred method, then submit: + +```bash +curl -X POST "https://api.defindex.io/send" \ + -H "Authorization: Bearer YOUR_JWT_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "xdr": "SIGNED_XDR_HERE...", + "launchtube": false + }' +``` + +**🚨 Important notes:** + +* Only the **Manager** role can update fees +* Maximum allowed value is **9000 BPS** (90%) +* Setting `new_fee_bps: 0` effectively disables partner fees + +--- + +## Step 3: Change the Fee Receiver Address 🔄 + +To redirect fee payments to a different address, use the `set/fee-receiver` endpoint. + +### Build the Transaction + +```bash +curl -X POST "https://api.defindex.io/vault/YOUR_VAULT_ADDRESS/set/fee-receiver?network=mainnet" \ + -H "Authorization: Bearer YOUR_JWT_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "new_address": "GNEW_RECEIVER_ADDRESS...", + "caller": "GMANAGER_ADDRESS..." + }' +``` + +**Parameters:** + +| Parameter | Type | Description | +|---------------|--------|-----------------------------------------| +| `new_address` | string | New fee receiver Stellar address | +| `caller` | string | Manager OR current Fee Receiver address | + +**🔍 What this does:** + +1. Updates the vault's fee receiver to the new address +2. Returns an **unsigned XDR** transaction + +### Sign and Submit + +Sign the returned XDR and submit it using the `/send` endpoint (same flow as Step 2). + +**🚨 Important notes:** + +* Can be called by **Manager** OR the **current Fee Receiver** +* The new address must be a valid Stellar address +* Always verify the new address before submitting — this action is irreversible without another update + +--- + +## Step 4: Distribute Accumulated Fees 📤 + +Fees accumulate in the vault as yield is generated. To distribute them, use the `distribute-fees` endpoint. + +### Build the Transaction + +```bash +curl -X POST "https://api.defindex.io/vault/YOUR_VAULT_ADDRESS/distribute-fees?network=mainnet" \ + -H "Authorization: Bearer YOUR_JWT_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "caller": "GMANAGER_ADDRESS..." + }' +``` + +**Parameters:** + +| Parameter | Type | Description | +|-----------|--------|---------------------------------| +| `caller` | string | Manager OR Fee Receiver address | + +**🔍 What this does:** + +1. Calculates the locked fee amount +2. **Splits** the fees between the vault fee receiver and the DeFindex protocol receiver based on the `defindexFee` rate +3. Sends each party their share +4. Returns an **unsigned XDR** transaction + +### Sign and Submit + +Sign the returned XDR and submit it using the `/send` endpoint (same flow as Step 2). + +**🚨 Important notes:** + +* Can be called by **Manager** OR **Fee Receiver** +* Fees must be locked before they can be distributed (Step 2 locks fees automatically) +* Distribution sends actual tokens to the receiver addresses + +--- + +## 🔄 Complete Fee Management Workflow + +```md +📐 CHECK CURRENT FEES +GET /vault/{address}?network=mainnet +GET /vault/{address}/get/fee-receiver?network=mainnet + ↓ + +💰 UPDATE FEE RATE (Optional) +POST /vault/{address}/lock-fees + → Locks accrued fees + sets new rate + → Sign & submit unsigned XDR + ↓ + +🔄 CHANGE FEE RECEIVER (Optional) +POST /vault/{address}/set/fee-receiver + → Updates receiver address + → Sign & submit unsigned XDR + ↓ + +📤 DISTRIBUTE FEES +POST /vault/{address}/distribute-fees + → Splits fees: partner share + DeFindex share + → Sign & submit unsigned XDR + ↓ + +✅ FEES DISTRIBUTED! + → Fee Receiver gets vault fee share + → DeFindex gets protocol fee share +``` + +--- + +## 📊 BPS Quick Reference Table + +| BPS | Percentage | Annual fee on $10,000 yield | +|-------|------------|-----------------------------| +| 100 | 1% | $100 | +| 250 | 2.5% | $250 | +| 500 | 5% | $500 | +| 1000 | 10% | $1,000 | +| 2000 | 20% | $2,000 | +| 3000 | 30% | $3,000 | +| 5000 | 50% | $5,000 | +| 9000 | 90% | $9,000 | + +Remember: fees are charged on **yield only**, not on deposited capital. + +--- + +## 🔒 Security Best Practices + +### ✅ DO + +* Use a **multisig wallet** for the Manager role +* Use a **dedicated, secure wallet** for the Fee Receiver +* **Verify fee values** before signing transactions (double-check BPS math) +* **Test on testnet** before making mainnet changes +* Distribute fees **regularly** to avoid large accumulated amounts + +### ❌ DON'T + +* Set fees above **9000 BPS** (the transaction will fail) +* Share your **API key** or expose it in client-side code +* Change the fee receiver to an **uncontrolled address** +* Skip **transaction verification** before signing + +--- + +## 🔧 Common Troubleshooting + +### Problem: "Permission denied" or "Unauthorized" + +**Solution**: Only the Manager role can update fees. Verify you're using the correct caller address. For `set/fee-receiver` and `distribute-fees`, the current Fee Receiver can also call these. + +### Problem: "Fee exceeds maximum" + +**Solution**: The maximum allowed vault fee is 9000 BPS (90%). Reduce the `new_fee_bps` value. + +### Problem: "No fees to distribute" + +**Solution**: Fees accumulate as the vault generates yield. If the vault hasn't generated yield since the last distribution, there may be nothing to distribute. Also ensure fees have been locked first. + +### Problem: "403 Forbidden" + +**Solution**: Check your API key is correct and not expired. See [Getting Started with API](../api.md) for key generation. + +### Problem: Transaction fails after signing + +**Solution**: The unsigned XDR may have expired. Rebuild the transaction and sign again promptly. Also ensure your wallet has enough XLM for network fees. + +--- + +## 📚 Related Resources + +* [Partner Fees](../../getting-started/partner-fees.md) — Conceptual overview of the fee model +* [Vault Roles](../../getting-started/vault-roles.md) — Understanding Manager and Fee Receiver roles +* [Beginner Guide](beginner-guide.md) — Full walkthrough of the build → sign → submit flow +* [API Documentation](https://api.defindex.io/docs) — Complete API reference +* [Getting Started with API](../api.md) — API key setup and client configuration From f24f187cb8c33dc8a2dc17433c0fa7698d5cf210 Mon Sep 17 00:00:00 2001 From: coderipper Date: Wed, 25 Mar 2026 12:49:50 -0600 Subject: [PATCH 2/2] fix(docs): replace YOUR_JWT_TOKEN with YOUR_API_KEY for consistency The rest of the docs use API keys directly in Bearer headers, not JWTs. --- .../guides-and-tutorials/setting-partner-fees.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/apps/docs/api-integration-guide/guides-and-tutorials/setting-partner-fees.md b/apps/docs/api-integration-guide/guides-and-tutorials/setting-partner-fees.md index 865d62cb..a45c1274 100644 --- a/apps/docs/api-integration-guide/guides-and-tutorials/setting-partner-fees.md +++ b/apps/docs/api-integration-guide/guides-and-tutorials/setting-partner-fees.md @@ -55,7 +55,7 @@ Before making changes, verify the current fee settings on your vault. ```bash curl -X GET "https://api.defindex.io/vault/YOUR_VAULT_ADDRESS?network=mainnet" \ - -H "Authorization: Bearer YOUR_JWT_TOKEN" + -H "Authorization: Bearer YOUR_API_KEY" ``` The response includes fee configuration: @@ -80,7 +80,7 @@ The response includes fee configuration: ```bash curl -X GET "https://api.defindex.io/vault/YOUR_VAULT_ADDRESS/get/fee-receiver?network=mainnet" \ - -H "Authorization: Bearer YOUR_JWT_TOKEN" + -H "Authorization: Bearer YOUR_API_KEY" ``` Response: @@ -101,7 +101,7 @@ To change the fee rate on your vault, use the `lock-fees` endpoint. This endpoin ```bash curl -X POST "https://api.defindex.io/vault/YOUR_VAULT_ADDRESS/lock-fees?network=mainnet" \ - -H "Authorization: Bearer YOUR_JWT_TOKEN" \ + -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "new_fee_bps": 3000, @@ -136,7 +136,7 @@ The response contains an unsigned XDR transaction: ```bash curl -X POST "https://api.defindex.io/send" \ - -H "Authorization: Bearer YOUR_JWT_TOKEN" \ + -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "xdr": "SIGNED_XDR_HERE...", @@ -160,7 +160,7 @@ To redirect fee payments to a different address, use the `set/fee-receiver` endp ```bash curl -X POST "https://api.defindex.io/vault/YOUR_VAULT_ADDRESS/set/fee-receiver?network=mainnet" \ - -H "Authorization: Bearer YOUR_JWT_TOKEN" \ + -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "new_address": "GNEW_RECEIVER_ADDRESS...", @@ -200,7 +200,7 @@ Fees accumulate in the vault as yield is generated. To distribute them, use the ```bash curl -X POST "https://api.defindex.io/vault/YOUR_VAULT_ADDRESS/distribute-fees?network=mainnet" \ - -H "Authorization: Bearer YOUR_JWT_TOKEN" \ + -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "caller": "GMANAGER_ADDRESS..."