> ## Documentation Index
> Fetch the complete documentation index at: https://docs.defindex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Fees through the API

> The four calls that run a vault's fee.

The full fee lifecycle on a deployed vault. For the model itself, read [Fees and revenue](/intro/fees).

<Card title="Or do it in the Console" icon="coins" href="https://console.defindex.io" horizontal>
  Your vault's Fees tab shows the current configuration and runs the same four operations with no code.
</Card>

## Before you start

* The **Manager** role on the vault, or the **Fee Receiver** role for the last two operations.
* An [API key](/integration-guide/quickstart).
* Your vault address, on mainnet or on the [Sandbox](/integration-guide/sandbox).
* A way to sign transactions: Freighter, Stellar Laboratory, or your own signer.

Every write below returns an unsigned XDR. You sign it and submit it with `POST /send`, the same flow as any [Vault Operation](/integration-guide/vault-operations/index).

## Basis points

Fees are expressed in basis points, where `SCALAR_BPS = 10,000` is 100%.

| BPS  | Of the yield |                               |
| ---- | ------------ | ----------------------------- |
| 1000 | 10%          |                               |
| 3000 | 30%          | Common starting point         |
| 5000 | 50%          |                               |
| 9000 | 90%          | The maximum the vault accepts |

The vault rejects anything above 9,000. Fees apply to the **yield** a vault produces.

## Read the current configuration

```bash theme={null}
curl -X GET "https://api.defindex.io/vault/YOUR_VAULT_ADDRESS?network=mainnet" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "name": "My Yield Vault",
  "address": "CABC...XYZ",
  "feesBps": {
    "vaultFee": 3000,
    "defindexFee": 5000
  }
}
```

* `vaultFee`: your fee on the yield. `3000` is 30%.
* `defindexFee`: the DeFindex share **of that fee**, not an extra charge on your users. `5000` is 50% of `vaultFee`. See [how DeFindex is paid](/intro/fees#how-defindex-is-paid).

The fee receiver address is a separate read:

```bash theme={null}
curl -X GET "https://api.defindex.io/vault/YOUR_VAULT_ADDRESS/get/fee-receiver?network=mainnet" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Change the fee

`lock-fees` does two things in one call: it locks whatever has accrued at the old rate, then sets the new one. That ordering is deliberate, so a rate change never reprices yield that was already earned.

```bash theme={null}
curl -X POST "https://api.defindex.io/vault/YOUR_VAULT_ADDRESS/lock-fees?network=mainnet" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "new_fee_bps": 3000,
    "caller": "GMANAGER_ADDRESS..."
  }'
```

| Parameter     | Type   | Description                |
| ------------- | ------ | -------------------------- |
| `new_fee_bps` | number | New rate in BPS, 0 to 9000 |
| `caller`      | string | Manager address            |

Manager only. `new_fee_bps: 0` disables the partner fee: your users then keep all of the yield and no fee is locked for anyone.

## Change the fee receiver

```bash theme={null}
curl -X POST "https://api.defindex.io/vault/YOUR_VAULT_ADDRESS/set/fee-receiver?network=mainnet" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "new_address": "GNEW_RECEIVER_ADDRESS...",
    "caller": "GMANAGER_ADDRESS..."
  }'
```

Callable by the Manager **or** by the current Fee Receiver. Verify the address before signing: the only way back is another update from whoever holds the role afterwards.

<Warning>
  Give the fee receiver a trustline for every asset the vault holds before you distribute. A distribution to an address without one fails.
</Warning>

## Distribute

```bash theme={null}
curl -X POST "https://api.defindex.io/vault/YOUR_VAULT_ADDRESS/distribute-fees?network=mainnet" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "caller": "GMANAGER_ADDRESS..." }'
```

Callable by the Manager or the Fee Receiver. It unwinds the locked amount from the strategies and transfers it, in the same transaction, to your fee receiver and to the DeFindex protocol fee receiver, split by `defindexFee`.

Fees must be locked before they can be distributed. Locking happens automatically on every deposit and withdrawal, so in practice there is usually something to distribute; `lock-fees` forces it.

## When it fails

| What you see            | Why                                                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------------------------------ |
| `Permission denied`     | Only the Manager changes fees. `set/fee-receiver` and `distribute-fees` also accept the current Fee Receiver |
| `Fee exceeds maximum`   | Above 9,000 BPS                                                                                              |
| `No fees to distribute` | Nothing locked since the last distribution, or the vault has not generated yield                             |
| `403 Forbidden`         | API key wrong or expired. See [Getting an API key](/integration-guide/guides-and-tutorials/getting-api-key)  |
| Fails after signing     | The XDR expired. Rebuild, sign and submit promptly, and check the signer holds enough XLM for network fees   |

## Good practice

Use a multisig for the Manager role and a dedicated wallet for the Fee Receiver. Check the BPS arithmetic before signing, since a slip of one digit is a factor of ten. Try it on the [Sandbox](/integration-guide/sandbox) before mainnet. Distribute regularly rather than letting a large balance sit locked.

## Related

* [Fees and revenue](/intro/fees): the model, what your users see, how the split works.
* [Stable APY](/products/stable-apy): let DeFindex move the fee for you against a target.
* [Vault Roles](/integration-guide/vault-roles): who can lock, change and distribute.