Skip to content

API.md

Latest commit

 

History

History
1867 lines (1431 loc) · 54.3 KB

API.md

File metadata and controls

1867 lines (1431 loc) · 54.3 KB

OMS SDK — API Reference

Table of Contents

OMSClient

The top-level entry point for the SDK.

import { OMSClient } from '@0xsequence/typescript-sdk'

const oms = new OMSClient({
  publishableKey: 'your-publishable-key',
})

Constructor

new OMSClient(params: {
  publishableKey: string
  auth?: OmsAuthConfig
  storage?: StorageManager
  redirectAuthStorage?: StorageManager
  credentialSigner?: CredentialSigner
})

Parameters

Name Type Required Description
publishableKey string Yes Your OMS publishable key.
auth OmsAuthConfig No OIDC provider configuration. Defaults to the built-in Google provider.
storage StorageManager No Storage backend for wallet metadata. Defaults to LocalStorageManager when browser localStorage is available, otherwise MemoryStorageManager.
redirectAuthStorage StorageManager No Transient storage for OIDC redirect auth state. Defaults to sessionStorage when available.
credentialSigner CredentialSigner No Request credential signer. Defaults to a non-extractable WebCrypto P-256 signer (ecdsa-p256-sha256) where WebCrypto is available.

Properties

Name Type Description
wallet WalletClient Handles authentication, signing, and transactions.
indexer IndexerClient Queries on-chain state and token balances.
supportedNetworks readonly Network[] Networks configured by the SDK. Same value as the exported supportedNetworks.

supportedNetworks

oms.supportedNetworks: readonly Network[]

Returns the supported network registry. Each entry has id, name, nativeTokenSymbol, explorerUrl, and displayName.

WalletClient

Accessed via oms.wallet. Manages the full wallet lifecycle: authentication, session persistence, signing, and transaction submission.

walletAddress

walletAddress: Address | undefined

The on-chain address of the active wallet (Address is the viem/abitype hex address type). Undefined until email or OIDC auth completes successfully, or a persisted session is restored.

session

type OMSClientSessionLoginType = 'email' | 'google-auth' | 'oidc'

interface OMSClientSessionState {
  walletAddress: Address | undefined
  expiresAt: string | undefined
  loginType: OMSClientSessionLoginType | undefined
  sessionEmail: string | undefined
}

interface OMSClientSessionExpiredEvent {
  session: OMSClientSessionState
  expiredAt: string
}

wallet.session: OMSClientSessionState

Completed wallet sessions persist walletAddress, credential expiry, login type, and returned email in the configured storage. Pending email OTP and OIDC redirect state are not exposed through session; use the auth method results to drive pending UI.

Expired sessions are made inactive before protected wallet operations and throw OmsSessionError with code OMS_SESSION_EXPIRED. The SDK clears the active signer/session state, but keeps the expired session metadata in storage until the app explicitly starts a new auth flow or calls signOut(). Use wallet.onSessionExpired to update app state or route back to sign-in; the event includes the expired session snapshot so apps can reuse sessionEmail for email OTP reauth or as a Google loginHint, including after a page refresh.

onSessionExpired

const unsubscribe = wallet.onSessionExpired((event) => {
  showReauth(event.session)
})

Registers a listener for expired wallet sessions and returns an unsubscribe function. The wallet client stores the latest expired-session event and replays it to each new listener until a new auth flow, new wallet session, or signOut() clears it.

startEmailAuth

startEmailAuth(params: { email: string }): Promise<void>

Sends a one-time passcode to the provided email address to begin authentication. If a wallet session is already active, it is cleared before the new auth attempt starts.

After this resolves, display an OTP input and pass the code to completeEmailAuth.

Parameters

Name Type Description
email string The email address to send the one-time passcode to.

Returns Promise<void>

Throws if the network request fails or the email is invalid.

Example

await oms.wallet.startEmailAuth({ email: 'user@example.com' })

completeEmailAuth

completeEmailAuth(params: {
  code: string
  walletType?: WalletType
  walletSelection?: 'automatic' | 'manual'
  sessionLifetimeSeconds?: number
}): Promise<
  | { walletAddress: Address; wallet: OmsWallet; wallets: OmsWallet[]; credential: WalletCredential }
  | PendingWalletSelection
>

Verifies the OTP code and activates a wallet. Must be called after startEmailAuth.

This method verifies the code with a one-week session lifetime by default, loads all wallet pages, then automatically selects an existing wallet matching walletType, or creates a new one if none exists. Wallet metadata is persisted to storage. Pass sessionLifetimeSeconds to request a shorter or longer session lifetime. Pass walletSelection: 'manual' to return a PendingWalletSelection bound to the verified auth flow; complete selection through that object.

Parameters

Name Type Required Description
code string Yes The one-time passcode entered by the user.
walletType WalletType No The wallet type to load or create. Defaults to WalletType.Ethereum.
walletSelection 'automatic' | 'manual' No Defaults to 'automatic'. Set to 'manual' to let the app choose an existing wallet or create one through the returned pending selection.
sessionLifetimeSeconds number No Requested session lifetime in seconds. Defaults to one week.

Returns Promise<{ walletAddress: Address; wallet: OmsWallet; wallets: OmsWallet[]; credential: WalletCredential }> by default, or Promise<PendingWalletSelection> when walletSelection is 'manual'.

Throws if the code is incorrect, expired, or the network request fails.

Example

try {
  const { walletAddress, credential } = await oms.wallet.completeEmailAuth({ code: '123456' })
  console.log('Wallet ready:', walletAddress, credential.credentialId)
} catch (err) {
  // Handle wrong or expired code
}

Manual selection:

