diff --git a/api-reference/endpoint/affiliate/get-earnings.mdx b/api-reference/endpoint/affiliate/get-earnings.mdx new file mode 100644 index 0000000..1c5b119 --- /dev/null +++ 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 index 79a62ca..df889b3 100644 --- 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. \ No newline at end of file +Total fees processed by Garden from genesis in USD. \ No newline at end of file diff --git a/api-reference/openapi.json b/api-reference/openapi.json index ab6ea87..61dc6c1 100644 --- 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" + } + ] + } + } + } + } + } + } } } } \ No newline at end of file diff --git a/changelog.mdx b/changelog.mdx index 348bea8..1911a87 100644 --- a/changelog.mdx +++ b/changelog.mdx @@ -2,6 +2,13 @@ title: "Changelog" description: "Product updates and announcements" --- + + + ### New endpoints + + - Add `/apps/earnings` endpoint for fetching affiliate earnings + + ### New endpoints diff --git a/developers/affiliate-fees.mdx b/developers/affiliate-fees.mdx index e7e9d1c..7a0d443 100644 --- 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 + +## 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" + } + ] +} +``` + + + The `claim_amount`, `claim_amount_usd`, `claim_signature`, and `claim_contract` fields are only included when you have unclaimed earnings available. + + +### 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: + + + 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. + + +```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(''); + + // 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 index b37835c..59f33c6 100644 --- 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" + ] } ] },