> ## Documentation Index
> Fetch the complete documentation index at: https://requestnetwork-fix-req-350-remove-unused-webhook-events.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Orchestrator fees

> Configure orchestrator fee defaults and client-specific configurations, including caps, fee bearer, payment flow, and resolution.

## Overview

As an [orchestrator](/orchestrators/overview), you can attach fees to the payments made under the client IDs you've linked. Fees are configured with the `x-orchestrator-key` header on the `/v2/orchestrators/fee-configs` endpoints.

Orchestrator fees are separate from — and stack with — the Request Network [protocol fee](/api-features/protocol-fees) and any per-request [platform fee](/api-features/platform-fees). On the orchestrator API you manage **orchestrator fees only**; the protocol fee is administered by Request Network.

## Fee layers and precedence

A payment can be subject to up to three fee layers. They resolve from most to least specific:

1. **Per-client-ID configuration** — an orchestrator fee scoped to a single linked client ID. It replaces the orchestrator default with the same `flow` and `feeBearer` pair.
2. **Orchestrator default** — an orchestrator fee that applies to all of the orchestrator's linked client IDs.
3. **Protocol fee** — set by Request Network (falls back to the standard protocol default when none is configured).

If a client-specific configuration uses a `flow` and `feeBearer` pair that the default does not use, it adds that fee instead of replacing anything. There is no per-client-ID protocol fee — client IDs can only configure orchestrator fees.

Each default or client-specific configuration can use the four unique `flow` and `feeBearer` combinations: `incoming` or `outgoing`, paired with `payer` or `recipient`. A single flow can have at most two configurations: one payer-borne and one recipient-borne.

<Note>
  The fee configuration is captured when a payment is created. Later changes apply only to newly created payments.
</Note>

## Fee configuration fields

<ParamField body="bps" type="integer" required>
  Fee rate in basis points, `0`–`10000` (`10000` = 100%). For example, `250` is 2.5%.
</ParamField>

<ParamField body="usdCap" type="string">
  Optional maximum fee in USD (as a string). Caps the fee for large payments.
</ParamField>

<ParamField body="feeBearer" type="string" required>
  Who absorbs the fee: `payer` (added on top of what the payer pays) or `recipient` (deducted from what the recipient receives).
</ParamField>

<ParamField body="flow" type="string" required>
  Which payment direction the fee applies to: `incoming` (get-paid flows) or `outgoing` (pay/payout flows).
</ParamField>

<ParamField body="evmRecipientAddress" type="string">
  EVM address that receives the fee. At least one of `evmRecipientAddress` or `tronRecipientAddress` is required.
</ParamField>

<ParamField body="tronRecipientAddress" type="string">
  Tron address that receives the fee. At least one of `evmRecipientAddress` or `tronRecipientAddress` is required.
</ParamField>

<ParamField body="status" type="string">
  Optional activation state: `active` (the default) or `disabled`.
</ParamField>

<ParamField body="clientId" type="string">
  Optional linked `cli_*` client ID. On creation, it creates a client-specific configuration instead of the orchestrator-wide default. On update, it targets that client-specific configuration; it is not itself mutable.
</ParamField>

<Note>
  A single fee configuration can include both recipient addresses to apply on EVM and Tron. Provide only the address for the chain you collect on when the fee is single-chain.
</Note>

<Note>
  A fee config's identity is its fee type (always `orchestrator_fee`), `flow`, and `feeBearer`. These fields are **immutable**. To change the flow or bearer, disable the existing configuration and create a new one. You can update `bps`, `usdCap`, recipient addresses, and `status`. Disabling a configuration does not free its `flow` and `feeBearer` pair; update or reactivate that configuration instead of creating a duplicate.
</Note>

## Fee bearer and flow semantics

* **`flow: incoming`** applies to payments you receive ("get paid").
* **`flow: outgoing`** applies to payouts you send ("pay").
* **`feeBearer: payer`** adds the fee on top of the amount the payer pays.
* **`feeBearer: recipient`** deducts the fee from the amount the recipient receives. A recipient-borne fee cannot exceed the gross amount.

## Managing fee configs

Create an example orchestrator-wide default:

```bash theme={null}
curl -X POST "https://api.request.network/v2/orchestrators/fee-configs" \
  -H "x-orchestrator-key: orc_YOUR_ORCHESTRATOR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bps": 250,
    "feeBearer": "payer",
    "flow": "incoming",
    "evmRecipientAddress": "0x742d35CC6634c0532925a3B844BC9e7595f8fA40"
  }'
```

| Operation                                             | Endpoint                                   |
| ----------------------------------------------------- | ------------------------------------------ |
| Create a default fee or client-specific configuration | `POST /v2/orchestrators/fee-configs`       |
| List fee configs (filter with `?clientId`)            | `GET /v2/orchestrators/fee-configs`        |
| Update a fee config                                   | `PATCH /v2/orchestrators/fee-configs/:id`  |
| Disable a fee config                                  | `DELETE /v2/orchestrators/fee-configs/:id` |

Omit `clientId` to manage the orchestrator-wide default. To target a single linked client ID, provide `clientId` when creating or updating a configuration, and as a query parameter when listing or disabling one. Refer to the endpoint reference for the request schema.

## Related

<CardGroup cols={3}>
  <Card title="Protocol fees" href="/api-features/protocol-fees" icon="building-columns">
    Request Network's protocol-level fee, rate, and cap.
  </Card>

  <Card title="Platform fees" href="/api-features/platform-fees" icon="percent">
    Per-request integrator fees via feePercentage/feeAddress.
  </Card>

  <Card title="Fee breakdowns" href="/api-features/fee-breakdowns" icon="receipt">
    Where fee line items appear in API responses.
  </Card>
</CardGroup>