const selection = await oms.wallet.completeEmailAuth({
  code: '123456',
  walletType: WalletType.Ethereum,
  walletSelection: 'manual',
})

await selection.selectWallet({ walletId: selection.wallets[0].id })
// or:
await selection.createAndSelectWallet({ reference: 'main' })

startOidcRedirectAuth

startOidcRedirectAuth(params: {
  provider: string | OidcProviderConfig
  redirectUri: string
  walletType?: WalletType
  relayRedirectUri?: string
  authorizeParams?: Record<string, string>
  loginHint?: string
}): Promise<{ url: string; state: string; challenge: string }>

Starts an OIDC authorization-code PKCE flow and returns the provider authorization URL. If a wallet session is already active, it is cleared before the new auth attempt starts. The SDK stores transient redirect auth state so the callback can complete after a full-page redirect.

If provider is a string, it must match a configured auth.oidcProviders key. Passing an OidcProviderConfig object directly is also supported.

When relayRedirectUri is set, the provider redirects through that relay before returning to the app redirectUri.

Pass loginHint for Google redirect flows to set the Google login_hint authorization parameter, which can prefill or select the expected account. The SDK only sends login_hint for providers whose issuer is https://accounts.google.com. If omitted, the SDK falls back to the previous active session email when one exists before the redirect auth attempt starts. After signOut(), that previous session email is cleared. To force no login_hint for a call, pass loginHint: ''.

const { url } = await oms.wallet.startOidcRedirectAuth({
  provider: 'google',
  redirectUri: `${window.location.origin}/auth/callback`,
})

window.location.assign(url)

completeOidcRedirectAuth

completeOidcRedirectAuth(params: {
  callbackUrl: string
  cleanUrl?: boolean
  replaceUrl?: (url: string) => void
  walletSelection?: 'automatic' | 'manual'
  sessionLifetimeSeconds?: number
}): Promise<
  | { walletAddress: Address; wallet: OmsWallet; wallets: OmsWallet[]; credential: WalletCredential }
  | PendingWalletSelection
>

Completes an OIDC redirect flow by validating the callback, completing auth with a one-week session lifetime by default, and activating an existing wallet or creating one. Pass sessionLifetimeSeconds to request a shorter or longer session lifetime. Pass walletSelection: 'manual' to return a PendingWalletSelection for app-driven wallet selection. cleanUrl removes OAuth query parameters after successful completion; outside a browser, pass replaceUrl.

const { walletAddress, credential } = await oms.wallet.completeOidcRedirectAuth({
  callbackUrl: window.location.href,
  cleanUrl: true,
})

signInWithOidcRedirect

signInWithOidcRedirect(params: {
  provider: string | OidcProviderConfig
  redirectUri?: string
  walletType?: WalletType
  walletSelection?: 'automatic' | 'manual'
  relayRedirectUri?: string
  authorizeParams?: Record<string, string>
  loginHint?: string
  sessionLifetimeSeconds?: number
  cleanUrl?: boolean
  currentUrl?: string
  assignUrl?: (url: string) => void
  replaceUrl?: (url: string) => void
}): Promise<{ walletAddress: Address; wallet: OmsWallet; wallets: OmsWallet[]; credential: WalletCredential } | PendingWalletSelection | void>

Browser convenience method for regular web apps. If the current URL has OIDC callback params, it completes auth and returns the same result as completeOidcRedirectAuth. Otherwise it starts auth, redirects with window.location.assign, and returns void. loginHint is passed through to the started redirect flow; sessionLifetimeSeconds is used when completing the callback and defaults to one week when omitted. For router-driven apps, prefer startOidcRedirectAuth and completeOidcRedirectAuth.

void oms.wallet.signInWithOidcRedirect({ provider: 'google' })

signOut

signOut(): Promise<void>

Clears the wallet session metadata from storage and clears the active credential signer where supported. After calling this, walletAddress and session metadata are no longer available and the user must authenticate again via startEmailAuth.

Returns Promise<void>

Example

await oms.wallet.signOut()

listWallets

listWallets(): Promise<OmsWallet[]>

Returns all wallets available to an authenticated active or pending wallet-selection session.

useWallet

useWallet(params: { walletId: string }): Promise<{ walletAddress: Address; wallet: OmsWallet }>

Activates an existing wallet by server-side wallet id and persists it as the current wallet session. Requires an active wallet session; pending manual auth flows must use PendingWalletSelection.selectWallet.

createWallet

createWallet(params?: { type?: WalletType; reference?: string }): Promise<{ walletAddress: Address; wallet: OmsWallet }>

Creates a new wallet, activates it, and persists it as the current wallet session. Requires an active wallet session. type defaults to WalletType.Ethereum. Pending manual auth flows must use PendingWalletSelection.createAndSelectWallet, which uses the auth-requested wallet type automatically.

getIdToken

getIdToken(params?: {
  ttlSeconds?: number
  customClaims?: Record<string, unknown>
}): Promise<string>

Requests an ID token for the active wallet session. The SDK uses the active wallet id automatically.

Parameters

Name Type Description
ttlSeconds number Optional token lifetime in seconds.
customClaims Record<string, unknown> Optional custom claims to include in the token.

Returns Promise<string> — the issued ID token.

signMessage

signMessage(params: {
  network: Network
  message: string
}): Promise<string>

Signs an arbitrary message using the active wallet session credential.

Parameters

Name Type Description
network Network The network for the signing context. Use an exported registry value such as Networks.polygon. See Network.
message string The message to sign.

Returns Promise<string> — a hex-encoded signature.

Example

import { Networks } from '@0xsequence/typescript-sdk'
const sigFromNetwork = await oms.wallet.signMessage({ network: Networks.polygon, message: 'some message to sign' })

