Golang SDK How To Retrieve More Than 10 Claimable Balance Results

Jul 17, 2025 by ADMIN 66 views

Golang SDK: Retrieving More Than 10 Results for Claimable Balances

Introduction to the Golang SDK and Claimable Balances

The Stellar network is a powerful platform for building decentralized financial applications, and the Golang SDK provides developers with a robust set of tools to interact with the Stellar blockchain. One of the key features of Stellar is the concept of claimable balances, which allow users to create balances that can only be claimed by specific accounts under certain conditions. This functionality opens up a wide range of possibilities for applications such as escrow services, vesting agreements, and conditional payments.

When working with claimable balances using the Golang SDK, developers often need to retrieve a list of these balances from the Stellar network. The SDK's horizonclient package provides methods for querying the Horizon API, which serves as an interface to the Stellar network. However, by default, the Horizon API limits the number of results returned in a single request to 10. This limitation can be problematic when dealing with a large number of claimable balances, as it requires developers to make multiple requests and paginate through the results. In this article, we will explore how to increase the result limit when querying claimable balances using the Golang SDK, enabling you to efficiently retrieve larger datasets.

To effectively manage and utilize claimable balances within your Stellar-based applications, it's crucial to understand how to retrieve data beyond the default limitations. This article will guide you through the process of configuring your horizonclient to fetch more than 10 results, ensuring you can handle a substantial number of claimable balances without the constraints of the default pagination settings. We will delve into the specifics of modifying the request parameters to achieve this, providing practical examples and clear explanations to empower you with the knowledge to optimize your data retrieval process.

Understanding the Default Limit and Pagination

The Stellar Horizon API, which the Golang SDK interacts with, employs pagination as a mechanism to manage large datasets. Pagination is a common technique in web APIs where results are divided into smaller, more manageable chunks or pages. This approach prevents the server from being overwhelmed by requests for massive amounts of data and ensures a smoother experience for the client. By default, Horizon limits the response size to 10 records per page for most endpoints, including the claimable balances endpoint. This default limit is in place to maintain the performance and stability of the Horizon server.

The Golang SDK's horizonclient package simplifies interaction with the Horizon API. However, it also adheres to the default pagination limits unless explicitly instructed otherwise. When you use the ClaimableBalances method, for example, it constructs a request to the Horizon API, which, by default, will only return the first 10 claimable balances that match your query criteria. If you have more than 10 claimable balances associated with your account or matching your filters, you will only see a subset of the total available data.

To overcome this limitation, you need to understand how to modify the request parameters to increase the number of results returned per page. The Horizon API provides a limit parameter that allows you to specify the maximum number of records to include in the response. By adjusting this parameter, you can retrieve more than the default 10 results in a single request. However, it's important to note that there is an upper limit to the limit parameter to prevent abuse and ensure server stability. The maximum allowable value for the limit parameter is typically 200, but it's always a good practice to consult the Horizon API documentation for the most up-to-date information. In the following sections, we will demonstrate how to use the limit parameter within the Golang SDK to retrieve more claimable balance records.

Increasing the Limit in the Golang SDK

To increase the number of claimable balances retrieved by the Golang SDK, you need to modify the horizonclient.ClaimableBalanceRequest struct to include the Limit parameter. This parameter allows you to specify the maximum number of records to return in a single response. Here's a step-by-step guide on how to do this:

Import the necessary packages:

First, ensure that you have imported the required packages in your Go file. These typically include github.com/stellar/go/clients/horizonclient for interacting with the Horizon API and any other packages you need for your application logic.
```
import (
    "github.com/stellar/go/clients/horizonclient"
    "fmt"
)
```
Create a ClaimableBalanceRequest:

Next, create an instance of the horizonclient.ClaimableBalanceRequest struct. This struct allows you to specify various filters and parameters for your query, including the Limit.
```
request := horizonclient.ClaimableBalanceRequest{
    Sponsor: "G...", // Replace with the sponsor account address
    // Add other filters as needed
}
```
Set the Limit parameter:

