Struct BreezSdk 

pub struct BreezSdk { /* private fields */ }

BreezSDK is a wrapper around SparkSDK that provides a more structured API with request/response objects and comprehensive error handling.

Implementations

impl BreezSdk

pub async fn add_event_listener( &self, listener: Box<dyn EventListener>, ) -> String

Registers a listener to receive SDK events

The SDK holds the listener until it is removed with remove_event_listener or until disconnect unregisters all listeners. A held listener that references the SDK instance keeps that instance alive.

Arguments

• listener - An implementation of the EventListener trait

Returns

A unique identifier for the listener, which can be used to remove it later

pub async fn remove_event_listener(&self, id: &str) -> bool

Removes a previously registered event listener

Arguments

• id - The listener ID returned from add_event_listener

Returns

true if the listener was found and removed, false otherwise

pub async fn disconnect(&self) -> Result<(), SdkError>

Stops the SDK’s background tasks

This method stops the background tasks started by the start() method. It should be called before your application terminates to ensure proper cleanup.

It also unregisters all event listeners, so listeners that reference the SDK no longer keep it alive after this call.

Returns

Result containing either success or an SdkError if the background task couldn’t be stopped

pub async fn parse(&self, input: &str) -> Result<InputType, SdkError>

pub async fn get_cross_chain_routes( &self, filter: &CrossChainRouteFilter, ) -> Result<Vec<CrossChainRoutePair>, SdkError>

Returns the available cross-chain routes.

Use CrossChainRouteFilter::Send to get routes for sending from Spark (filtered by the parsed recipient address), or CrossChainRouteFilter::Receive to get routes for receiving into Spark (optionally filtered by a source contract address).

pub async fn get_info( &self, request: GetInfoRequest, ) -> Result<GetInfoResponse, SdkError>

Returns the balance of the wallet in satoshis

pub async fn list_fiat_currencies( &self, ) -> Result<ListFiatCurrenciesResponse, SdkError>

List fiat currencies for which there is a known exchange rate, sorted by the canonical name of the currency.

pub async fn list_fiat_rates(&self) -> Result<ListFiatRatesResponse, SdkError>

List the latest rates of fiat currencies, sorted by name.

pub async fn recommended_fees(&self) -> Result<RecommendedFees, SdkError>

Get the recommended BTC fees based on the configured chain service.

pub async fn get_tokens_metadata( &self, request: GetTokensMetadataRequest, ) -> Result<GetTokensMetadataResponse, SdkError>

Returns the metadata for the given token identifiers.

Results are not guaranteed to be in the same order as the input token identifiers.

If the metadata is not found locally in cache, it will be queried from the Spark network and then cached.

pub async fn sign_message( &self, request: SignMessageRequest, ) -> Result<SignMessageResponse, SdkError>

Signs a message with the wallet’s identity key. The message is SHA256 hashed before signing. The returned signature will be hex encoded in DER format by default, or compact format if specified.

pub async fn check_message( &self, request: CheckMessageRequest, ) -> Result<CheckMessageResponse, SdkError>

Verifies a message signature against the provided public key. The message is SHA256 hashed before verification. The signature can be hex encoded in either DER or compact format.

pub async fn get_user_settings(&self) -> Result<UserSettings, SdkError>

Returns the user settings for the wallet.

Some settings are fetched from the Spark network so network requests are performed.

pub async fn update_user_settings( &self, request: UpdateUserSettingsRequest, ) -> Result<(), SdkError>

Updates the user settings for the wallet.

Some settings are updated on the Spark network so network requests may be performed.

pub fn get_token_issuer(&self) -> TokenIssuer

Returns an instance of the TokenIssuer for managing token issuance.

pub async fn optimize_leaves( &self, request: OptimizeLeavesRequest, ) -> Result<OptimizeLeavesResponse, SdkError>

Manually drives leaf optimization, blocking until the requested work is done.

With OptimizationMode::Full (the default) the call runs the entire optimization in a single invocation. With OptimizationMode::SingleRound it executes one round and returns — the caller drives the loop by inspecting the OptimizeLeavesResponse::outcome and calling again until InProgress no longer appears.

Returns an error if another optimization run (auto or manual) is already in flight (SdkError::OptimizationAlreadyRunning), or if the SDK preempted this run to free leaves for a payment (SdkError::OptimizationCancelled).

