Kotlin API reference

class OMSWallet {
    val wallet: WalletClient

    val indexer: IndexerClient

    /**
     * Creates an Android-backed client with separate session metadata storage
     * and Android Keystore request signing.
     */
    constructor(
        context: Context,
        publishableKey: String,
        okHttpClient: OkHttpClient = OkHttpClient(),
    )
}

sealed interface OMSWalletSessionAuth {
    val email: String?
}

data class OMSWalletEmailSessionAuth(
    override val email: String,
) : OMSWalletSessionAuth

enum class OMSWalletOidcSessionAuthFlow {
    Redirect,
    IdToken,
}

data class OMSWalletOidcSessionAuth(
    val flow: OMSWalletOidcSessionAuthFlow,
    val issuer: String,
    val provider: String?,
    val providerLabel: String?,
    override val email: String?,
) : OMSWalletSessionAuth

data class OMSWalletSessionState(
    /**
     * Address of the selected wallet in a completed session, or null when the
     * SDK is signed out.
     */
    val walletAddress: String?,
    /**
     * ISO-8601 expiration time for the current completed wallet session, or null
     * when the SDK is signed out.
     */
    val expiresAt: String? = null,
    val auth: OMSWalletSessionAuth? = null,
)

data class OMSWalletSessionExpiredEvent(
    val session: OMSWalletSessionState,
    val expiredAt: String,
)

enum class WalletType(
    val wireValue: String,
) {
    Ethereum("ethereum"),
    UNKNOWN_DEFAULT("UNKNOWN_DEFAULT"),
}

data class Wallet(
    val id: String,
    val type: WalletType,
    val address: String,
    val reference: String? = null,
)

data class Page(
    val limit: UInt? = null,
    val cursor: String? = null,
)

data class CredentialInfo(
    val credentialId: String,
    val expiresAt: String,
    val isCaller: Boolean,
)

data class ListAccessResponse(
    val credentials: List<CredentialInfo>,
    val page: Page? = null,
)

data class CustomOidcProviderConfig(
    val issuer: String,
    val clientId: String,
    val authorizationUrl: String,
    val providerRedirectUri: String,
    val provider: String? = null,
    val providerLabel: String? = null,
    val scopes: List<String> = emptyList(),
    val authorizeParams: Map<String, String> = emptyMap(),
    val authMode: OidcRedirectAuthMode = OidcRedirectAuthMode.AuthCodePKCE,
)

sealed interface OmsRelayOidcProvider

object OmsRelayOidcProviders {
    val google: OmsRelayOidcProvider

    val apple: OmsRelayOidcProvider
}

@Serializable
enum class OidcRedirectAuthMode {
    @SerialName("auth-code")
    AuthCode,
    @SerialName("auth-code-pkce")
    AuthCodePKCE,
}

data class StartOidcRedirectAuthResult(
    val authorizationUrl: String,
)

sealed interface OidcRedirectAuthResult

data class Completed(
    val result: CompleteAuthResult,
) : OidcRedirectAuthResult

data object NotOidcRedirectCallback : OidcRedirectAuthResult

data object NoPendingAuth : OidcRedirectAuthResult

data class WalletSelectionResult(
    val walletAddress: String,
    val wallet: Wallet,
)

enum class WalletSelectionBehavior {
    /**
     * Selects the first existing wallet for the requested wallet type, or
     * creates and selects one when none exists. Use `Manual` when the app needs
     * to present wallet choices.
     */
    Automatic,
    /**
     * Completes auth and returns a `PendingWalletSelection` for app-driven
     * wallet selection.
     */
    Manual,
}

class PendingWalletSelection {
    val walletType: WalletType

    val wallets: List<Wallet>

    val credential: CredentialInfo

    /**
     * Selects one of `wallets` and persists it as the active wallet session.
     */
    suspend fun selectWallet(walletId: String): WalletSelectionResult

    /**
     * Creates a new wallet for `walletType`, selects it, and persists it as the
     * active wallet session.
     */
    suspend fun createAndSelectWallet(reference: String? = null): WalletSelectionResult
}