signTypedData

signTypedData(params: {
  network: Network
  typedData: any
}): Promise<string>

Signs EIP-712 typed data using the active wallet session credential.

Returns Promise<string> — a hex-encoded signature.

isValidMessageSignature

isValidMessageSignature(params: {
  network?: Network
  walletAddress?: Address
  walletId?: string
  message: string
  signature: string
}): Promise<boolean>

Validates a message signature. If neither walletAddress nor walletId is provided, the active wallet session id is used when available.

isValidTypedDataSignature

isValidTypedDataSignature(params: {
  network?: Network
  walletAddress?: Address
  walletId?: string
  typedData: any
  signature: string
}): Promise<boolean>

Validates an EIP-712 typed data signature. If neither walletAddress nor walletId is provided, the active wallet session id is used when available.

getTransactionStatus

getTransactionStatus(params: { txnId: string }): Promise<TransactionStatusResponse>

Fetches the latest status for a prepared/executed transaction. This is useful after calling sendTransaction with waitForStatus: false.

sendTransaction

sendTransaction is overloaded with three signatures depending on the type of transaction.

Native Token Transfer

sendTransaction(params: SendNativeTransactionParams): Promise<SendTransactionResponse>

Sends native tokens (ETH, POL, etc.) to an address.

import { parseUnits } from 'viem'

const tx = await oms.wallet.sendTransaction({
  network: Networks.polygon,
  to: '0xRecipient',
  value: parseUnits('1', 18), // 1 POL
})

Raw Data Transaction

sendTransaction(params: SendDataTransactionParams): Promise<SendTransactionResponse>

Sends a transaction with arbitrary calldata as a hex string. Use this when you have pre-encoded calldata.

const tx = await oms.wallet.sendTransaction({
  network: Networks.polygon,
  to: '0xContract',
  data: '0xa9059cbb000000000000000000000000...',
})

ABI-Encoded Contract Call

sendTransaction<abi, functionName>(params: SendContractTransactionParams<abi, functionName>): Promise<SendTransactionResponse>

Sends a contract interaction with fully-typed ABI encoding via viem. The calldata is encoded automatically from abi, functionName, and args.

import { parseUnits } from 'viem'

const erc20Abi = [
  {
    name: 'transfer',
    type: 'function',
    inputs: [
      { name: 'to', type: 'address' },
      { name: 'amount', type: 'uint256' },
    ],
  },
] as const

const tx = await oms.wallet.sendTransaction({
  network: Networks.polygon,
  to: '0xTokenContract',
  abi: erc20Abi,
  functionName: 'transfer',
  args: ['0xRecipient', parseUnits('1', 18)],
})

All three variants share the following optional base fields:

Name Type Description
value bigint Native token value to attach (in wei).
mode TransactionMode Transaction execution mode. Defaults to TransactionMode.Relayer.
selectFeeOption FeeOptionSelector Optional callback for choosing a fee option.
waitForStatus boolean Set to false to return immediately after execute without polling transaction status.
statusPolling TransactionStatusPollingOptions Optional post-execute polling configuration.

Returns Promise<SendTransactionResponse> — the prepared transaction ID, latest status, and transaction hash when available.

Throws if no session is active, the transaction reverts, or the request fails.

When fee options are returned, selectFeeOption receives FeeOptionWithBalance[]. Each entry includes the FeeOption plus the selected wallet's balance for that fee token when the indexer can load it. Use FeeOptionSelector.firstAvailable to choose the first option the wallet can pay, or return option.selection from a custom selector.

callContract

callContract(params: {
  network: Network
  contractAddress: Address
  method: string
  args?: AbiArg[]
  mode?: TransactionMode
  selectFeeOption?: FeeOptionSelector
  waitForStatus?: boolean
  statusPolling?: TransactionStatusPollingOptions
}): Promise<SendTransactionResponse>

Calls a state-changing smart contract function using a method signature string and loosely-typed argument list. For fully-typed ABI encoding, prefer the ABI overload of sendTransaction.

Parameters

Name Type Required Description
network Network Yes Network identifier. See Network.
contractAddress Address Yes Address of the target contract.
method string Yes ABI function signature, e.g. "transfer(address,uint256)".
args AbiArg[] No Ordered list of typed arguments. See AbiArg.
mode TransactionMode No Transaction execution mode. Defaults to TransactionMode.Relayer.
selectFeeOption FeeOptionSelector No Optional callback for choosing a fee option.
waitForStatus boolean No Set to false to return immediately after execute without polling transaction status.
statusPolling TransactionStatusPollingOptions No Optional post-execute polling configuration.

Returns Promise<SendTransactionResponse> — the prepared transaction ID, latest status, and transaction hash when available.

Example

import { parseUnits } from 'viem'

const tx = await oms.wallet.callContract({
  network: Networks.polygon,
  contractAddress: '0xTokenContract',
  method: 'transfer(address,uint256)',
  args: [
    { type: 'address', value: '0xRecipient' },
    { type: 'uint256', value: parseUnits('1', 18).toString() },
  ],
})

listAccess

listAccess(params?: ListAccessParams): Promise<AccessGrant[]>

Returns all credentials that currently have access to this wallet across all pages.

Returns Promise<AccessGrant[]> — see AccessGrant.

Example

const grants = await oms.wallet.listAccess()
console.log(grants.filter(g => g.isCaller)) // current session

listAccessPages

listAccessPages(params?: ListAccessParams): AsyncIterable<AccessGrantPage>

Yields credential pages for callers that want page-at-a-time rendering or explicit backpressure.

Example

for await (const page of oms.wallet.listAccessPages({ pageSize: 25 })) {
  console.log(page.grants)
}

