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"),
    Solana("solana"),
    UNKNOWN_DEFAULT("UNKNOWN_DEFAULT"),
}

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

enum class WalletKeyOrigin(
    val wireValue: String,
) {
    Enclave("enclave"),
    Imported("imported"),
    UNKNOWN_DEFAULT("UNKNOWN_DEFAULT"),
}

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

enum class WalletImportCipherSuite(
    val wireValue: String,
) {
    X25519Sha256Aes256Gcm("x25519-sha256-aes256gcm"),
    X25519Sha256ChaCha20Poly1305("x25519-sha256-chacha20poly1305"),
    P256Sha256Aes256Gcm("p256-sha256-aes256gcm"),
    P256Sha256ChaCha20Poly1305("p256-sha256-chacha20poly1305"),
}

sealed interface WalletImportPrivateKey {
    val walletType: WalletType
}

data class Ethereum(
    val value: String,
) : WalletImportPrivateKey {
    override val walletType: WalletType
}

class EthereumBytes(
    val value: ByteArray,
) : WalletImportPrivateKey {
    override val walletType: WalletType
}

data class Solana(
    val value: String,
) : WalletImportPrivateKey {
    override val walletType: WalletType
}

class SolanaBytes(
    val value: ByteArray,
) : WalletImportPrivateKey {
    override val walletType: WalletType
}

data class WalletImportRecipientKey(
    val keyId: String,
    val cipherSuite: WalletImportCipherSuite,
    val publicKey: String,
)

data class EncryptedWalletImportKeyMaterial(
    val keyId: String,
    val cipherSuite: WalletImportCipherSuite,
    val encapsulatedKey: String,
    val ciphertext: String,
)

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

data class RemoteCredentialMetadata(
    val appUrl: String,
    val appName: String,
    val appLogoUrl: String,
    val custom: Map<String, String>,
)

sealed interface SmartSessionGrant

data class NativeTransfer(
    val to: String,
    val limit: BigInteger,
) : SmartSessionGrant

data class Erc20Transfer(
    val token: String,
    val to: String? = null,
    val limit: BigInteger,
    val cumulative: Boolean? = null,
) : SmartSessionGrant

enum class AccessGrantType {
    Direct,
    Remote,
}

sealed interface AccessGrant {
    val credential: WalletCredential
}

data class Direct(
    override val credential: WalletCredential,
) : AccessGrant

data class Remote(
    override val credential: WalletCredential,
    val sessionId: String,
    val metadata: RemoteCredentialMetadata,
    val grants: List<SmartSessionGrant>,
) : AccessGrant

data class AccessGrantPage(
    val grants: List<AccessGrant>,
    val page: Page? = null,
)

data class AuthorizedRemoteAccess(
    val walletId: String,
    val sessionId: String,
    val expiresAt: String,
)

data class RemoteAccessSession(
    val sessionId: String,
    val walletId: String,
    val signerAddress: String,
    val grants: List<SmartSessionGrant>,
    val chainId: Int,
    val expiresAt: String,
)

