FederationService

SEP-2 Federation Protocol service client.

Provides support for resolving human-readable Stellar addresses to account IDs and vice versa. The federation protocol allows users to share addresses like bob*stellar.org instead of raw public keys, making the Stellar network more user-friendly and reducing payment errors.

This service handles:

• Resolving Stellar addresses (name*domain) to account IDs and memo information

• Reverse lookup of account IDs to Stellar addresses

• Transaction ID lookups

• Forward queries for payment routing

• Discovering federation servers from stellar.toml files

Typical workflow:

1. Create service instance via fromDomain or static resolveStellarAddress

2. Resolve addresses to get account IDs and required memos

3. Use resolved information to build and send payments

Example - Resolve a Stellar address:

val address = "bob*stellar.org"
val response = FederationService.resolveStellarAddress(address)

println("Account ID: ${response.accountId}")
if (response.memoType != null && response.memo != null) {
    println("Memo required: ${response.memoType} = ${response.memo}")
}

// Build payment with resolved information
val payment = PaymentOperation(
    destination = response.accountId,
    asset = AssetTypeNative(),
    amount = "10"
)

Example - Reverse lookup:

val service = FederationService.fromDomain("stellar.org")
val response = service.resolveAccountId("GCIBUCGPOHWMMMFPFTDWBSVHQRT4DIBJ7AD6BZJYDITBK2LCVBYW7HUQ")

println("Stellar address: ${response.stellarAddress}")

Example - Forward payment:

val service = FederationService.fromDomain("stellar.org")
val response = service.resolveForward(
    mapOf(
        "forward_type" to "bank_account",
        "swift" to "BOPBPHMM",
        "acct" to "2382376"
    )
)

// Use response.accountId for payment destination

See also:

• fromDomain for automatic configuration from stellar.toml

• resolveStellarAddress for one-step address resolution

• parseAddress for validating address format

• FederationResponse for response details

• SEP-0002 Specification