revokeAccess

revokeAccess(params: { targetCredentialId: string }): Promise<void>

Permanently revokes a credential's access to this wallet. Cannot be undone.

Parameters

Name Type Description
targetCredentialId string The ID of the credential to revoke. Obtain from listAccess.

Example

const grants = await oms.wallet.listAccess()
const other = grants.find(g => !g.isCaller)
if (other) {
  await oms.wallet.revokeAccess({ targetCredentialId: other.credentialId })
}

IndexerClient

Accessed via oms.indexer. Queries on-chain balances and transaction history.

getBalances

getBalances(params: {
  walletAddress: string
  networks?: Network[]
  networkType?: 'MAINNETS' | 'TESTNETS' | 'ALL'
  contractAddresses?: string[]
  includeMetadata?: boolean
  omitPrices?: boolean
  tokenIds?: string[]
  contractStatus?: ContractVerificationStatus
  page?: TokenBalancesPage
}): Promise<BalancesResult>

Fetches native and token balances for a wallet. Pass networks to query explicit SDK network objects. If networks is omitted, the request defaults to networkType: 'MAINNETS'. The default request returns page 0 with up to 40 entries. includeMetadata defaults to true; token display data is returned on contractInfo and tokenMetadata, and ERC-20 decimals are available as contractInfo.decimals.

Parameters

Name Type Description
walletAddress string The wallet address whose balances to fetch. Use oms.wallet.walletAddress after checking it is defined.
networks Network[] Optional explicit networks to query. Use exported registry values such as Networks.polygon.
networkType 'MAINNETS' | 'TESTNETS' | 'ALL' Optional gateway network group when networks is omitted. Defaults to 'MAINNETS'.
contractAddresses string[] Optional token contract filter. Omit to query balances across contracts.
includeMetadata boolean Optional metadata flag. Defaults to true.
omitPrices boolean Optional price exclusion flag.
tokenIds string[] Optional token ID filter.
contractStatus ContractVerificationStatus Optional contract verification filter.
page TokenBalancesPage Optional pagination request. Defaults to { page: 0, pageSize: 40 }.

Returns Promise<BalancesResult> — see BalancesResult.

Example

const { walletAddress } = oms.wallet
if (!walletAddress) throw new Error('No active wallet session')

const result = await oms.indexer.getBalances({
  networks: [Networks.polygon],
  walletAddress,
  includeMetadata: true,
})

for (const b of result.nativeBalances) {
  console.log(b.symbol, b.balance)
}

for (const b of result.balances) {
  console.log(b.contractAddress, b.balance, b.tokenId)
}

getTransactionHistory

getTransactionHistory(params: {
  walletAddress: string
  networks?: Network[]
  networkType?: 'MAINNETS' | 'TESTNETS' | 'ALL'
  contractAddresses?: string[]
  transactionHashes?: string[]
  metaTransactionIds?: string[]
  fromBlock?: number
  toBlock?: number
  tokenId?: string
  includeMetadata?: boolean
  omitPrices?: boolean
  metadataOptions?: MetadataOptions
  page?: TokenBalancesPage
}): Promise<TransactionHistoryResult>

Fetches mined transaction history for a wallet. Pass networks to query explicit SDK network objects. If networks is omitted, the request defaults to networkType: 'MAINNETS'. includeMetadata defaults to true. Use metadataOptions to tune returned token and contract metadata.

Parameters

Name Type Description
walletAddress string The wallet address whose transaction history to fetch. Use oms.wallet.walletAddress after checking it is defined.
networks Network[] Optional explicit networks to query. Use exported registry values such as Networks.polygon.
networkType 'MAINNETS' | 'TESTNETS' | 'ALL' Optional network group when networks is omitted. Defaults to 'MAINNETS'.
contractAddresses string[] Optional token contract filter.
transactionHashes string[] Optional transaction hash filter.
metaTransactionIds string[] Optional meta-transaction ID filter.
fromBlock number Optional starting block number.
toBlock number Optional ending block number.
tokenId string Optional token ID filter.
includeMetadata boolean Optional metadata flag. Defaults to true.
omitPrices boolean Optional price exclusion flag.
metadataOptions MetadataOptions Optional metadata enrichment filters. See MetadataOptions.
page TokenBalancesPage Optional pagination request.

Returns Promise<TransactionHistoryResult> — see TransactionHistoryResult.

Errors

Public methods throw OmsSdkError subclasses for SDK-level failures.

class OmsSdkError extends Error {
  code: OmsSdkErrorCode
  operation?: string
  status?: number
  txnId?: string
  retryable?: boolean
  upstreamError?: OmsUpstreamError
  cause?: unknown
}
interface OmsUpstreamError {
  service: 'waas' | 'indexer'
  name?: string
  code?: number | string
  message?: string
  status?: number
}
type OmsSdkErrorCode =
  | 'OMS_HTTP_ERROR'
  | 'OMS_INVALID_RESPONSE'
  | 'OMS_REQUEST_FAILED'
  | 'OMS_AUTH_COMMITMENT_CONSUMED'
  | 'OMS_SESSION_MISSING'
  | 'OMS_SESSION_EXPIRED'
  | 'OMS_WALLET_SELECTION_STALE'
  | 'OMS_WALLET_SELECTION_UNAVAILABLE'
  | 'OMS_WALLET_SELECTION_IN_FLIGHT'
  | 'OMS_TRANSACTION_EXECUTION_UNCONFIRMED'
  | 'OMS_TRANSACTION_STATUS_LOOKUP_FAILED'
  | 'OMS_VALIDATION_ERROR'

OMS_AUTH_COMMITMENT_CONSUMED means the OTP/OIDC auth commitment has already been used. Restart the auth flow before retrying.

