From c0b0763182b6f5e009246a5a1c1ab5fac62d5ca2 Mon Sep 17 00:00:00 2001
From: Aimen Sahnoun <aimensahnoun@outlook.com>
Date: Mon, 2 Mar 2026 16:38:21 +0400
Subject: [PATCH] =?UTF-8?q?docs(api-features):=20add=20protocol-fees=20pag?=
 =?UTF-8?q?e=20and=20include=20it=20in=20Fee=20Structure=20nav=20Introduce?=
 =?UTF-8?q?=20a=20dedicated=20Protocol=20Fees=20page=20using=20legacy=20fe?=
 =?UTF-8?q?e=20documentation=20as=20the=20source=20of=20truth,=20and=20reg?=
 =?UTF-8?q?ister=20it=20in=20API=20Features=20navigation.=20-=20add=20`api?=
 =?UTF-8?q?-features/protocol-fees.mdx`=20with=20legacy-aligned=20protocol?=
 =?UTF-8?q?=20fee=20content=20-=20preserve=20legacy=20fee=20structure=20de?=
 =?UTF-8?q?tails=20(rate,=20cap,=20covered=20payment=20types)=20-=20keep?=
 =?UTF-8?q?=20legacy=20=E2=80=9CWho=20Pays=20the=20Fee=3F=E2=80=9D=20and?=
 =?UTF-8?q?=20=E2=80=9CShifting=20the=20Fee=20to=20the=20Payee=E2=80=9D=20?=
 =?UTF-8?q?explanations=20and=20examples=20-=20include=20protocol=20+=20pl?=
 =?UTF-8?q?atform=20fee=20coexistence=20section=20and=20metadata=20respons?=
 =?UTF-8?q?e=20example=20-=20update=20`docs.json`=20to=20add=20`api-featur?=
 =?UTF-8?q?es/protocol-fees`=20under=20Fee=20Structure=20This=20separates?=
 =?UTF-8?q?=20protocol-fee=20policy=20from=20platform-fee=20implementation?=
 =?UTF-8?q?=20and=20improves=20Fee=20Structure=20discoverability.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 api-features/protocol-fees.mdx | 81 ++++++++++++++++++++++++++++++++++
 docs.json                      |  1 +
 2 files changed, 82 insertions(+)
 create mode 100644 api-features/protocol-fees.mdx

diff --git a/api-features/protocol-fees.mdx b/api-features/protocol-fees.mdx
new file mode 100644
index 0000000..31ec1f8
--- /dev/null
+++ b/api-features/protocol-fees.mdx
@@ -0,0 +1,81 @@
+---
+title: "Protocol Fees"
+description: "Protocol fee model applied by Request Network API payments"
+---
+
+## Protocol Fee
+
+Request Network charges a protocol fee on all payments processed through the API.
+
+## Fee Structure
+
+| Fee Type     | Rate                   | Cap                                               |
+| ------------ | ---------------------- | ------------------------------------------------- |
+| Protocol Fee | 5 basis points (0.05%) | ~$25/€25 for main USD and EUR backed stablecoins |
+
+The protocol fees applies to all the payment types
+
+- ERC20 token payments
+- Native currency payments (ETH, POL, etc.)
+- Conversion payments
+- Batch payments
+- Crosschain payments
+- Subscription (coming soon)
+
+## Who Pays the Fee?
+
+By default, the payer bears the protocol fee. The fee is added on top of the invoice amount.
+
+### Example
+
+- Invoice amount: 1000 USDC
+- Protocol fee: 1000 x 0.05% = 0.50 USDC
+- Total paid by payer: 1000.50 USDC + gas fee
+- Amount received by payee: 1000 USDC
+
+For larger payments with stablecoins, the fee is capped:
+
+- Payment of 100,000 USDC -> Fee capped at 25 USDC (not 50 USDC)
+
+## Shifting the Fee to the Payee
+
+If you want the payee to bear the protocol fee instead of the payer, simple reduce the invoice amount by 5bps (0.05%) before creating the request.
+
+### Example:
+
+- Original intended payment: 1000 USDC
+- Reduce by 0.05%: 1000 - (1000 x 0.05%) = 999.50 USDC
+- Total paid by the payer: 1000 USDC + gas fee
+- Amount received by payee: 999.95 USDC
+
+This way, the payer pays approximately the original amount while the payee effectively absorbs the fee.
+
+## Platform Fees
+
+You can add your own platform fee on top of the protocol fee. Both fees are handled automatically when you configure a platform fee in your request.
+
+To set up platform fees, include the following parameters in your payment request:
+
+- `feePercentage`: Your platform fee percentage (e.g., "2.5").
+- `feeAddress`: The wallet address to receive your platform fees.
+
+When both protocol and platform fees are configured, the API automatically batches them into a single transaction for the payer.
+
+### Fee Information In Responses
+
+Every API response includes the fee details in the metadata:
+
+```json
+{
+  "metadata": {
+    "protocolFee": {
+      "percentage": "0.05",
+      "address": "0x..."
+    },
+    "platformFee": {
+      "percentage": "2.5",
+      "address": "0x..."
+    }
+  }
+}
+```
diff --git a/docs.json b/docs.json
index cbf0380..485b97c 100644
--- a/docs.json
+++ b/docs.json
@@ -111,6 +111,7 @@
                 "group": "Fee Structure",
                 "pages": [
                   "api-features/platform-fees",
+                  "api-features/protocol-fees",
                   "api-features/fee-breakdowns"
                 ]
               }