Skip to main content

​
Overview

Creates an unsigned transaction for claiming accumulated fees from a Meteora DAMM v2 (Dynamic AMM) pool. The API validates available fees, builds a combined transaction that claims fees and transfers 70% to the configured destination address, and returns the transaction ready for user signing.
Important: This endpoint only claims fees from the first position in the pool to keep transaction size manageable. If multiple positions exist, subsequent calls are needed to claim from other positions.
curl -X POST https://api.zcombinator.io/fee-claim/claim \
  -H "Content-Type: application/json" \
  -d '{
    "payerPublicKey": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
  }'

​
Request Parameters

​
payerPublicKey
string
required
Base58 encoded public key of the wallet that will pay transaction fees. This wallet only covers network transaction costs and cannot redirect claimed fees.

​
Response

​
success
boolean
Indicates if the operation was successful
​
transaction
string
Base58 encoded unsigned transaction that needs to be signed by the fee payer
​
requestId
string
Unique identifier for this fee claim request (needed for confirmation)
​
poolAddress
string
Address of the Meteora DAMM v2 pool
​
tokenAMint
string
Mint address of Token A in the pool
​
tokenBMint
string
Mint address of Token B in the pool
​
isTokenBNativeSOL
boolean
Whether Token B is native SOL (unwrapped after claim)
​
totalPositions
number
Total number of positions owned by the LP owner in this pool
​
claimingPosition
number
Position number being claimed (always 1 for this endpoint)
​
instructionsCount
number
Number of instructions in the transaction
​
estimatedFees
object
Object containing fee estimates with the following fields:
  • tokenA (string): Total Token A fees to be claimed
  • tokenB (string): Total Token B fees to be claimed
  • tokenATransfer (string): Token A amount to be transferred (70%)
  • tokenBTransfer (string): Token B amount to be transferred (70%)
​
message
string
Instructions for the next step in the process

​
Success Response

{
  "success": true,
  "transaction": "4MzR7dxJNJRVP1Q6k7Y3j8X...",
  "requestId": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "poolAddress": "CPMMoo8L3F4NbTegBCKVNunggL7H1ZpdTHKxQB5qKP1C",
  "tokenAMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "tokenBMint": "So11111111111111111111111111111111111111112",
  "isTokenBNativeSOL": true,
  "totalPositions": 3,
  "claimingPosition": 1,
  "instructionsCount": 8,
  "estimatedFees": {
    "tokenA": "1000000",
    "tokenB": "500000000",
    "tokenATransfer": "700000",
    "tokenBTransfer": "350000000"
  },
  "message": "Sign this transaction and submit to /fee-claim/confirm (Token B will be transferred as native SOL)"
}

​
Error Responses

{
  "error": "Missing required field: payerPublicKey"
}

{
  "error": "Invalid payerPublicKey format"
}
The provided public key is not a valid Solana address.
{
  "error": "No positions found for the LP owner in this pool"
}
The protocol wallet does not have any LP positions in the configured pool.
{
  "error": "No fees available to claim"
}
All fees have already been claimed or no fees have accumulated yet.
{
  "error": "Server configuration incomplete. Missing required environment variables."
}
Required environment variables (RPC_URL, DAMM_POOL_ADDRESS, PROTOCOL_PRIVATE_KEY, FEE_DESTINATION_ADDRESS) are not configured.
{
  "error": "Failed to create fee claim transaction"
}

​
Process Flow

This endpoint performs several validations and transaction building steps:
1

Validate Parameters

Ensures payerPublicKey is provided and is a valid Solana address
2

Validate Environment

Checks that required environment variables are configured (RPC_URL, DAMM_POOL_ADDRESS, PROTOCOL_PRIVATE_KEY, FEE_DESTINATION_ADDRESS)
3

Initialize Connection

Connects to Solana RPC and loads the LP owner keypair
4

Fetch Pool State

Retrieves the current state of the Meteora DAMM v2 pool
5

Get User Positions

Fetches all LP positions owned by the protocol wallet
6

Calculate Unclaimed Fees

Uses Meteora SDK to calculate accurate unclaimed fees for all positions
7

Build Combined Transaction

Creates a transaction with:
  • ATA creation instructions (if needed)
  • Fee claim instruction (first position only)
  • Transfer instructions (70% to destination, 30% remains with LP owner)
8

Handle Native SOL

If Token B is wrapped SOL, the transaction includes native SOL transfer logic (Meteora automatically unwraps wSOL to native SOL)
9

Store Transaction Data

Temporarily stores transaction details with requestId for confirmation step
10

Return Unsigned Transaction

Returns the Base58 encoded transaction for user signing

​
Fee Distribution

The claimed fees are automatically split:
  • 70%: Transferred to the configured destination address (FEE_DESTINATION_ADDRESS)
  • 30%: Remains with the LP owner wallet
This split is hardcoded and cannot be modified by the fee payer.

​
Native SOL Handling

Special handling for wrapped SOL (wSOL):When Token B is the native SOL mint (So11111111111111111111111111111111111111112):
  1. Meteora automatically unwraps wSOL to native SOL during the claim
  2. No token account is created for Token B
  3. The 70% transfer uses SystemProgram.transfer instead of SPL token transfer
  4. Fees are received directly as native SOL in the wallet

​
Request ID

The requestId is essential for the confirmation step:
  • Format: Random 16-byte hex string
  • Expiration: Automatically cleaned up after 15 minutes
  • Required: Must be provided to /fee-claim/confirm

​
Rate Limiting

This endpoint is subject to rate limiting:
  • 10 requests per 5-minute window per IP
  • Returns HTTP 429 when limit exceeded with message: “Too many fee claim requests, please wait a moment.”

​
Security Considerations

No authorization required:
  • Fee destinations are hardcoded in environment variables
  • Transaction validation ensures funds can ONLY go to configured addresses
  • Fee payer only covers transaction costs, cannot redirect fees
  • This allows anyone to trigger fee claims for the protocol

​
Next Steps

After receiving the unsigned transaction:
  1. Deserialize the transaction using @solana/web3.js
  2. Sign the transaction with your wallet (fee payer)
  3. Submit the signed transaction to /fee-claim/confirm

​
Transaction Storage

Transaction data is stored temporarily in memory:
  • Storage Duration: 10 minutes (validation) to 15 minutes (cleanup)
  • Cleanup: Automatic cleanup every 5 minutes
  • Expiration: You must call /fee-claim/confirm within the time window

​
Position Claiming

Multiple positions: If totalPositions > 1, you need to call this endpoint multiple times to claim fees from all positions. Each call claims fees from the first unclaimed position.