Now, set the Limit field of the ClaimableBalanceRequest struct to the desired number of results. Remember that the maximum allowable value is typically 200. Setting the limit higher than the allowed maximum may result in an error.
```
request.Limit = 100 // Set the limit to 100 results
```
Execute the request:

Finally, use the client.ClaimableBalances method to execute the request and retrieve the claimable balances. The method will return a slice of horizonclient.ClaimableBalance structs, containing the details of the claimable balances that match your query.
```
balances, err := client.ClaimableBalances(request)
if err != nil {
    fmt.Println("Error:", err)
    return
}
```

By following these steps, you can successfully increase the number of claimable balances retrieved by the Golang SDK in a single request. This can significantly improve the efficiency of your application, especially when dealing with a large number of claimable balances. In the following section, we will provide a complete code example demonstrating how to implement this in practice.

Complete Code Example

To illustrate how to increase the result limit for claimable balances using the Golang SDK, let's consider a complete code example. This example demonstrates how to create a horizonclient, configure a ClaimableBalanceRequest with a custom limit, and iterate through the results. This comprehensive example will solidify your understanding and provide a practical foundation for implementing this technique in your own projects.

package main

import (
	"fmt"

	"github.com/stellar/go/clients/horizonclient"
	"github.com/stellar/go/network"
	"github.com/stellar/go/keypair"
)

func main() {
	// Initialize Horizon client
	client := horizonclient.DefaultPublicNetClient

	// Replace with your keypair
	seed := "SBGJS444KEV2CSI376WJF3JQSXQIRR543VHV4DOUC5K7N5TC7VA4753D"
	keypair, err := keypair.Parse(seed)
	if err != nil {
		fmt.Println("Error parsing keypair:", err)
		return
	}

	// Set the recipient address
	recipient := keypair.Address()

	// Configure the ClaimableBalanceRequest with a limit of 100
	request := horizonclient.ClaimableBalanceRequest{
	Claimant: recipient,
	Limit: 100,
	}

	// Retrieve claimable balances
	balances, err := client.ClaimableBalances(request)
	if err != nil {
		fmt.Println("Error retrieving claimable balances:", err)
		return
	}

	// Print the details of each claimable balance
	fmt.Println("Claimable Balances:")
	for _, balance := range balances.Embedded.Records {
		fmt.Printf("  Balance ID: %s\n", balance.ID)
		fmt.Printf("  Amount: %s\n", balance.Amount)
		fmt.Printf("  Asset: %s\n", balance.Asset)
		fmt.Printf("  Sponsor: %s\n", balance.Sponsor)

		fmt.Println("  Claimants:")
		for _, claimant := range balance.Claimants {
			fmt.Printf("    Destination: %s\n", claimant.Destination)
			fmt.Printf("    Predicate: %+v\n", claimant.Predicate)
		}

		fmt.Println("------------------------")
	}
}

This example demonstrates the complete process of setting up a horizonclient, creating a ClaimableBalanceRequest with a Limit of 100, and iterating through the returned claimable balances. By modifying the Limit parameter, you can control the number of results retrieved in a single request, allowing you to efficiently manage large datasets of claimable balances. Remember to replace the placeholder values with your actual keypair and recipient address.

Handling Pagination for Large Datasets

While increasing the limit to 200 can help retrieve more results in a single request, it might not be sufficient when dealing with extremely large datasets. In such cases, you need to implement pagination to retrieve all the claimable balances. Pagination involves making multiple requests, each fetching a subset of the data, and then combining the results. The Horizon API provides links in the response headers that allow you to navigate through the pages of results. The Golang SDK simplifies this process by providing methods to follow these links.

To handle pagination, you can use the Next() method on the ClaimableBalanceRequest object. This method updates the request object to point to the next page of results. Here's how you can implement pagination in your code:

package main

import (
	"fmt"

	"github.com/stellar/go/clients/horizonclient"
)

