Stellar PHP SDK API Documentation

AccountsRequestBuilder extends RequestBuilder
in package

Soneso

StellarSDK

Requests

Builds requests for the accounts endpoint in Horizon

This class provides methods to query accounts on the Stellar network, including fetching individual accounts, querying accounts by various criteria (signer, asset, sponsor, liquidity pool), and streaming account updates in real-time.

Query Methods:

forSigner(): Filter accounts by a specific signer
forAsset(): Filter accounts holding a specific asset
forSponsor(): Filter accounts by sponsor
forLiquidityPool(): Filter accounts participating in a liquidity pool

Note: Filter methods are mutually exclusive - only one filter can be applied per query.

Usage Examples:

// Get a single account $account = $sdk->accounts()->account("GDAT5...");

// Query accounts by signer with pagination $accounts = $sdk->accounts() ->forSigner("GDAT5...") ->limit(50) ->order("desc") ->execute();

// Query accounts holding a specific asset $asset = Asset::createNonNativeAsset("USD", "GBBD..."); $accounts = $sdk->accounts() ->forAsset($asset) ->execute();

// Stream real-time account updates $sdk->accounts()->streamAccount("GDAT5...", function($account) { echo "Balance: " . $account->getBalances()->getNativeBalance()->getBalance(); });

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: Constructs a new AccountsRequestBuilder instance
account() : AccountResponse: Fetches a single account by its public key
accountData() : AccountDataValueResponse: Requests <code>GET /accounts/{account}/data/{key}</code> Returns the value of a single data entry for an account.
buildUrl() : string: Builds the complete request URL with all segments and query parameters
cursor() : AccountsRequestBuilder: Sets the cursor position for pagination
execute() : AccountsPageResponse: Builds the query URL and executes the request
executeRequest() : Response: Executes an HTTP request to Horizon and returns a parsed response object
forAsset() : AccountsRequestBuilder: Filters accounts by a specific asset they hold
forLiquidityPool() : AccountsRequestBuilder: Filters accounts by liquidity pool participation
forSigner() : AccountsRequestBuilder: Filters accounts by a specific signer
forSponsor() : AccountsRequestBuilder: Filters accounts by sponsor
getAndStream() : void: Streams Server-Sent Events from Horizon to a callback function
limit() : AccountsRequestBuilder: Sets the maximum number of accounts to return
order() : AccountsRequestBuilder: Sets the sort order for results
request() : AccountsPageResponse: Requests a specific URL and returns paginated accounts
streamAccount() : mixed: Streams AccountResponse objects for a specific account to $callback
streamAccountData() : void: Streams AccountDataValueResponse objects for a specific account data entry to $callback
setSegments() : RequestBuilder: Sets the URL path segments for this request

HEADERS


    public
        mixed
    HEADERS
    = ["X-Client-Name" => "stellar_php_sdk", "X-Client-Version" => \Soneso\StellarSDK\StellarSDK::VERSION_NR]

$httpClient


        protected
            Client
    $httpClient

$queryParameters


        protected
            array<string|int, mixed>
    $queryParameters

$segments


        protected
            array<string|int, mixed>
    $segments

__construct()

Constructs a new AccountsRequestBuilder instance


    public
                    __construct(Client $httpClient) : mixed

Parameters

$httpClient : Client: The Guzzle HTTP client for making requests

account()

Fetches a single account by its public key


    public
                    account(string $accountId) : AccountResponse

Requests GET /accounts/{account}

Parameters

$accountId : string: Public key of the account to fetch (G-address)

Return values

AccountResponse —

The account details including balances, signers, and data

accountData()

Requests <code>GET /accounts/{account}/data/{key}</code> Returns the value of a single data entry for an account.


    public
                    accountData(string $accountId, string $key) : AccountDataValueResponse

Parameters

$accountId : string: Public key of the account
$key : string: The data entry key to fetch

Return values

AccountDataValueResponse

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

cursor()

Sets the cursor position for pagination


    public
                    cursor(string $cursor) : AccountsRequestBuilder

A cursor is an opaque value that points to a specific location in a result set. Use this to navigate to a specific page when paginating through results.

Parameters

$cursor : string: The paging token from a previous response

Return values

AccountsRequestBuilder —

This instance for method chaining

execute()

Builds the query URL and executes the request


    public
                    execute() : AccountsPageResponse

Combines all query parameters and filters to build the final URL, then executes the request and returns paginated account results.

Return values

AccountsPageResponse —

Paginated list of accounts matching the query

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")

Return values

Response —

The parsed response object of the specified type

forAsset()

Filters accounts by a specific asset they hold


    public
                    forAsset(AssetTypeCreditAlphaNum $asset) : AccountsRequestBuilder

Returns accounts that have a trustline for the specified asset. This filter is mutually exclusive with forSigner, forLiquidityPool, and forSponsor.

Parameters

$asset : AssetTypeCreditAlphaNum: The asset to filter by (cannot be native XLM)

Return values

AccountsRequestBuilder —

This instance for method chaining

forLiquidityPool()

Filters accounts by liquidity pool participation


    public
                    forLiquidityPool(string $liquidityPoolId) : AccountsRequestBuilder

Returns accounts that have trustlines to the specified liquidity pool. This filter is mutually exclusive with forSigner, forAsset, and forSponsor.

Parameters

$liquidityPoolId : string: The liquidity pool ID (L-address or hex format)