sealed interface CompleteAuthResult

data class WalletSelected(
    val walletAddress: String,
    val wallet: Wallet,
    val wallets: List<Wallet>,
    val credential: CredentialInfo,
) : CompleteAuthResult

data class WalletSelection(
    val pendingSelection: PendingWalletSelection,
) : CompleteAuthResult

class WalletClient

const val DEFAULT_SESSION_LIFETIME_SECONDS: Long = 604_800L

const val MAX_SESSION_LIFETIME_SECONDS: Long = 2_592_000L

val walletAddress: String?

val session: OMSWalletSessionState

fun onSessionExpired(listener: (OMSWalletSessionExpiredEvent) -> Unit): () -> Unit

fun signOut()

suspend fun startEmailAuth(
    email: String,
    sessionLifetimeSeconds: Long = DEFAULT_SESSION_LIFETIME_SECONDS,
): Unit

suspend fun signInWithOidcIdToken(
    idToken: String,
    issuer: String,
    audience: String,
    walletSelection: WalletSelectionBehavior = WalletSelectionBehavior.Automatic,
    walletType: WalletType = WalletType.Ethereum,
    sessionLifetimeSeconds: Long = DEFAULT_SESSION_LIFETIME_SECONDS,
    provider: String? = null,
    providerLabel: String? = null,
): CompleteAuthResult

suspend fun startOidcRedirectAuth(
    provider: OmsRelayOidcProvider,
    omsRelayReturnUri: String,
    walletType: WalletType = WalletType.Ethereum,
    walletSelection: WalletSelectionBehavior? = null,
    sessionLifetimeSeconds: Long? = null,
    loginHint: String? = null,
): StartOidcRedirectAuthResult

suspend fun startOidcRedirectAuth(
    provider: CustomOidcProviderConfig,
    walletType: WalletType = WalletType.Ethereum,
    walletSelection: WalletSelectionBehavior? = null,
    sessionLifetimeSeconds: Long? = null,
    authorizeParams: Map<String, String> = emptyMap(),
    loginHint: String? = null,
): StartOidcRedirectAuthResult

suspend fun handleOidcRedirectCallback(
    callbackUrl: String?,
    walletSelection: WalletSelectionBehavior? = null,
    sessionLifetimeSeconds: Long? = null,
): OidcRedirectAuthResult

suspend fun completeEmailAuth(
    code: String,
    walletSelection: WalletSelectionBehavior = WalletSelectionBehavior.Automatic,
    walletType: WalletType = WalletType.Ethereum,
): CompleteAuthResult

suspend fun useWallet(walletId: String): WalletSelectionResult

suspend fun createWallet(
    walletType: WalletType = WalletType.Ethereum,
    reference: String? = null,
): WalletSelectionResult

suspend fun listWallets(): List<Wallet>

suspend fun listAccess(pageSize: UInt? = null): List<CredentialInfo>

fun listAccessPages(pageSize: UInt? = null): Flow<ListAccessResponse>

suspend fun listAccessPage(
    pageSize: UInt? = null,
    cursor: String? = null,
): ListAccessResponse

suspend fun getIdToken(
    ttlSeconds: UInt? = null,
    customClaims: Map<String, JsonElement>? = null,
): String

suspend fun revokeAccess(targetCredentialId: String): Unit

enum class TransactionMode(
    val wireValue: String,
) {
    Native("native"),
    Relayer("relayer"),
    UNKNOWN_DEFAULT("UNKNOWN_DEFAULT"),
}

enum class TransactionStatus(
    val wireValue: String,
) {
    Quoted("quoted"),
    Pending("pending"),
    Executed("executed"),
    Failed("failed"),
    UNKNOWN_DEFAULT("UNKNOWN_DEFAULT"),
}

data class FeeToken(
    val network: String,
    val name: String,
    val symbol: String,
    val type: String,
    val decimals: UInt? = null,
    val logoUrl: String? = null,
    val contractAddress: String? = null,
    val tokenId: String? = null,
)

