Overview
As an orchestrator, you can attach fees to the payments made under the client IDs you’ve linked. Fees are configured with thex-orchestrator-key header on the /v2/orchestrators/fee-configs endpoints.
Orchestrator fees are separate from — and stack with — the Request Network protocol fee and any per-request platform fee. 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:- Per-client-ID configuration — an orchestrator fee scoped to a single linked client ID. It replaces the orchestrator default with the same
flowandfeeBearerpair. - Orchestrator default — an orchestrator fee that applies to all of the orchestrator’s linked client IDs.
- Protocol fee — set by Request Network (falls back to the standard protocol default when none is configured).
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.
The fee configuration is captured when a payment is created. Later changes apply only to newly created payments.
Fee configuration fields
integer
required
Fee rate in basis points,
0–10000 (10000 = 100%). For example, 250 is 2.5%.string
Optional maximum fee in USD (as a string). Caps the fee for large payments.
string
required
Who absorbs the fee:
payer (added on top of what the payer pays) or recipient (deducted from what the recipient receives).string
required
Which payment direction the fee applies to:
incoming (get-paid flows) or outgoing (pay/payout flows).string
EVM address that receives the fee. At least one of
evmRecipientAddress or tronRecipientAddress is required.string
Tron address that receives the fee. At least one of
evmRecipientAddress or tronRecipientAddress is required.string
Optional activation state:
active (the default) or disabled.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.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.
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.Fee bearer and flow semantics
flow: incomingapplies to payments you receive (“get paid”).flow: outgoingapplies to payouts you send (“pay”).feeBearer: payeradds the fee on top of the amount the payer pays.feeBearer: recipientdeducts 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:
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
Protocol fees
Request Network’s protocol-level fee, rate, and cap.
Platform fees
Per-request integrator fees via feePercentage/feeAddress.
Fee breakdowns
Where fee line items appear in API responses.