gardenfi · SaiKiranMatta · Aug 6, 2025 · Aug 6, 2025 · Aug 6, 2025 · Aug 6, 2025
diff --git a/api-reference/endpoint/affiliate/get-earnings.mdx b/api-reference/endpoint/affiliate/get-earnings.mdx
@@ -0,0 +1,7 @@
+---
+title: 'Earnings'
+openapi: 'GET /apps/earnings'
+version: 1.0
+---
+
+Get affiliate earnings and claimable amounts for different assets.
diff --git a/api-reference/endpoint/get-fees.mdx b/api-reference/endpoint/get-fees.mdx
@@ -1,7 +1,7 @@
 ---
-title: 'Fees'
+title: 'Total Fees'
 openapi: 'GET /fees'
 version: 1.0
 --- 
 
-Returns total fees processed by Garden from genesis in USD, or affiliate fees if a `garden-app-id` header is provided.
+Total fees processed by Garden from genesis in USD.
diff --git a/api-reference/openapi.json b/api-reference/openapi.json
@@ -163,32 +163,54 @@
           }
         ]
       },
-      "AffiliateFeeItem": {
+      "AffiliateEarningsItem": {
         "type": "object",
         "properties": {
           "total_earnings": {
-            "type": "string"
+            "type": "string",
+            "description": "Total earnings in asset units for the affiliate."
+          },
+          "total_earnings_usd": {
+            "type": "string",
+            "description": "Total earnings in USD for the mentioned asset for the affiliate."
           },
           "affiliate": {
-            "type": "string"
+            "type": "string",
+            "description": "The address that will receive the earnings."
           },
           "asset": {
             "$ref": "#/components/schemas/AffiliateFeeAsset"
           },
+          "token_address": {
+            "type": "string",
+            "description": "Contract address for the affiliate fee asset."
+          },
           "claim_amount": {
-            "type": "string"
+            "type": "string",
+            "description": "Amount available for claiming in asset units. Only included if the affiliate has not yet claimed their earnings."
           },
-          "claim_transaction": {
-            "$ref": "#/components/schemas/EVMTransaction"
+          "claim_amount_usd": {
+            "type": "string",
+            "description": "Amount available for claiming in USD. Only included if the affiliate has not yet claimed their earnings."
+          },
+          "claim_signature": {
+            "type": "string",
+            "description": "Signature for claiming earnings. Only included if the affiliate has not yet claimed their earnings."
+          },
+          "claim_contract": {
+            "type": "string",
+            "description": "Contract address for claiming earnings. Only included if the affiliate has not yet claimed their earnings."
           }
         },
         "required": [
           "total_earnings",
+          "total_earnings_usd",
           "affiliate",
-          "asset"
+          "asset",
+          "token_address"
         ]
       },
-      "AffiliateFeesResponse": {
+      "AffiliateEarningsResponse": {
        "allOf": [
           {
             "$ref": "#/components/schemas/Response"
@@ -202,7 +224,7 @@
               "result": {
                 "type": "array",
                 "items": {
-                  "$ref": "#/components/schemas/AffiliateFeeItem"
+                  "$ref": "#/components/schemas/AffiliateEarningsItem"
                 }
               }
             }
@@ -1352,69 +1374,17 @@
     "/fees": {
       "get": {
         "summary": "Get swap fees.",
-        "security": [],
-        "parameters": [
-          {
-            "in": "header",
-            "name": "garden-app-id",
-            "required": false,
-            "schema": {
-              "type": "string"
-            },
-            "description": "Garden app ID for affiliate fee information"
-          }
-        ],
         "responses": {
           "200": {
-            "description": "Total swap fees or affiliate fees if garden-app-id is provided. For affiliate fees, claim_amount and claim_transaction are only included if the affiliate has not yet claimed their fees.",
+            "description": "Total swap fees.",
             "content": {
               "application/json": {
                 "schema": {
-                  "oneOf": [
-                    {
-                      "$ref": "#/components/schemas/ResponseString",
-                      "title": "Total Fees"
-                    },
-                    {
-                      "$ref": "#/components/schemas/AffiliateFeesResponse",
-                      "title": "Affiliate Fees"
-                    }
-                  ]
+                  "$ref": "#/components/schemas/ResponseString"
                 },
-                "examples": {
-                  "total-fees": {
-                    "summary": "Total Fees Response",
-                    "value": {
-                      "success": true,
-                      "result": "2668122"
-                    }
-                  },
-                  "affiliate-fees": {
-                    "summary": "Affiliate Fees Response",
-                    "value": {
-                      "success": true,
-                      "result": [
-                        {
-                          "total_earnings": "150750000",
-                          "affiliate": "0x004Cc75ACF4132Fc08cB6a252E767804F303F729",
-                          "asset": "ethereum:usdc",
-                          "claim_amount": "50750000",
-                          "claim_transaction": {
-                            "to": "0x5EbEC4D8DA437b2BAD656D43d40fE412bA5D217a",
-                            "value": "0x0",
-                            "chain_id": 1,
-                            "data": "0x4ede0ab7000000000000000000000000661ba32eb5f86cab358ddbb7f264b10c5825e2dd0000000000000000000000000000000000000000000000000000000000069780000000000000000000000000000000000000000000000000000000000000c3503331ff69aca609e06dcd4b97223667611d66bb4e8b56e26fc0ff53c49a1ed04d00000000000000000000000000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000000000",
-                            "gas_limit": "0x30d40"
-                          }
-                        },
-                        {
-                          "total_earnings": "3000000",
-                          "affiliate": "0x004Cc75ACF4132Fc08cB6a252E767804F303F729",
-                          "asset": "ethereum:cbbtc"
-                        }
-                      ]
-                    }
-                  }
+                "example": {
+                    "status": "Ok",
+                    "result": "2668122"
                 }
               }
             }
@@ -1765,6 +1735,46 @@
           }
         }
       }
+    },
+    "/apps/earnings": {
+      "get": {
+        "summary": "Get affiliate earnings.",
+        "responses": {
+          "200": {
+            "description": "List of affiliate earnings.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AffiliateEarningsResponse"
+                },
+                "example": {
+                  "status": "Ok",
+                  "result": [
+                    {
+                      "total_earnings": "15075000000",
+                      "total_earnings_usd": "15075",
+                      "affiliate": "0x004Cc75ACF4132Fc08cB6a252E767804F303F729",
+                      "asset": "ethereum:usdc",
+                      "token_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+                      "claim_amount": "5075000000",
+                      "claim_amount_usd": "5075",
+                      "claim_signature": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1b",
+                      "claim_contract": "0x5EbEC4D8DA437b2BAD656D43d40fE412bA5D217a"
+                    },
+                    {
+                      "total_earnings": "30000000",
+                      "total_earnings_usd": "30000",
+                      "affiliate": "0x004Cc75ACF4132Fc08cB6a252E767804F303F729",
+                      "asset": "ethereum:cbbtc",
+                      "token_address": "0xcbB7C0000aB88B473b1f5aFd9ef808440eed33Bf"
+                    }
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
     }
   }
 }
diff --git a/changelog.mdx b/changelog.mdx
@@ -2,6 +2,13 @@
 title: "Changelog"
 description: "Product updates and announcements"
 ---
+
+<Update label="August 21, 2025" description="v2.0.3" tags={["API"]}>
+  ### New endpoints
+
+  - Add `/apps/earnings` endpoint for fetching affiliate earnings
+</Update>
+
 <Update label="July 15, 2025" description="v2.0.1" tags={["API"]}>
   ### New endpoints
 

diff --git a/developers/affiliate-fees.mdx b/developers/affiliate-fees.mdx
@@ -160,3 +160,98 @@ For example, a 30 bps fee could be split by sending 10 bps in USDC to an Ethereu
     </Tab>
 
 </Tabs>
+
+## How to Claim
+
+The claiming process involves two steps: checking your available earnings through the API, then submitting an on-chain transaction to withdraw them.
+
+### Check Available Earnings
+
+First, call the earnings endpoint to get your claimable amounts:
+
+```bash cURL
+curl -X 'GET' 'https://api.garden.finance/v2/apps/earnings' \
+    -H 'garden-app-id: YOUR_APP_ID' \
+    -H 'accept: application/json'
+```
+
+Example response:
+
+```json Success
+{
+  "status": "Ok",
+  "result": [
+    {
+      "total_earnings": "15075000000",
+      "total_earnings_usd": "15075",
+      "affiliate": "0x004Cc75ACF4132Fc08cB6a252E767804F303F729",
+      "asset": "ethereum:usdc",
+      "token_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+      "claim_amount": "5075000000",
+      "claim_amount_usd": "5075",
+      "claim_signature": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1b",
+      "claim_contract": "0x5EbEC4D8DA437b2BAD656D43d40fE412bA5D217a"
+    }
+  ]
+}
+```
+
+<Note>
+  The `claim_amount`, `claim_amount_usd`, `claim_signature`, and `claim_contract` fields are only included when you have unclaimed earnings available.
+</Note>
+
+### Claim Your Earnings
+
+To claim your earnings, you need to call the `claim` function on the distributor contract. Here's how to construct the transaction:
+
+<Note>
+  Make sure to call the claim function on the same chain where you received the rewards. For example, if your earnings are in `ethereum:usdc`, you should use the Ethereum mainnet RPC URL and chain configuration.
+</Note>
+
+```javascript JavaScript
+import { createWalletClient, createPublicClient, http, parseAbi } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { mainnet } from 'viem/chains';
+
+async function claimAffiliateEarnings(claimData) {
+  const account = privateKeyToAccount('<YOUR_PRIVATE_KEY>');
+
+  // Create wallet client for sending transactions
+  const walletClient = createWalletClient({
+    account,
+    chain: mainnet,
+    transport: http('YOUR_RPC_URL'),
+  });
+
+  // Create public client for reading transaction receipts
+  const publicClient = createPublicClient({
+    chain: mainnet,
+    transport: http('YOUR_RPC_URL'),
+  });
+
+  // Parse the ABI for the claim function
+  const abi = parseAbi([
+    'function claim((address toAddress, address tokenAddress, uint256 totalRewards) _claim, bytes _signature)'
+  ]);
+
+  // Prepare claim parameters
+  const claimParams = {
+    toAddress: claimData.affiliate,
+    tokenAddress: claimData.token_address,
+    totalRewards: BigInt(claimData.total_earnings)
+  };
+
+  // Execute the claim transaction
+  const hash = await walletClient.writeContract({
+    address: claimData.claim_contract,
+    abi,
+    functionName: 'claim',
+    args: [claimParams, claimData.claim_signature]
+  });
+
+  // Wait for transaction receipt
+  const receipt = await publicClient.waitForTransactionReceipt({ hash });
+  return receipt;
+}
+```
+
diff --git a/docs.json b/docs.json
@@ -206,6 +206,12 @@
               "api-reference/endpoint/orders/get-instant-refund-hash",
               "api-reference/endpoint/orders/patch"
             ]
+          },
+          {
+            "group": "Affiliate",
+            "pages": [
+              "api-reference/endpoint/affiliate/get-earnings"
+            ]
           }
         ]
       },