data class FeeOption(
    val token: FeeToken,
    val value: String,
    val displayValue: String,
)

data class FeeOptionSelection(
    val token: String,
) {
    constructor(feeOption: FeeOption)
}

data class AbiArg(
    val type: String,
    val value: JsonElement,
)

data class TransactionStatusResponse(
    val status: TransactionStatus,
    val txnHash: String? = null,
)

fun interface FeeOptionSelector {
    suspend fun select(feeOptions: List<FeeOptionWithBalance>): FeeOptionSelection?

    companion object {
        /**
         * Selects the first fee option whose available raw balance covers the
         * quoted fee value. Returns null when no option has sufficient balance.
         */
        val firstAvailable: FeeOptionSelector
    }
}

data class FeeOptionWithBalance(
    val feeOption: FeeOption,
    val balance: TokenBalance?,
    val available: String?,
    val availableRaw: String?,
    val decimals: Int?,
) {
    val selection: FeeOptionSelection
}

data class SendTransactionRequest(
    val to: String,
    /**
     * Raw base-unit transaction value. Use
     * `technology.polygon.omswallet.utils.parseUnits` to convert decimal display
     * values before sending.
     */
    val value: BigInteger,
    val data: String? = null,
    val mode: TransactionMode = TransactionMode.Relayer,
)

data class SendTransactionResponse(
    val txnId: String,
    val status: TransactionStatus,
    val txnHash: String?,
    val statusResolution: TransactionStatusResolution,
)

enum class TransactionStatusResolution {
    NotRequested,
    Resolved,
    TimedOut,
}

data class TransactionStatusPollingOptions(
    val fastPollIntervalMillis: Long = 400L,
    val fastPollCount: Int = 5,
    val pollIntervalMillis: Long = 2_000L,
    val timeoutMillis: Long = 60_000L,
)

suspend fun signMessage(
    network: Network,
    message: String,
): String

suspend fun signTypedData(
    network: Network,
    typedData: JsonElement,
): String

suspend fun isValidMessageSignature(
    network: Network,
    message: String,
    signature: String,
): Boolean

suspend fun isValidTypedDataSignature(
    network: Network,
    typedData: JsonElement,
    signature: String,
): Boolean

suspend fun sendTransaction(
    network: Network,
    to: String,
    value: BigInteger,
    waitForStatus: Boolean = true,
    statusPolling: TransactionStatusPollingOptions? = null,
    selectFeeOption: FeeOptionSelector? = null,
): ClientSendTransactionResponse

suspend fun sendTransaction(
    network: Network,
    request: ClientSendTransactionRequest,
    waitForStatus: Boolean = true,
    statusPolling: TransactionStatusPollingOptions? = null,
    selectFeeOption: FeeOptionSelector? = null,
): ClientSendTransactionResponse

suspend fun callContract(
    network: Network,
    contract: String,
    method: String,
    args: List<AbiArg>? = null,
    mode: TransactionMode = TransactionMode.Relayer,
    waitForStatus: Boolean = true,
    statusPolling: TransactionStatusPollingOptions? = null,
    selectFeeOption: FeeOptionSelector? = null,
): ClientSendTransactionResponse

suspend fun getTransactionStatus(txnId: String): TransactionStatusResponse

class IndexerClient

suspend fun getBalances(
    walletAddress: String,
    networks: List<Network> = emptyList(),
    networkType: IndexerNetworkType = IndexerNetworkType.MAINNETS,
    contractAddresses: List<String> = emptyList(),
    includeMetadata: Boolean = true,
    omitPrices: Boolean? = null,
    tokenIds: List<String> = emptyList(),
    contractStatus: ContractVerificationStatus? = null,
    page: TokenBalancesPageRequest = TokenBalancesPageRequest(),
): TokenBalancesResult