Manual runs do not emit events; events ([SdkEvent::AutoOptimization]) are reserved for the background auto-optimizer.

pub async fn register_webhook( &self, request: RegisterWebhookRequest, ) -> Result<RegisterWebhookResponse, SdkError>

Registers a webhook to receive notifications for wallet events.

When registered events occur (e.g., a Lightning payment is received), the Spark service provider will send an HTTP POST to the specified URL with a payload signed using HMAC-SHA256 with the provided secret.

Arguments

• request - The webhook registration details including URL, secret, and event types

Returns

A response containing the unique identifier of the registered webhook

pub async fn unregister_webhook( &self, request: UnregisterWebhookRequest, ) -> Result<(), SdkError>

Unregisters a previously registered webhook.

After unregistering, the Spark service provider will no longer send notifications to the webhook URL.

Arguments

• request - The unregister request containing the webhook ID

pub async fn list_webhooks(&self) -> Result<Vec<Webhook>, SdkError>

Lists all webhooks currently registered for this wallet.

Returns

A list of registered webhooks with their IDs, URLs, and subscribed event types

pub async fn buy_bitcoin( &self, request: BuyBitcoinRequest, ) -> Result<BuyBitcoinResponse, SdkError>

Initiates a Bitcoin purchase flow via an external provider.

Returns a URL the user should open to complete the purchase. The request variant determines the provider and its parameters:

• BuyBitcoinRequest::Moonpay: Fiat-to-Bitcoin via on-chain deposit.
• BuyBitcoinRequest::CashApp: Lightning invoice + cash.app deep link (mainnet only).

impl BreezSdk

pub async fn add_contact( &self, request: AddContactRequest, ) -> Result<Contact, SdkError>

Adds a new contact.

Arguments

• request - The request containing the contact details

Returns

The created contact or an error

pub async fn update_contact( &self, request: UpdateContactRequest, ) -> Result<Contact, SdkError>

Updates an existing contact.

Arguments

• request - The request containing the updated contact details

Returns

The updated contact or an error

pub async fn delete_contact(&self, id: String) -> Result<(), SdkError>

Deletes a contact by its ID.

Arguments

• id - The ID of the contact to delete

Returns

Success or an error

pub async fn list_contacts( &self, request: ListContactsRequest, ) -> Result<Vec<Contact>, SdkError>

Lists contacts with optional pagination.

Arguments

• request - The request containing optional pagination parameters

Returns

A list of contacts or an error

impl BreezSdk

pub async fn claim_deposit( &self, request: ClaimDepositRequest, ) -> Result<ClaimDepositResponse, SdkError>

pub async fn refund_deposit( &self, request: RefundDepositRequest, ) -> Result<RefundDepositResponse, SdkError>

pub async fn list_unclaimed_deposits( &self, request: ListUnclaimedDepositsRequest, ) -> Result<ListUnclaimedDepositsResponse, SdkError>

impl BreezSdk

pub async fn check_lightning_address_available( &self, req: CheckLightningAddressRequest, ) -> Result<bool, SdkError>

pub async fn get_lightning_address( &self, ) -> Result<Option<LightningAddressInfo>, SdkError>

pub async fn register_lightning_address( &self, request: RegisterLightningAddressRequest, ) -> Result<LightningAddressInfo, SdkError>

pub async fn authorize_lightning_address_transfer( &self, request: AuthorizeTransferRequest, ) -> Result<TransferAuthorization, SdkError>

Authorize transferring the current owner’s registered lightning address username to request.transferee_pubkey. Returns a TransferAuthorization to hand to the new owner, who claims it via BreezSdk::claim_lightning_address_transfer. Errors if the current owner has no lightning address registered.

pub async fn claim_lightning_address_transfer( &self, request: ClaimTransferRequest, ) -> Result<LightningAddressInfo, SdkError>

Claim a lightning address username handed over by its current owner, using the TransferAuthorization from BreezSdk::authorize_lightning_address_transfer. Completes the takeover and returns the newly-owned address.

pub async fn delete_lightning_address(&self) -> Result<(), SdkError>

impl BreezSdk

pub async fn prepare_lnurl_pay( &self, request: PrepareLnurlPayRequest, ) -> Result<PrepareLnurlPayResponse, SdkError>

