ClaimableBalancesRequestBuilder
extends RequestBuilder
in package
Builds requests for the claimable balances endpoint in Horizon
This class provides methods to query claimable balances on the Stellar network. Claimable balances represent amounts of an asset that can be claimed by specific accounts under predefined conditions. They are commonly used for payment escrow and conditional transfers.
Query Methods:
- claimableBalance(): Fetch a single claimable balance by ID
- forSponsor(): Filter by sponsor account
- forAsset(): Filter by the asset held in the balance
- forClaimant(): Filter by accounts that can claim the balance
Claimable balances support both BalanceID (starts with "B") and hex formats.
Usage Examples:
// Get a specific claimable balance $balance = $sdk->claimableBalances() ->claimableBalance("00000000...");
// Get claimable balances for a specific claimant $balances = $sdk->claimableBalances() ->forClaimant("GDAT5...") ->execute();
// Get claimable balances by sponsor and asset $asset = Asset::createNonNativeAsset("USD", "GBBD..."); $balances = $sdk->claimableBalances() ->forSponsor("GDAT5...") ->forAsset($asset) ->execute();
Tags
Table of Contents
Constants
- HEADERS = ["X-Client-Name" => "stellar_php_sdk", "X-Client-Version" => \Soneso\StellarSDK\StellarSDK::VERSION_NR]
Properties
- $httpClient : Client
- $queryParameters : array<string|int, mixed>
- $segments : array<string|int, mixed>
Methods
- __construct() : mixed
- Constructor
- buildUrl() : string
- Builds the complete request URL with all segments and query parameters
- claimableBalance() : ClaimableBalanceResponse
- The claimable balance details endpoint provides information on a claimable balance.
- cursor() : ClaimableBalancesRequestBuilder
- Sets <code>cursor</code> parameter on the request.
- execute() : Response
- Build and execute request.
- executeRequest() : Response
- Executes an HTTP request to Horizon and returns a parsed response object
- forAsset() : ClaimableBalancesRequestBuilder
- Returns all claimable balances which hold a given asset.
- forClaimant() : ClaimableBalancesRequestBuilder
- Returns all claimable balances which can be claimed by a given account id.
- forSponsor() : ClaimableBalancesRequestBuilder
- Returns all claimable balances sponsored by a given account.
- getAndStream() : void
- Streams Server-Sent Events from Horizon to a callback function
- limit() : ClaimableBalancesRequestBuilder
- Sets <code>limit</code> parameter on the request.
- order() : ClaimableBalancesRequestBuilder
- Sets <code>order</code> parameter on the request.
- request() : ClaimableBalancesPageResponse
- Requests specific <code>url</code> and returns {@link ClaimableBalancesPageResponse}.
- setSegments() : RequestBuilder
- Sets the URL path segments for this request
Constants
HEADERS
public
mixed
HEADERS
= ["X-Client-Name" => "stellar_php_sdk", "X-Client-Version" => \Soneso\StellarSDK\StellarSDK::VERSION_NR]
Properties
$httpClient
protected
Client
$httpClient
$queryParameters
protected
array<string|int, mixed>
$queryParameters
$segments
protected
array<string|int, mixed>
$segments
Methods
__construct()
Constructor
public
__construct(Client $httpClient) : mixed
Parameters
- $httpClient : Client
-
The HTTP client used for making requests to Horizon
buildUrl()
Builds the complete request URL with all segments and query parameters
public
buildUrl() : string
Combines the URL path segments with query parameters to create the final request URL string that will be sent to Horizon.
Return values
string —The constructed URL with query parameters
claimableBalance()
The claimable balance details endpoint provides information on a claimable balance.
public
claimableBalance(string $claimableBalanceId) : ClaimableBalanceResponse
Parameters
- $claimableBalanceId : string
-
Specifies which claimable balance to load.
Tags
Return values
ClaimableBalanceResponse —The claimable balance details.
cursor()
Sets <code>cursor</code> parameter on the request.
public
cursor(string $cursor) : ClaimableBalancesRequestBuilder
A cursor is a value that points to a specific location in a collection of resources. The cursor attribute itself is an opaque value meaning that users should not try to parse it.
Parameters
- $cursor : string
Tags
Return values
ClaimableBalancesRequestBuilderexecute()
Build and execute request.
public
execute() : Response
@throws HorizonRequestException
Return values
Response —The parsed response object
executeRequest()
Executes an HTTP request to Horizon and returns a parsed response object
public
executeRequest(string $url, string $requestType[, string|null $requestMethod = "GET" ]) : Response
This method sends the HTTP request to the Horizon server, handles errors, and parses the JSON response into the appropriate response type.
Parameters
- $url : string
-
The complete request URL to fetch
- $requestType : string
-
The expected response type for parsing
- $requestMethod : string|null = "GET"
-
The HTTP method to use (default: "GET")
Tags
Return values
Response —The parsed response object of the specified type
forAsset()
Returns all claimable balances which hold a given asset.
public
forAsset(Asset $asset) : ClaimableBalancesRequestBuilder
Parameters
- $asset : Asset
-
The asset held by the claimable balance.
Return values
ClaimableBalancesRequestBuilder —current instance.
forClaimant()
Returns all claimable balances which can be claimed by a given account id.
public
forClaimant(string $claimant) : ClaimableBalancesRequestBuilder
Parameters
- $claimant : string
-
Account ID of the address which can claim the claimable balance.
Return values
ClaimableBalancesRequestBuilder —current instance.
forSponsor()
Returns all claimable balances sponsored by a given account.
public
forSponsor(string $sponsor) : ClaimableBalancesRequestBuilder
Parameters
- $sponsor : string
-
Account ID of the sponsor.
Return values
ClaimableBalancesRequestBuilder —current instance
getAndStream()
Streams Server-Sent Events from Horizon to a callback function
public
getAndStream(string $relativeUrl, callable $callback[, bool $retryOnServerException = true ]) : void
This method establishes a persistent connection to Horizon's streaming endpoints using Server-Sent Events (SSE). It processes each event and passes the parsed data to the provided callback function. The stream automatically reconnects on server exceptions if retryOnServerException is true.
Horizon streaming uses SSE to push real-time updates. The stream sends:
- "hello" message on connection
- "byebye" message on disconnection
- JSON data objects for actual events
Parameters
- $relativeUrl : string
-
The relative URL to stream from
- $callback : callable
-
Function to receive parsed event data
- $retryOnServerException : bool = true
-
If true, automatically retry on server errors (default: true)
Tags
Return values
void —This method runs indefinitely until interrupted
limit()
Sets <code>limit</code> parameter on the request.
public
limit(int $number) : ClaimableBalancesRequestBuilder
It defines maximum number of records to return. For range and default values check documentation of the endpoint requested.
Parameters
- $number : int
-
Maximum number of records to return
Return values
ClaimableBalancesRequestBuilderorder()
Sets <code>order</code> parameter on the request.
public
order([string $direction = "asc" ]) : ClaimableBalancesRequestBuilder
Parameters
- $direction : string = "asc"
-
"asc" or "desc"
Return values
ClaimableBalancesRequestBuilderrequest()
Requests specific <code>url</code> and returns {@link ClaimableBalancesPageResponse}.
public
request(string $url) : ClaimableBalancesPageResponse
Parameters
- $url : string
Tags
Return values
ClaimableBalancesPageResponsesetSegments()
Sets the URL path segments for this request
protected
setSegments(string ...$segments) : RequestBuilder
This method constructs the URL path by combining multiple segments. Can only be called once per request builder instance.
Parameters
- $segments : string
-
Variable number of URL path segments
Tags
Return values
RequestBuilder —This instance for method chaining