suspend fun getTransactionHistory(
    walletAddress: String,
    networks: List<Network> = emptyList(),
    networkType: IndexerNetworkType = IndexerNetworkType.MAINNETS,
    contractAddresses: List<String> = emptyList(),
    transactionHashes: List<String> = emptyList(),
    metaTransactionIds: List<String> = emptyList(),
    fromBlock: Long? = null,
    toBlock: Long? = null,
    tokenId: String? = null,
    includeMetadata: Boolean = true,
    omitPrices: Boolean? = null,
    metadataOptions: MetadataOptions? = null,
    page: TokenBalancesPageRequest = TokenBalancesPageRequest(),
): TransactionHistoryResult

data class TokenBalancesPageRequest(
    val page: Int = 0,
    val pageSize: Int = 40,
)

enum class IndexerNetworkType(
    val wireValue: String,
) {
    MAINNETS("MAINNETS"),
    TESTNETS("TESTNETS"),
    ALL("ALL"),
}

enum class ContractVerificationStatus(
    val wireValue: String,
) {
    VERIFIED("VERIFIED"),
    UNVERIFIED("UNVERIFIED"),
    ALL("ALL"),
}

data class TokenBalancesPage(
    val page: Int,
    val pageSize: Int,
    val more: Boolean,
)

data class MetadataOptions(
    val verifiedOnly: Boolean? = null,
    val unverifiedOnly: Boolean? = null,
    val includeContracts: List<String> = emptyList(),
)

data class TokenContractInfo(
    val chainId: Long,
    val address: String,
    val source: String,
    val name: String,
    val type: String,
    val symbol: String,
    val decimals: Int? = null,
    val logoURI: String? = null,
    val deployed: Boolean,
    val bytecodeHash: String,
    val extensions: Map<String, JsonElement>,
    val updatedAt: String,
    val queuedAt: String? = null,
    val status: String,
)

data class TokenMetadataAsset(
    val id: Long? = null,
    val collectionId: Long? = null,
    val tokenId: String? = null,
    val url: String? = null,
    val metadataField: String? = null,
    val name: String? = null,
    val filesize: Long? = null,
    val mimeType: String? = null,
    val width: Int? = null,
    val height: Int? = null,
    val updatedAt: String? = null,
)

data class TokenMetadata(
    val chainId: Long? = null,
    val contractAddress: String? = null,
    val tokenId: String,
    val source: String,
    val name: String,
    val description: String? = null,
    val image: String? = null,
    val video: String? = null,
    val audio: String? = null,
    val properties: Map<String, JsonElement>? = null,
    val attributes: List<Map<String, JsonElement>>,
    val imageData: String? = null,
    val externalUrl: String? = null,
    val backgroundColor: String? = null,
    val animationUrl: String? = null,
    val decimals: Int? = null,
    val updatedAt: String? = null,
    val assets: List<TokenMetadataAsset>? = null,
    val status: String,
    val queuedAt: String? = null,
    val lastFetched: String? = null,
)

sealed interface TokenBalance {
    val contractType: String

    val accountAddress: String

    val balance: String

    val chainId: Long

    val balanceUSD: String?

    val priceUSD: String?

    val priceUpdatedAt: String?
}

data class NativeTokenBalance(
    override val accountAddress: String,
    val name: String,
    val symbol: String,
    override val balance: String,
    override val chainId: Long,
    override val balanceUSD: String? = null,
    override val priceUSD: String? = null,
    override val priceUpdatedAt: String? = null,
) : TokenBalance {
    override val contractType: String
}

data class ContractTokenBalance(
    override val contractType: String,
    val contractAddress: String,
    override val accountAddress: String,
    val tokenId: String,
    override val balance: String,
    val blockHash: String,
    val blockNumber: Long,
    override val chainId: Long,
    override val balanceUSD: String? = null,
    override val priceUSD: String? = null,
    override val priceUpdatedAt: String? = null,
    val uniqueCollectibles: String? = null,
    val isSummary: Boolean? = null,
    val contractInfo: TokenContractInfo? = null,
    val tokenMetadata: TokenMetadata? = null,
) : TokenBalance

