Generating Call Data for Claiming Reward Transactions

Overview

The process of claiming rewards within decentralized finance (DeFi) protocols often requires generating specific call data to interact with smart contracts. This call data, a crucial piece of information, instructs the blockchain network to execute the function that releases your earned incentives. This guide explains the essential components and steps involved in creating this transaction call data for claiming bonuses, ensuring a seamless interaction with various DeFi protocols.

Whether you are a developer integrating this functionality or a user understanding the backend process, comprehending how to structure this request is fundamental. The correct construction of this data ensures that your transaction is processed accurately on the blockchain, securing your rightful rewards from staking, lending, or other yield-generating activities.

Understanding the API Endpoint

To initiate the process, a POST request must be sent to a specific API endpoint. This endpoint is designed to receive your claim parameters and return the necessary call data for the transaction.

API Request URL: https://web3.okx.com/api/v5/defi/transaction/bonus

This endpoint acts as a generator, taking your input details about the investment and the desired reward claim, and returning a structured data package ready for blockchain execution.

Core Request Parameters

The request body must contain specific parameters to generate the correct call data. The following table outlines these mandatory and optional fields.

Parameter	Description	Type	Required	Data Type
`address`	The user's wallet address.	Body	Yes	String
`investmentId`	The unique identifier for the investment product.	Body	Yes	String
`userInputList`	An array containing details of the tokens involved.	Body	Yes	Array[Struct]
`>chainId`	The blockchain network ID (defaults to the investment's network).	Body	No	String
`>coinAmount`	The quantity of tokens to be subscribed or claimed.	Body	Yes	String
`>tokenAddress`	The smart contract address of the token (defaults to the investment token address).	Body	No	String
`expectOutputList`	An array detailing the user's expected output from the transaction.	Body	Yes	Array[Struct]
`>chainId`	The blockchain network ID for the output.	Body	No	String
`>coinAmount`	The expected quantity of output tokens.	Body	Yes	String
`>tokenAddress`	The smart contract address of the expected output token.	Body	No	String
`extra`	Additional parameters for specific claim scenarios. See notes below.	Body	No	String

The `extra` Parameter: Detailed Usage

The extra field is critical for handling complex claim scenarios across different DeFi protocols. It is a string that contains key-value pairs to specify precise actions.

Claiming by Reward ID (`claimIndex`)

This method is used for protocols like Ankr, Benqi, Stader, and Lido. It requires a specific reward ID obtained from a user's position or unstaking list.

Key: claimIndex (Number). This ID uniquely identifies the specific reward to be claimed.
Usage Rules:
- If canClaimAll is true (e.g., on BENQI or Tranchess), you can pass an array with one index to claim a single reward or multiple indices to claim all available rewards.
- If canClaimAll is false, you must specify only one claimIndex value.
- For overdue rewards on some protocols (e.g., BENQI), an additional parameter claimOverdue=true can be set to claim them, though the reward token may differ.

Claiming by Platform (`analysisPlatformId`)

This method is for claiming all available rewards from an entire integrated platform, such as Compound, Aave, WePiggy, and others.

Key: analysisPlatformId (Number). This ID represents the specific platform from which to claim all rewards.

Understanding which method to use and how to format the extra parameter is essential for a successful transaction. For a deeper dive into constructing these complex transactions, you can explore more strategies on advanced DeFi interactions.

Response Parameters

Upon a successful API call, the response will contain a data list with the generated call data information, structured as follows:

Parameter	Description	Data Type
`dataList`	The list of generated call data objects.	Array[Struct]
`>from`	The sender's address (user's wallet address).	String
`>to`	The recipient address (target smart contract address).	String
`>value`	The amount of native token to transfer (usually an empty string).	String
`>serializedData`	The final call data to be used in the transaction.	String
`>originalData`	The raw data in JSON format.	JSON String
`>callDataType`	The type of operation (e.g.,授权、申购、赎回、领取).	String
`>signatureData`	Signature data for verifying the call data was generated correctly.	String

Verifying the Response Signature

To ensure the integrity and authenticity of the generated call data, a verification process is recommended. This proves the data was signed by the expected service.

Extract the r, s, and v values from the provided signatureData.
Calculate a verification hash by concatenating the to address, serializedData, and originalData strings.
Use the recovered public key from the signature to verify this hash. A successful verification confirms the call data is authentic and untampered.

Frequently Asked Questions

What is call data in a blockchain transaction?
Call data is encoded information included in a transaction that specifies which function of a smart contract to call and with what parameters. It's essential for executing anything beyond a simple token transfer, such as claiming staking rewards or providing liquidity.

How do I find the correct investmentId for my DeFi product?
The investmentId is typically provided by the platform or API service you are using to explore available DeFi products. You would retrieve it from a list of investment options before initiating a stake or deposit, and then use the same ID when claiming rewards.

What happens if I use the wrong chainId in my request?
Using an incorrect chainId will likely result in the API returning an error or generating call data for the wrong blockchain network. If this erroneous data is broadcast to a different network, the transaction will fail, potentially resulting in a loss of gas fees. Always double-check the network ID.

When should I use claimIndex versus analysisPlatformId?
Use claimIndex when you need to claim a specific, individual reward from a protocol that lists them separately (e.g., Ankr, Lido). Use analysisPlatformId when you want to claim all accumulated rewards from every supported market within an entire lending platform like Compound or Aave in a single transaction.

Is verifying the signature data mandatory?
Verification is optional but highly recommended for security-conscious applications. It ensures that the call data you received was generated by the authentic API service and has not been altered by a man-in-the-middle attack, protecting your funds from malicious transactions.

Can I generate call data for claiming rewards on any EVM-compatible chain?
Yes, the API supports generating call data for any supported EVM-compatible blockchain. You must specify the correct chainId for the network where your assets are staked or lent out, such as Ethereum Mainnet, BNB Smart Chain, or Polygon. For a comprehensive list of supported networks and their IDs, view real-time tools provided by the service.