func main() {
	// Initialize Horizon client
	client := horizonclient.DefaultPublicNetClient

	// Configure the ClaimableBalanceRequest with a limit
	request := horizonclient.ClaimableBalanceRequest{
		Sponsor: "G...", // Replace with the sponsor account address
		Limit:   100,
	}

	var allBalances []horizonclient.ClaimableBalance

	for {
		// Retrieve claimable balances
		balances, err := client.ClaimableBalances(request)
		if err != nil {
			fmt.Println("Error retrieving claimable balances:", err)
			return
		}

		// Append the retrieved balances to the allBalances slice
		allBalances = append(allBalances, balances.Embedded.Records...)

		// Check if there is a next page
		if balances.Links.Next == nil {
			break // No more pages
		}

		// Update the request for the next page
		err = request.Next()
		if err != nil {
			fmt.Println("Error getting next page:", err)
			return
		}
	}

	// Print the total number of claimable balances retrieved
	fmt.Printf("Total Claimable Balances: %d\n", len(allBalances))

	// You can now process the allBalances slice
}

In this example, we use a loop to iterate through all the pages of results. The request.Next() method updates the request object to point to the next page. The loop continues until there are no more pages, indicated by balances.Links.Next being nil. This approach ensures that you retrieve all claimable balances, regardless of the total number.

Best Practices and Considerations

When working with the Golang SDK and retrieving claimable balances, it's essential to follow best practices and consider certain factors to ensure efficient and reliable data retrieval. Here are some key considerations:

Use appropriate limits: While increasing the limit can reduce the number of requests, setting it too high can put a strain on the Horizon server and potentially lead to errors. It's recommended to use a limit that balances the number of requests and the size of each response. A limit of 100 or 200 is generally a good starting point, but you may need to adjust it based on your specific use case and the size of your dataset.
Implement error handling: Network requests can fail due to various reasons, such as network connectivity issues or server errors. It's crucial to implement robust error handling to gracefully handle these situations. Check the error returned by the client.ClaimableBalances method and take appropriate action, such as retrying the request or logging the error.
Consider rate limiting: The Horizon API has rate limits in place to prevent abuse and ensure fair usage. If you make too many requests in a short period, you may be rate-limited. The Golang SDK provides mechanisms to handle rate limiting, such as waiting before retrying requests. Be mindful of these limits and implement appropriate strategies to avoid being rate-limited.
Optimize your queries: When querying claimable balances, use filters to narrow down the results. For example, you can filter by sponsor, claimant, or asset. This can significantly reduce the amount of data retrieved and improve performance. Avoid making broad queries that return a large number of unnecessary results.
Monitor performance: Regularly monitor the performance of your application and identify any bottlenecks in the data retrieval process. Use metrics such as request latency and error rates to track performance and identify areas for optimization. You can use tools like Prometheus and Grafana to monitor your application's performance.

By following these best practices and considerations, you can ensure that your application efficiently and reliably retrieves claimable balances from the Stellar network using the Golang SDK. This will contribute to a smoother user experience and the overall stability of your application.

Conclusion

In this article, we have explored how to increase the result limit when querying claimable balances using the Golang SDK. By default, the Horizon API limits the number of results returned in a single request to 10. However, by modifying the Limit parameter in the horizonclient.ClaimableBalanceRequest struct, you can retrieve more results in a single request. We demonstrated how to set the Limit parameter, provided a complete code example, and discussed how to handle pagination for large datasets.

Increasing the result limit can significantly improve the efficiency of your application, especially when dealing with a large number of claimable balances. By retrieving more results in a single request, you can reduce the number of requests and the overall time required to fetch the data. However, it's important to use appropriate limits and consider the potential impact on the Horizon server. Setting the limit too high can put a strain on the server and potentially lead to errors.

For extremely large datasets, you should implement pagination to retrieve all the claimable balances. The Golang SDK provides methods to navigate through the pages of results, allowing you to retrieve the entire dataset without exceeding the limits. By combining the techniques discussed in this article, you can efficiently and reliably retrieve claimable balances from the Stellar network using the Golang SDK.

Remember to follow best practices and consider the factors discussed in the previous section to ensure optimal performance and reliability. By understanding how to increase the result limit and handle pagination, you can build robust and scalable applications that leverage the power of claimable balances on the Stellar network. This knowledge empowers you to create more efficient and user-friendly applications, enhancing the overall experience for your users and contributing to the growth of the Stellar ecosystem.