data class TokenBalancesResult(
    val status: Int,
    val page: TokenBalancesPage?,
    val balances: List<ContractTokenBalance>,
    val nativeBalances: List<NativeTokenBalance> = emptyList(),
)

data class TransactionTransfer(
    val transferType: String,
    val contractAddress: String,
    val contractType: String,
    val from: String,
    val to: String,
    val tokenIds: List<String>? = null,
    val amounts: List<String>,
    val logIndex: Long,
    val amountsUSD: List<String>? = null,
    val pricesUSD: List<String>? = null,
    val contractInfo: TokenContractInfo? = null,
    val tokenMetadata: Map<String, TokenMetadata>? = null,
)

data class Transaction(
    val txnHash: String,
    val blockNumber: Long,
    val blockHash: String,
    val chainId: Long,
    val metaTxnId: String? = null,
    val transfers: List<TransactionTransfer> = emptyList(),
    val timestamp: String,
)

data class TransactionHistoryResult(
    val status: Int,
    val page: TokenBalancesPage?,
    val transactions: List<Transaction>,
)

class Network {
    val id: Int

    val name: String

    val nativeTokenSymbol: String

    val explorerUrl: String

    val displayName: String

    override fun equals(other: Any?): Boolean

    override fun hashCode(): Int

    override fun toString(): String

    companion object {
        val MAINNET: Network

        val SEPOLIA: Network

        val POLYGON: Network

        val AMOY: Network

        val ARBITRUM: Network

        val ARBITRUM_SEPOLIA: Network

        val OPTIMISM: Network

        val OPTIMISM_SEPOLIA: Network

        val BASE: Network

        val BASE_SEPOLIA: Network

        val BSC: Network

        val BSC_TESTNET: Network

        val ARBITRUM_NOVA: Network

        val AVALANCHE: Network

        val AVALANCHE_TESTNET: Network

        val KATANA: Network

        val entries: List<Network>
    }
}

object OMSWalletNetworks {
    /**
     * All networks currently supported by this SDK build.
     */
    val supportedNetworks: List<Network>

    /**
     * Returns a supported network by chain id.
     */
    fun findById(id: Int): Network?

    /**
     * Returns a supported network by registry name.
     */
    fun findByName(name: String): Network?
}

enum class OMSWalletErrorCode(
    val id: String,
) {
    HttpError("OMS_HTTP_ERROR"),
    InvalidResponse("OMS_INVALID_RESPONSE"),
    RequestFailed("OMS_REQUEST_FAILED"),
    AuthCommitmentConsumed("OMS_AUTH_COMMITMENT_CONSUMED"),
    SessionMissing("OMS_SESSION_MISSING"),
    SessionExpired("OMS_SESSION_EXPIRED"),
    WalletSelectionStale("OMS_WALLET_SELECTION_STALE"),
    WalletSelectionUnavailable("OMS_WALLET_SELECTION_UNAVAILABLE"),
    WalletSelectionInFlight("OMS_WALLET_SELECTION_IN_FLIGHT"),
    TransactionExecutionUnconfirmed("OMS_TRANSACTION_EXECUTION_UNCONFIRMED"),
    TransactionStatusLookupFailed("OMS_TRANSACTION_STATUS_LOOKUP_FAILED"),
    ValidationError("OMS_VALIDATION_ERROR"),
    StorageError("OMS_STORAGE_ERROR"),
}