Return values

AccountsRequestBuilder —

This instance for method chaining

forSigner()

Filters accounts by a specific signer


    public
                    forSigner(string $signer) : AccountsRequestBuilder

Returns accounts where the specified address is one of the signers. This filter is mutually exclusive with forAsset, forLiquidityPool, and forSponsor.

Parameters

$signer : string: Public key of the signer to filter by (G-address)

Return values

AccountsRequestBuilder —

This instance for method chaining

forSponsor()

Filters accounts by sponsor


    public
                    forSponsor(string $sponsor) : AccountsRequestBuilder

Returns accounts where the base reserve is being sponsored by the specified account. This filter is mutually exclusive with forSigner, forAsset, and forLiquidityPool.

Parameters

$sponsor : string: Public key of the sponsor account (G-address)

Return values

AccountsRequestBuilder —

This instance for method chaining

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)

Return values

void —

This method runs indefinitely until interrupted

limit()

Sets the maximum number of accounts to return


    public
                    limit(int $number) : AccountsRequestBuilder

Defines the maximum number of records in the response. The default limit varies by endpoint. Maximum allowed is typically 200.

Parameters

$number : int: Maximum number of accounts to return (1-200)

Return values

AccountsRequestBuilder —

This instance for method chaining

order()

Sets the sort order for results


    public
                    order([string $direction = "asc" ]) : AccountsRequestBuilder

Determines whether results are sorted in ascending or descending order. For accounts, ordering is typically by creation time or ID.

Parameters

$direction : string = "asc": Sort direction: "asc" for ascending, "desc" for descending

Return values

AccountsRequestBuilder —

This instance for method chaining

request()

Requests a specific URL and returns paginated accounts


    public
                    request(string $url) : AccountsPageResponse

This method is typically used internally for pagination. Use execute() instead for normal queries, or follow pagination links from response objects.

Parameters

$url : string: The complete URL to request

Return values

AccountsPageResponse —

Paginated list of accounts

streamAccount()

Streams AccountResponse objects for a specific account to $callback


    public
                    streamAccount(string $accountId[, callable|null $callback = null ]) : mixed

This method provides real-time updates by streaming the /accounts/{account_id} endpoint directly. Horizon uses polling-based streaming: it polls the account endpoint every few seconds and sends SSE events when the account state changes.

The callback receives AccountResponse objects whenever the account is updated (e.g., after transactions, balance changes, data entries, etc.).

$callback should have arguments: AccountResponse

For example:

$sdk = StellarSDK::getTestNetInstance(); $accountId = "GDQJUTQYK2MQX2VGDR2FYWLIYAQIEGXTQVTFEMGH2BEWFG4BRUY4CKI7"; $sdk->accounts()->streamAccount($accountId, function(AccountResponse $account) { printf('Account %s updated - Sequence: %s, Balance: %s XLM' . PHP_EOL, $account->getAccountId(), $account->getSequenceNumber(), $account->getBalances()->getNativeBalance()->getBalance() ); });

Parameters

$accountId : string: Public key of the account to stream
$callback : callable|null = null: Callback function to receive AccountResponse objects

streamAccountData()

Streams AccountDataValueResponse objects for a specific account data entry to $callback


    public
                    streamAccountData(string $accountId, string $key[, callable|null $callback = null ]) : void

This method provides real-time updates by streaming the /accounts/{account_id}/data/{key} endpoint. Horizon uses polling-based streaming: it polls the endpoint every few seconds and sends SSE events when the data value changes.

The callback receives AccountDataValueResponse objects whenever the data entry value is updated (e.g., after a MANAGE_DATA operation).

$callback should have arguments: AccountDataValueResponse

For example:

$sdk = StellarSDK::getTestNetInstance(); $accountId = "GDQJUTQYK2MQX2VGDR2FYWLIYAQIEGXTQVTFEMGH2BEWFG4BRUY4CKI7"; $key = "config"; $sdk->accounts()->streamAccountData($accountId, $key, function(AccountDataValueResponse $data) { printf('Data value updated: %s' . PHP_EOL, $data->getDecodedValue()); });

Parameters

$accountId : string: Public key of the account
$key : string: The data entry key to stream
$callback : callable|null = null: Callback function to receive AccountDataValueResponse objects

setSegments()

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

Return values

RequestBuilder —

This instance for method chaining

AccountsRequestBuilder extends RequestBuilder in package Soneso StellarSDK Requests

Tags

Table of Contents

Constants

Properties

Methods

Constants

HEADERS

Properties

$httpClient

$queryParameters

$segments

Methods

__construct()

Parameters

account()

Parameters

Tags

Return values

accountData()

Parameters

Tags

Return values

buildUrl()

Return values

cursor()

Parameters

Tags

Return values

execute()

Tags

Return values

executeRequest()

Parameters

Tags

Return values

forAsset()

Parameters

Tags

Return values

forLiquidityPool()

Parameters

Tags

Return values

forSigner()

Parameters

Tags

Return values

forSponsor()

Parameters

Tags

Return values

getAndStream()

Parameters

Tags

Return values

limit()

Parameters

Return values

order()

Parameters

Return values

request()

Parameters

Tags

Return values

streamAccount()

Parameters

Tags

streamAccountData()

Parameters

Tags

setSegments()

Parameters

Tags

Return values

AccountsRequestBuilder extends RequestBuilder
in package

Soneso

StellarSDK

Requests