data class SmartSessionGrantUsage(
    val grant: SmartSessionGrant,
    val used: BigInteger? = 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: WalletCredential

    /**
     * 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: WalletCredential,
) : 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 importWallet(
    privateKey: WalletImportPrivateKey,
    reference: String? = null,
): WalletSelectionResult

suspend fun getWalletImportRecipientKey(cipherSuite: WalletImportCipherSuite): WalletImportRecipientKey

suspend fun importEncryptedWallet(
    walletType: WalletType,
    keyMaterial: EncryptedWalletImportKeyMaterial,
    reference: String? = null,
): WalletSelectionResult

suspend fun listWallets(): List<Wallet>

suspend fun inspectRemoteCredential(credentialId: String): RemoteCredentialMetadata

suspend fun authorizeRemoteAccess(
    credentialId: String,
    network: Network,
    grants: List<SmartSessionGrant>,
    expiresAt: String,
    sessionId: String? = null,
): AuthorizedRemoteAccess

suspend fun listAccess(
    pageSize: UInt? = null,
    type: AccessGrantType? = null,
): List<AccessGrant>

fun listAccessPages(
    pageSize: UInt? = null,
    type: AccessGrantType? = null,
): Flow<AccessGrantPage>

suspend fun listAccessPage(
    pageSize: UInt? = null,
    cursor: String? = null,
    type: AccessGrantType? = null,
): AccessGrantPage

suspend fun getRemoteAccessSession(sessionId: String): RemoteAccessSession

suspend fun getRemoteAccessSessionUsage(
    sessionId: String,
    network: Network,
): List<SmartSessionGrantUsage>

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

suspend fun revokeAccess(
    credentialId: String,
    sessionId: String? = null,
): 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,
    val index: UInt? = null,
) {
    constructor(feeOption: FeeOption, index: UInt? = null)
}

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 selection: FeeOptionSelection = FeeOptionSelection(feeOption),
    val balance: TokenBalance? = null,
    val available: String? = null,
    val availableRaw: String? = null,
    val decimals: Int? = null,
)

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 signSolanaMessage(message: String): String

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

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

suspend fun isValidSolanaMessageSignature(
    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,
): SendTransactionResponse

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

suspend fun sendSolanaTransfer(
    network: SolanaNetwork,
    asset: String,
    to: String,
    amount: BigInteger,
    mode: TransactionMode = TransactionMode.Relayer,
    waitForStatus: Boolean = true,
    statusPolling: TransactionStatusPollingOptions? = null,
    selectFeeOption: FeeOptionSelector? = null,
): SendTransactionResponse

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,
): SendTransactionResponse

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

suspend fun getSolanaBalances(
    walletAddress: String,
    networks: List<SolanaNetwork> = listOf(SolanaNetwork.Mainnet, SolanaNetwork.Devnet),
    includeMetadata: Boolean = true,
    omitNativeBalances: Boolean? = null,
    mintAddresses: List<String> = emptyList(),
    excludedMintAddresses: List<String> = emptyList(),
): SolanaBalancesResult

enum class SolanaVerificationStatus {
    Verified,
    Unverified,
    Unknown,
}

enum class SolanaVerificationSource {
    Jupiter,
    SolflareUtl,
    None,
}

enum class SolanaTokenProgram {
    SplToken,
    Token2022,
}

sealed interface SolanaBalance {
    val network: SolanaNetwork

    val accountAddress: String

    val name: String

    val symbol: String

    val decimals: Int

    val balance: String

    val formattedBalance: String

    val imageUrl: String?

    val metadataUri: String?

    val verificationStatus: SolanaVerificationStatus

    val verificationSource: SolanaVerificationSource

    val priceUSD: String?

    val balanceUSD: String?
}

data class Native(
    override val network: SolanaNetwork,
    override val accountAddress: String,
    override val name: String,
    override val symbol: String,
    override val decimals: Int,
    override val balance: String,
    override val formattedBalance: String,
    override val imageUrl: String?,
    override val metadataUri: String?,
    override val verificationStatus: SolanaVerificationStatus,
    override val verificationSource: SolanaVerificationSource,
    override val priceUSD: String?,
    override val balanceUSD: String?,
) : SolanaBalance

data class FungibleToken(
    override val network: SolanaNetwork,
    override val accountAddress: String,
    val tokenProgram: SolanaTokenProgram,
    val mintAddress: String,
    override val name: String,
    override val symbol: String,
    override val decimals: Int,
    override val balance: String,
    override val formattedBalance: String,
    override val imageUrl: String?,
    override val metadataUri: String?,
    override val verificationStatus: SolanaVerificationStatus,
    override val verificationSource: SolanaVerificationSource,
    override val priceUSD: String?,
    override val balanceUSD: String?,
) : SolanaBalance

data class SolanaNetworkError(
    val network: SolanaNetwork,
    val reason: String,
)

data class SolanaBalancesResult(
    val status: Int,
    val balances: List<SolanaBalance>,
    val errors: List<SolanaNetworkError>,
)

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(),
)