OMS_TRANSACTION_EXECUTION_UNCONFIRMED means transaction preparation succeeded, but the execute request failed before the SDK could confirm whether the transaction was submitted. The error includes txnId when available; do not blindly resend the same write solely because the upstream failure looked temporary.

OMS_TRANSACTION_STATUS_LOOKUP_FAILED means the transaction was submitted, but post-submit status polling failed. The error includes txnId and is retryable by checking status again with getTransactionStatus.

upstreamError is normalized diagnostic detail from a remote OMS service response or transport failure. Use the SDK-level code for application branching; use upstreamError for logging and service-specific troubleshooting.

retryable describes the failed SDK operation, not the whole user intent. For example, a retryable transaction status lookup failure means retry getTransactionStatus; it does not mean blindly resend the original transaction write.

Class Typical use
OmsSessionError Missing, expired, or stale wallet session.
OmsRequestError Network, fetch, or non-2xx HTTP failures.
OmsResponseError Invalid JSON or malformed API responses.
OmsTransactionError Transaction execution could not be confirmed or submitted transaction status polling failed; includes txnId when available.
OmsWalletSelectionError Manual wallet selection is stale, invalid, or already processing an action.
OmsValidationError SDK-side validation failures before a request is sent.

Use isOmsSdkError(err) or err instanceof OmsSdkError to branch on structured error fields.

Types

Network

interface Network {
  readonly id: number
  readonly name: string
  readonly nativeTokenSymbol: string
  readonly explorerUrl: string
  readonly displayName: string
}

A supported OMS network entry. The SDK exports Networks, supportedNetworks, findNetworkById(id), and findNetworkByName(name). name is the registry/routing slug for indexer URLs, while displayName is the user-facing label.

findNetworkById(id: number): Network | undefined
findNetworkByName(name: string): Network | undefined
Key id name displayName nativeTokenSymbol explorerUrl
Networks.mainnet 1 mainnet Ethereum ETH https://etherscan.io
Networks.sepolia 11155111 sepolia Sepolia ETH https://sepolia.etherscan.io
Networks.polygon 137 polygon Polygon POL https://polygonscan.com
Networks.amoy 80002 amoy Polygon Amoy POL https://amoy.polygonscan.com
Networks.arbitrum 42161 arbitrum Arbitrum ETH https://arbiscan.io
Networks.arbitrumSepolia 421614 arbitrum-sepolia Arbitrum Sepolia ETH https://sepolia.arbiscan.io
Networks.optimism 10 optimism Optimism ETH https://optimistic.etherscan.io
Networks.optimismSepolia 11155420 optimism-sepolia Optimism Sepolia ETH https://sepolia-optimism.etherscan.io
Networks.base 8453 base Base ETH https://basescan.org
Networks.baseSepolia 84532 base-sepolia Base Sepolia ETH https://sepolia.basescan.org
Networks.bsc 56 bsc BSC BNB https://bscscan.com
Networks.bscTestnet 97 bsc-testnet BSC Testnet BNB https://testnet.bscscan.com
Networks.arbitrumNova 42170 arbitrum-nova Arbitrum Nova ETH https://nova.arbiscan.io
Networks.avalanche 43114 avalanche Avalanche AVAX https://subnets.avax.network/c-chain
Networks.avalancheTestnet 43113 avalanche-testnet Avalanche Testnet AVAX https://subnets-test.avax.network/c-chain
Networks.katana 747474 katana Katana ETH https://katanascan.com

OmsAuthConfig

interface OmsAuthConfig {
  oidcProviders?: Record<string, OidcProviderConfig>
}
Field Type Description
oidcProviders Record<string, OidcProviderConfig> OIDC provider configurations addressable by provider key.

When auth is omitted, the SDK configures the built-in google provider. Passing auth replaces the configured provider set.

Use defineOmsAuthConfig to preserve typed custom OIDC provider keys:

const auth = defineOmsAuthConfig({
  oidcProviders: {
    custom: customOidcProvider,
  },
})

const oms = new OMSClient({
  publishableKey: 'your-publishable-key',
  auth,
})

OidcProviderConfig

type OidcProviderConfig = {
  clientId: string
  issuer: string
  authorizationUrl: string
  scopes?: string[]
  relayRedirectUri?: string
  authorizeParams?: Record<string, string>
}

Google can be configured with the googleOidcProvider helper:

// Uses the SDK default Google client id and relay redirect URI.
googleOidcProvider()

// Override defaults when needed.
googleOidcProvider({
  clientId: 'your-google-client-id',
  relayRedirectUri: 'http://localhost:8090/callback',
})

OIDC Provider Helpers

type OidcProviderName<Env> = string
type OidcProviderInput<Env> = OidcProviderName<Env> | OidcProviderConfig

interface GoogleOidcProviderParams {
  clientId?: string
  relayRedirectUri?: string
  scopes?: string[]
  authorizeParams?: Record<string, string>
}

const defaultOmsAuthConfig: OmsAuthConfig

OidcProviderName is narrowed from the configured auth.oidcProviders keys when OMSClient is constructed with defineOmsAuthConfig. googleOidcProvider(params) accepts GoogleOidcProviderParams and returns an OidcProviderConfig. defaultOmsAuthConfig contains the SDK's built-in Google provider configuration.

Auth Method Types

interface CompleteEmailAuthParams {
  code: string
  walletType?: WalletType
  walletSelection?: WalletSelectionBehavior
  sessionLifetimeSeconds?: number
}

interface CompleteEmailAuthResult {
  walletAddress: Address
  wallet: OmsWallet
  wallets: OmsWallet[]
  credential: WalletCredential
}

