stellar-sdk/com.soneso.stellar.sdk.sep.sep24/Sep24Service

Sep24Service

class Sep24Service(serviceAddress: String, httpClient: HttpClient? = null, httpRequestHeaders: Map<String, String>? = null)

SEP-24 Hosted Deposit and Withdrawal service client.

Provides interactive deposit and withdrawal flows with Stellar anchors. SEP-24 enables wallets to offer on/off ramp functionality through a standardized protocol where users complete the deposit or withdrawal process through an anchor-hosted web interface.

This service handles all communication with SEP-24 compliant anchors, including:

Discovering anchor capabilities and supported assets via /info
Initiating interactive deposit flows via /transactions/deposit/interactive
Initiating interactive withdrawal flows via /transactions/withdraw/interactive
Querying transaction status and history
Polling for transaction completion

Authentication:

The /info endpoint does not require authentication
All other endpoints require a valid SEP-10 JWT token

Typical workflow:

Create service instance via fromDomain or constructor
Call info to discover supported assets and limits
Authenticate via SEP-10 WebAuth to obtain a JWT token
Call deposit or withdraw to initiate an interactive flow
Display the returned URL in a webview for user interaction
Poll transaction or use pollTransaction to monitor completion

Example - Complete deposit flow:

// 1. Initialize from domain
val sep24 = Sep24Service.fromDomain("anchor.example.com")

// 2. Check supported assets
val info = sep24.info()
val usdcEnabled = info.depositAssets?.get("USDC")?.enabled == true

// 3. Authenticate via SEP-10
val webAuth = WebAuth.fromDomain("anchor.example.com", network)
val jwt = webAuth.jwtToken(accountId, listOf(keyPair)).token

// 4. Initiate deposit
val response = sep24.deposit(Sep24DepositRequest(
    assetCode = "USDC",
    jwt = jwt,
    account = keyPair.getAccountId(),
    amount = "100"
))

// 5. Display interactive URL in webview
displayWebView(response.url)

// 6. Poll for completion
val tx = sep24.pollTransaction(
    Sep24TransactionRequest(jwt = jwt, id = response.id),
    onStatusChange = { println("Status: ${it.status}") }
)

when (tx.getStatusEnum()) {
    Sep24TransactionStatus.COMPLETED -> println("Success! Received ${tx.amountOut}")
    Sep24TransactionStatus.ERROR -> println("Failed: ${tx.message}")
    else -> println("Final status: ${tx.status}")
}

Example - Error handling:

try {
    val response = sep24.deposit(request)
} catch (e: Sep24AuthenticationRequiredException) {
    // JWT expired, re-authenticate via SEP-10
} catch (e: Sep24InvalidRequestException) {
    // Invalid parameters, check request
} catch (e: Sep24ServerErrorException) {
    // Anchor server error, retry with backoff
}

Example - SEP-38 quote integration:

// Get firm quote first
val quoteService = QuoteService.fromDomain("anchor.example.com")
val quote = quoteService.postQuote(
    Sep38QuoteRequest(
        context = "sep24",
        sellAsset = "iso4217:USD",
        buyAsset = "stellar:USDC:GA...",
        sellAmount = "100"
    ),
    jwt
)

// Use quote in deposit
val response = sep24.deposit(Sep24DepositRequest(
    assetCode = "USDC",
    jwt = jwt,
    quoteId = quote.id,
    amount = quote.sellAmount
))