Skip to main content

​
Overview

As an orchestrator, 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 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:
  1. Per-client-ID override — an orchestrator fee scoped to a single linked client ID. Wins its slot over the orchestrator default.
  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).
There is no per-client-ID protocol fee — client IDs can only override orchestrator fees.

​
Fee configuration fields

​
bps
integer
required
Fee rate in basis points, 0–10000 (10000 = 100%). For example, 250 is 2.5%.
​
usdCap
string
Optional maximum fee in USD (as a string). Caps the fee for large payments.
​
feeBearer
string
required
Who absorbs the fee: payer (added on top of what the payer pays) or recipient (deducted from what the recipient receives).
​
flow
string
required
Which payment direction the fee applies to: incoming (get-paid flows) or outgoing (pay/payout flows). Immutable — see below.
​
evmRecipientAddress
string
EVM address that receives the fee. At least one of evmRecipientAddress or tronRecipientAddress is required.
​
tronRecipientAddress
string
Tron address that receives the fee. At least one of evmRecipientAddress or tronRecipientAddress is required.
A fee config’s identity is its combination of fee type, flow, and feeBearer. These are immutable — to change flow or feeBearer, disable the existing config and create a new one. You can update bps, usdCap, recipient addresses, and status.

​
Fee bearer and flow semantics

  • flow: incoming applies to payments you receive (“get paid”); its default bearer is the recipient.
  • flow: outgoing applies to payouts you send (“pay”); its default bearer is the payer.
  • 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 orchestrator default fee (2.5%, payer-borne, on incoming payments)
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"
  }'
OperationEndpoint
Create a fee or per-client-ID overridePOST /v2/orchestrators/fee-configs
List fee configs (filter with ?clientId)GET /v2/orchestrators/fee-configs
Update a fee configPATCH /v2/orchestrators/fee-configs/:id
Disable a fee configDELETE /v2/orchestrators/fee-configs/:id
To scope a fee to a single linked client ID (an override rather than the orchestrator-wide default), provide that clientId when creating, listing, or disabling the config.

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.