interface StartOidcRedirectAuthParams<Env> {
  provider: OidcProviderInput<Env>
  redirectUri: string
  walletType?: WalletType
  relayRedirectUri?: string
  authorizeParams?: Record<string, string>
  loginHint?: string
}

interface StartOidcRedirectAuthResult {
  url: string
  state: string
  challenge: string
}

interface CompleteOidcRedirectAuthParams {
  callbackUrl: string
  cleanUrl?: boolean
  replaceUrl?: (url: string) => void
  walletSelection?: WalletSelectionBehavior
  sessionLifetimeSeconds?: number
}

interface CompleteOidcRedirectAuthResult {
  walletAddress: Address
  wallet: OmsWallet
  wallets: OmsWallet[]
  credential: WalletCredential
}

interface SignInWithOidcRedirectParams<Env> {
  provider: OidcProviderInput<Env>
  redirectUri?: string
  walletType?: WalletType
  walletSelection?: WalletSelectionBehavior
  relayRedirectUri?: string
  authorizeParams?: Record<string, string>
  loginHint?: string
  sessionLifetimeSeconds?: number
  cleanUrl?: boolean
  currentUrl?: string
  assignUrl?: (url: string) => void
  replaceUrl?: (url: string) => void
}

Exported parameter and result interfaces for the email OTP and OIDC redirect methods documented above.

StorageManager

interface StorageManager {
  get(key: string): string | null
  set(key: string, value: string): void
  delete(key: string): void
}

Interface for wallet metadata storage. Implement this to use a custom backend. The SDK defaults to LocalStorageManager when browser localStorage is available and MemoryStorageManager otherwise.

Storage Helpers

class LocalStorageManager implements StorageManager
class SessionStorageManager implements StorageManager
class MemoryStorageManager implements StorageManager

function createDefaultStorage(): StorageManager

createDefaultStorage() returns LocalStorageManager when browser localStorage is available, otherwise MemoryStorageManager. OIDC redirect state defaults to SessionStorageManager when browser sessionStorage is available.

CredentialSigner

type CredentialSigningAlgorithm = 'ecdsa-p256k-eip191' | 'ecdsa-p256-sha256'

interface CredentialSigner {
  readonly signingAlgorithm: CredentialSigningAlgorithm
  credentialId(): Promise<string>
  nextNonce(): Promise<string>
  sign(preimage: string): Promise<string>
  hasCredential?(): Promise<boolean>
  clear?(): Promise<void>
}

Interface for request credential signing. The default implementation is WebCryptoP256CredentialSigner, which uses ecdsa-p256-sha256 and a non-extractable WebCrypto private key.

Credential Signing Helpers

class WebCryptoP256CredentialSigner implements CredentialSigner
class EthereumPrivateKeyCredentialSigner implements CredentialSigner

WebCryptoP256CredentialSigner is the browser default. EthereumPrivateKeyCredentialSigner signs credential requests with an EVM private key and is useful for Node.js or server-side usage where the caller provides key material directly.

Session Listener Types

type OMSClientSessionLoginType = 'email' | 'google-auth' | 'oidc'

interface OMSClientSessionState {
  walletAddress: Address | undefined
  expiresAt: string | undefined
  loginType: OMSClientSessionLoginType | undefined
  sessionEmail: string | undefined
}

interface OMSClientSessionExpiredEvent {
  session: OMSClientSessionState
  expiredAt: string
}

type OMSClientSessionExpiredListener = (
  event: OMSClientSessionExpiredEvent
) => void | Promise<void>

Session state and listener types used by session and onSessionExpired.

Signing and Validation Method Types

interface SignMessageParams {
  network: Network
  message: string
}

interface SignTypedDataParams {
  network: Network
  typedData: any
}

interface GetIdTokenParams {
  ttlSeconds?: number
  customClaims?: Record<string, unknown>
}

interface IsValidMessageSignatureParams {
  network?: Network
  walletAddress?: Address
  walletId?: string
  message: string
  signature: string
}

interface IsValidTypedDataSignatureParams {
  network?: Network
  walletAddress?: Address
  walletId?: string
  typedData: any
  signature: string
}

Exported parameter interfaces for signing, ID token, and signature validation methods.

OmsWallet

interface OmsWallet {
  id: string
  type: WalletType
  address: Address
  reference?: string
}

Wallet metadata returned by auth and wallet listing APIs.

PendingWalletSelection

interface PendingWalletSelection {
  walletType: WalletType
  wallets: OmsWallet[]
  credential: WalletCredential

  selectWallet(params: { walletId: string }): Promise<WalletActivationResult>
  createAndSelectWallet(params?: { reference?: string }): Promise<WalletActivationResult>
}

Returned by manual email or OIDC auth completion. The selection is bound to the verified auth flow and signer that created it. It can be used once to select one of the returned wallets or to create and select a new wallet of walletType.

WalletSelectionBehavior

type WalletSelectionBehavior = 'automatic' | 'manual'

Controls whether auth completion immediately activates a wallet or returns a PendingWalletSelection.

WalletCredential

interface WalletCredential {
  credentialId: string
  expiresAt: string
  isCaller: boolean
}
Field Type Description
credentialId string Unique identifier. Pass to revokeAccess to remove this credential.
expiresAt string ISO 8601 timestamp for credential expiry.
isCaller boolean true if this credential belongs to the current active session.

AccessGrant has the same shape and represents a credential with access to the active wallet.

AccessGrant

type AccessGrant = WalletCredential

ListAccessParams

interface ListAccessParams {
  pageSize?: number
}
Field Type Description
pageSize number Requested page size. The service applies its own default and maximum.

AccessGrantPage