enum class OMSWalletOperation(
    val id: String,
) {
    PendingWalletSelection("wallet.pendingWalletSelection"),
    PendingWalletSelectionCreateAndSelectWallet("wallet.pendingWalletSelection.createAndSelectWallet"),
    PendingWalletSelectionSelectWallet("wallet.pendingWalletSelection.selectWallet"),
    IndexerGetBalances("indexer.getBalances"),
    IndexerGetTransactionHistory("indexer.getTransactionHistory"),
    WalletCallContract("wallet.callContract"),
    WalletCompleteEmailAuth("wallet.completeEmailAuth"),
    WalletCreateWallet("wallet.createWallet"),
    WalletExecute("wallet.execute"),
    WalletGetIdToken("wallet.getIdToken"),
    WalletHandleOidcRedirectCallback("wallet.handleOidcRedirectCallback"),
    WalletGetTransactionStatus("wallet.getTransactionStatus"),
    WalletIsValidMessageSignature("wallet.isValidMessageSignature"),
    WalletIsValidTypedDataSignature("wallet.isValidTypedDataSignature"),
    WalletListAccess("wallet.listAccess"),
    WalletListAccessPage("wallet.listAccessPage"),
    WalletListAccessPages("wallet.listAccessPages"),
    WalletListWallets("wallet.listWallets"),
    WalletRevokeAccess("wallet.revokeAccess"),
    WalletSendTransaction("wallet.sendTransaction"),
    WalletSignInWithOidcIdToken("wallet.signInWithOidcIdToken"),
    WalletSignMessage("wallet.signMessage"),
    WalletSignOut("wallet.signOut"),
    WalletSignTypedData("wallet.signTypedData"),
    WalletStartEmailAuth("wallet.startEmailAuth"),
    WalletStartOidcRedirectAuth("wallet.startOidcRedirectAuth"),
    WalletTransactionStatus("wallet.transactionStatus"),
    WalletUseWallet("wallet.useWallet"),
}

enum class OMSWalletUpstreamService {
    Waas,
    Indexer,
}

data class OMSWalletUpstreamError(
    val service: OMSWalletUpstreamService,
    val name: String? = null,
    val code: String? = null,
    val message: String? = null,
    val status: Int? = null,
)

sealed class OMSWalletException(
    val code: OMSWalletErrorCode,
    val operation: OMSWalletOperation? = null,
    val status: Int? = null,
    val txnId: String? = null,
    val retryable: Boolean? = null,
    val upstreamError: OMSWalletUpstreamError? = null,
    message: String,
    cause: Throwable? = null,
) : RuntimeException

class OMSWalletSessionException(
    code: OMSWalletErrorCode = OMSWalletErrorCode.SessionMissing,
    operation: OMSWalletOperation? = null,
    message: String = "No active wallet session",
    cause: Throwable? = null,
) : OMSWalletException

class OMSWalletRequestException(
    code: OMSWalletErrorCode = OMSWalletErrorCode.RequestFailed,
    operation: OMSWalletOperation? = null,
    status: Int? = null,
    retryable: Boolean? = status == null || status >= 500,
    upstreamError: OMSWalletUpstreamError? = null,
    message: String = "OMS request failed",
    cause: Throwable? = null,
) : OMSWalletException

class OMSWalletResponseException(
    operation: OMSWalletOperation? = null,
    status: Int? = null,
    upstreamError: OMSWalletUpstreamError? = null,
    message: String = "OMS response was invalid",
    cause: Throwable? = null,
) : OMSWalletException

class OMSWalletTransactionException(
    code: OMSWalletErrorCode = OMSWalletErrorCode.TransactionStatusLookupFailed,
    operation: OMSWalletOperation? = null,
    status: Int? = null,
    txnId: String? = null,
    retryable: Boolean? = true,
    upstreamError: OMSWalletUpstreamError? = null,
    message: String = "Transaction status lookup failed",
    cause: Throwable? = null,
) : OMSWalletException

class OMSWalletSelectionException(
    code: OMSWalletErrorCode,
    operation: OMSWalletOperation? = null,
    message: String,
    cause: Throwable? = null,
) : OMSWalletException

class OMSWalletValidationException(
    operation: OMSWalletOperation? = null,
    message: String,
    cause: Throwable? = null,
) : OMSWalletException

class OMSWalletStorageException(
    operation: OMSWalletOperation? = null,
    message: String,
    cause: Throwable? = null,
) : OMSWalletException

fun formatUnits(
    value: BigInteger,
    decimals: Int,
): String

fun parseUnits(
    value: String,
    decimals: Int,
): BigInteger