pub async fn lnurl_pay( &self, request: LnurlPayRequest, ) -> Result<LnurlPayResponse, SdkError>

pub async fn build_unsigned_lnurl_pay_package( &self, request: BuildUnsignedLnurlPayPackageRequest, ) -> Result<UnsignedTransferPackage, SdkError>

pub async fn publish_signed_lnurl_pay_package( &self, request: PublishSignedLnurlPayPackageRequest, ) -> Result<PublishSignedLnurlPayResponse, SdkError>

pub async fn lnurl_withdraw( &self, request: LnurlWithdrawRequest, ) -> Result<LnurlWithdrawResponse, SdkError>

Performs an LNURL withdraw operation for the amount of satoshis to withdraw and the LNURL withdraw request details. The LNURL withdraw request details can be obtained from calling BreezSdk::parse.

The method generates a Lightning invoice for the withdraw amount, stores the LNURL withdraw metadata, and performs the LNURL withdraw using the generated invoice.

If the completion_timeout_secs parameter is provided and greater than 0, the method will wait for the payment to be completed within that period. If the withdraw is completed within the timeout, the payment field in the response will be set with the payment details. If the completion_timeout_secs parameter is not provided or set to 0, the method will not wait for the payment to be completed. If the withdraw is not completed within the timeout, the payment field will be empty.

Arguments

• request - The LNURL withdraw request

Returns

Result containing either:

• LnurlWithdrawResponse - The payment details if the withdraw request was successful
• SdkError - If there was an error during the withdraw process

pub async fn lnurl_auth( &self, request_data: LnurlAuthRequestDetails, ) -> Result<LnurlCallbackStatus, SdkError>

Performs LNURL-auth with the service.

This method implements the LNURL-auth protocol as specified in LUD-04 and LUD-05. It derives a domain-specific linking key, signs the challenge, and sends the authentication request to the service.

impl BreezSdk

pub async fn receive_payment( &self, request: ReceivePaymentRequest, ) -> Result<ReceivePaymentResponse, SdkError>

pub async fn claim_htlc_payment( &self, request: ClaimHtlcPaymentRequest, ) -> Result<ClaimHtlcPaymentResponse, SdkError>

pub async fn prepare_send_payment( &self, request: PrepareSendPaymentRequest, ) -> Result<PrepareSendPaymentResponse, SdkError>

pub async fn send_payment( &self, request: SendPaymentRequest, ) -> Result<SendPaymentResponse, SdkError>

pub async fn build_unsigned_transfer_package( &self, request: BuildUnsignedTransferPackageRequest, ) -> Result<UnsignedTransferPackage, SdkError>

pub async fn publish_signed_transfer_package( &self, request: PublishSignedTransferPackageRequest, ) -> Result<PublishSignedTransferPackageResponse, SdkError>

pub async fn fetch_conversion_limits( &self, request: FetchConversionLimitsRequest, ) -> Result<FetchConversionLimitsResponse, SdkError>

pub async fn refund_pending_conversions(&self) -> Result<(), SdkError>

Runs one pass of the pending-conversion refunder.

Iterates over payments whose conversions failed and have a refund pending, then attempts to refund each one. This is the same logic the SDK runs internally on a periodic schedule when background_tasks_enabled is true. When background tasks are disabled the periodic refunder does not run, and this method is the explicit entry point for driving the pass; when background tasks are enabled, it can be called to force an immediate refund pass.

pub async fn list_payments( &self, request: ListPaymentsRequest, ) -> Result<ListPaymentsResponse, SdkError>

Lists payments from the storage with pagination

This method provides direct access to the payment history stored in the database. It returns payments in reverse chronological order (newest first).

Arguments

• request - Contains pagination parameters (offset and limit)

Returns

• Ok(ListPaymentsResponse) - Contains the list of payments if successful
• Err(SdkError) - If there was an error accessing the storage

pub async fn get_payment( &self, request: GetPaymentRequest, ) -> Result<GetPaymentResponse, SdkError>

impl BreezSdk

pub async fn sync_wallet( &self, request: SyncWalletRequest, ) -> Result<SyncWalletResponse, SdkError>

Synchronizes the wallet with the Spark network

Trait Implementations

impl Clone for BreezSdk

fn clone(&self) -> BreezSdk

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.