interface AccessGrantPage {
  grants: AccessGrant[]
}
Field Type Description
grants AccessGrant[] Credentials yielded for this page.

WalletActivationResult

interface WalletActivationResult {
  walletAddress: Address
  wallet: OmsWallet
}

Returned when an existing wallet is selected or a new wallet is created and activated.

SendNativeTransactionParams

type SendNativeTransactionParams = {
  network: Network
  to: Address
  value: bigint        // required — amount in wei
  mode?: TransactionMode
  selectFeeOption?: FeeOptionSelector
  waitForStatus?: boolean
  statusPolling?: TransactionStatusPollingOptions
}

Used when sending a native token transfer. value is required and data/abi must not be set.

SendDataTransactionParams

type SendDataTransactionParams = {
  network: Network
  to: Address
  data: Hex            // required — pre-encoded calldata
  value?: bigint
  mode?: TransactionMode
  selectFeeOption?: FeeOptionSelector
  waitForStatus?: boolean
  statusPolling?: TransactionStatusPollingOptions
}

Used when sending a transaction with raw calldata. abi must not be set.

SendContractTransactionParams

type SendContractTransactionParams<
  abi extends Abi | readonly unknown[],
  functionName extends ContractFunctionName<abi> | undefined
> = {
  network: Network
  to: Address
  abi: abi
  functionName: functionName
  args?: ...           // inferred from abi + functionName
  value?: bigint
  mode?: TransactionMode
  selectFeeOption?: FeeOptionSelector
  waitForStatus?: boolean
  statusPolling?: TransactionStatusPollingOptions
}

Used for fully-typed ABI-encoded contract calls. abi and functionName are required; args types are inferred from the ABI. data must not be set. Calldata is encoded automatically using viem's encodeFunctionData.

SendTransactionResponse

type SendTransactionResponse = {
  txnId: string
  status: TransactionStatus
  txnHash?: string
}

txnHash is present once the transaction is published. If polling times out while the transaction is still pending, use txnId to check status later.

TransactionStatusResponse

interface TransactionStatusResponse {
  status: TransactionStatus
  txnHash?: string
}

Returned by getTransactionStatus.

TransactionStatusPollingOptions

type TransactionStatusPollingOptions = {
  timeoutMs?: number
  intervalMs?: number
  fastIntervalMs?: number
  fastPollCount?: number
}

Controls how sendTransaction polls transaction status after execute when waitForStatus is not false.

TransactionMode

enum TransactionMode {
  Native = 'native',
  Relayer = 'relayer'
}

Controls how the SDK prepares a wallet transaction. Transaction methods default to TransactionMode.Relayer.

TransactionStatus

enum TransactionStatus {
  Quoted = 'quoted',
  Pending = 'pending',
  Executed = 'executed',
  Failed = 'failed'
}

Returned in transaction execution and status responses.

FeeOptionSelector

type FeeOptionSelector = (
  feeOptions: FeeOptionWithBalance[]
) => FeeOptionSelection | undefined | Promise<FeeOptionSelection | undefined>

const FeeOptionSelector: {
  firstAvailable: FeeOptionSelector
}

When no selector is provided, the SDK uses the first required fee option, or no fee option for sponsored transactions. FeeOptionSelector.firstAvailable uses enriched balances to skip underfunded fee options and selects the first option the wallet can pay. For custom selectors, return option.selection to select that fee option.

FeeOption

interface FeeOption {
  token: {
    network: string
    name: string
    symbol: string
    type: string
    decimals?: number
    logoURL?: string
    contractAddress?: string
    tokenID?: string
  }
  value: string
  displayValue: string
}

A fee token option returned during transaction preparation. value is the token amount in base units.

FeeOptionSelection

interface FeeOptionSelection {
  token: string
}

The selector payload for a fee option. In custom selectors, return the selection field from FeeOptionWithBalance.

FeeOptionWithBalance

type FeeOptionWithBalance = {
  feeOption: FeeOption
  selection: FeeOptionSelection
  balance?: TokenBalance
  available?: string
  availableRaw?: string
  decimals?: number
}

Fee option plus the active wallet's indexer balance for that token, when the SDK can load it.

GetBalancesParams

interface GetBalancesParams {
  walletAddress: string
  networks?: Network[]
  networkType?: IndexerNetworkType
  contractAddresses?: string[]
  includeMetadata?: boolean
  omitPrices?: boolean
  tokenIds?: string[]
  contractStatus?: ContractVerificationStatus
  page?: TokenBalancesPage
}

Parameters for getBalances.

GetTransactionHistoryParams

interface GetTransactionHistoryParams {
  walletAddress: string
  networks?: Network[]
  networkType?: IndexerNetworkType
  contractAddresses?: string[]
  transactionHashes?: string[]
  metaTransactionIds?: string[]
  fromBlock?: number
  toBlock?: number
  tokenId?: string
  includeMetadata?: boolean
  omitPrices?: boolean
  metadataOptions?: MetadataOptions
  page?: TokenBalancesPage
}

Parameters for getTransactionHistory.

IndexerNetworkType

type IndexerNetworkType = 'MAINNETS' | 'TESTNETS' | 'ALL'

Network group used when explicit networks are not provided.

ContractVerificationStatus

type ContractVerificationStatus = 'VERIFIED' | 'UNVERIFIED' | 'ALL'

Optional contract verification filter for balance queries.

MetadataOptions

interface MetadataOptions {
  verifiedOnly?: boolean
  unverifiedOnly?: boolean
  includeContracts?: string[]
}

Options for transaction metadata enrichment. Use contractStatus on getBalances to filter balance queries by contract verification status; use metadataOptions on getTransactionHistory to tune metadata returned with transaction history.

