Wallet & Trustlines

The wallet service reads account balances and manages trustlines through Stellar's Horizon API. On Stellar, an account must hold a trustline for a non-native asset before it can receive or hold that asset — so the typical onboarding sequence is: check the balance, add a trustline if missing, then supply into the protocol.

Accessed via client.wallet.

Horizon, not Soroban

Trustline changes are classic Stellar operations submitted through Horizon, a different signing and submission path from the Soroban contract calls used elsewhere in the SDK. addTrustline handles this for you.

Balances

getBalances

Fetch all balance lines for an account.

const balances = await client.wallet.getBalances('GABC...')

Parameter	Type	Description
publicKey	string	Optional; falls back to the client's connected public key

Returns an array of Horizon balance lines, or throws if no address is available.

---

getAssetBalance

Fetch the balance for one asset. Pass 'XLM' for the native asset; otherwise provide the asset code and, optionally, the issuer to disambiguate.

const xlm = await client.wallet.getAssetBalance('GABC...', 'XLM')
const usdc = await client.wallet.getAssetBalance('GABC...', 'USDC', usdcIssuer)

Parameter	Type	Description
publicKey	string	Account to read
assetCode	string	Asset code, or 'XLM' for native
assetIssuer	string	Optional issuer to disambiguate the asset

Returns the balance as a string, or null if the account holds no such asset.

Trustlines

addTrustline

Add a trustline for an asset, then sign and submit it through Horizon.

await client.wallet.addTrustline('GABC...', 'USDC', usdcIssuer, kit)

Parameter	Type	Description
publicKey	string	Account adding the trustline
assetCode	string	Asset code to trust
assetIssuer	string	Issuer of the asset
kit	SigningKit	Wallet used to sign
options	{ debug?: boolean }	Optional; debug defaults to true

Build-only variant: buildAddTrustlineTx(publicKey, assetCode, assetIssuer) returns the unsigned transaction.

Connection helpers

hasWallet() returns whether a public key is currently set, and setPublicKey(publicKey) updates it after a wallet connects.

if (!client.wallet.hasWallet()) {
  client.wallet.setPublicKey(connectedAddress)
}