Field Type Description
verifiedOnly boolean Request metadata for verified contracts only.
unverifiedOnly boolean Request metadata for unverified contracts only.
includeContracts string[] Limit metadata enrichment to specific contract addresses.

SortBy

interface SortBy {
  column: string
  order: 'DESC' | 'ASC'
}

Sort descriptor used in indexer pagination requests.

BalancesResult

interface BalancesResult {
  status: number
  page?: TokenBalancesPage
  nativeBalances: TokenBalance[]
  balances: TokenBalance[]
}
Field Type Description
status number Response status code.
page TokenBalancesPage Pagination metadata, if present.
nativeBalances TokenBalance[] Native token balances for the requested address.
balances TokenBalance[] Array of token balance entries for the requested address.

TransactionHistoryResult

interface TransactionHistoryResult {
  status: number
  page?: TokenBalancesPage
  transactions: Transaction[]
}
Field Type Description
status number Response status code.
page TokenBalancesPage Pagination metadata, if present.
transactions Transaction[] Flattened transaction entries across the requested networks.

Transaction

interface Transaction {
  txnHash: string
  blockNumber: number
  blockHash: string
  chainId: number
  metaTxnId?: string
  transfers?: TransactionTransfer[]
  timestamp: string
}

Indexer transaction entry returned by getTransactionHistory.

TransactionTransfer

interface TransactionTransfer {
  transferType?: string
  contractAddress?: string
  contractType?: string
  from?: string
  to?: string
  tokenIds?: string[]
  amounts?: string[]
  logIndex?: number
  amountsUSD?: string[]
  pricesUSD?: string[]
  contractInfo?: TokenContractInfo
  tokenMetadata?: Record<string, TokenMetadata>
}

Token or native transfer details associated with an indexer transaction entry.

TokenBalancesPage

interface TokenBalancesPage {
  page?: number
  column?: string
  pageSize?: number
  more?: boolean
  before?: unknown
  after?: unknown
  sort?: SortBy[]
}
Field Type Description
page number Current page index (zero-based).
column string Pagination column, when returned or requested.
pageSize number Number of entries per page.
more boolean true if additional pages are available.
before unknown Cursor before the current page, when returned.
after unknown Cursor after the current page, when returned.
sort SortBy[] Optional sort descriptors.

TokenBalance

interface TokenBalance {
  contractType?: string
  contractAddress?: string
  accountAddress?: string
  tokenId?: string
  name?: string
  symbol?: string
  balance?: string
  balanceUSD?: string
  priceUSD?: string
  priceUpdatedAt?: string
  blockHash?: string
  blockNumber?: number
  chainId?: number
  uniqueCollectibles?: string
  isSummary?: boolean
  contractInfo?: TokenContractInfo
  tokenMetadata?: TokenMetadata
}
Field Type Description
contractType string Token standard, e.g. "ERC20", "ERC721", "ERC1155".
contractAddress string Address of the token contract.
accountAddress string Wallet address this balance belongs to.
tokenId string For ERC-721/ERC-1155 tokens, the token ID.
name string Token name, when returned directly on the balance row.
symbol string Token symbol, when returned directly on the balance row.
balance string Balance in the token's smallest denomination.
balanceUSD string USD value when returned by the Indexer.
priceUSD string Token price in USD when returned by the Indexer.
priceUpdatedAt string Timestamp for the returned USD price.
blockHash string Block hash at which this balance was recorded.
blockNumber number Block number at which this balance was recorded.
chainId number Numeric chain ID.
uniqueCollectibles string Number of unique collectibles represented by a summary row.
isSummary boolean Whether the row represents an aggregated collection summary.
contractInfo TokenContractInfo Contract display metadata. ERC-20 decimals are exposed as contractInfo.decimals.
tokenMetadata TokenMetadata Token-level metadata for NFT/collection entries when returned.

TokenContractInfo

interface TokenContractInfo {
  chainId?: number
  address?: string
  source?: string
  name?: string
  type?: string
  symbol?: string
  decimals?: number
  logoURI?: string
  deployed?: boolean
  bytecodeHash?: string
  extensions?: Record<string, unknown>
  updatedAt?: string
  queuedAt?: string | null
  status?: string
}

Contract-level metadata returned by the Indexer when includeMetadata is true.

TokenMetadata

interface TokenMetadata {
  chainId?: number
  contractAddress?: string
  tokenId?: string
  source?: string
  name?: string
  description?: string
  image?: string
  video?: string
  audio?: string
  properties?: Record<string, unknown>
  attributes?: Record<string, unknown>[]
  image_data?: string
  external_url?: string
  background_color?: string
  animation_url?: string
  decimals?: number
  updatedAt?: string
  assets?: TokenMetadataAsset[]
  status?: string
  queuedAt?: string | null
  lastFetched?: string
}

Token-level metadata returned by the Indexer when available.

TokenMetadataAsset

interface TokenMetadataAsset {
  id?: number
  collectionId?: number
  tokenId?: string
  url?: string
  metadataField?: string
  name?: string
  filesize?: number
  mimeType?: string
  width?: number
  height?: number
  updatedAt?: string
}

Media asset metadata associated with token metadata when returned.

AbiArg

interface AbiArg {
  type: string
  value: any
}

A loosely-typed ABI argument used by callContract. For fully-typed encoding, use the ABI overload of sendTransaction instead.

Field Type Description
type string Solidity type string, e.g. "address", "uint256", "bytes32", "bool".
value any The argument value. Use a string for large integers to avoid precision loss.

WalletType

enum WalletType {
  Ethereum = 'ethereum'
}

Identifies the wallet type to load or create. Passed as the optional walletType parameter to completeEmailAuth. Defaults to WalletType.Ethereum.