React Native SDK Authentication - Polygon Developer Docs

The React Native SDK supports email OTP and Google sign-in through OIDC ID-token auth or authorization-code redirect auth. Authentication returns an active wallet by default. Use manual wallet selection when your app should present wallet choices.

Create The Client

Create OMSClient before using authentication, wallet, signing, transaction, balance, or access APIs.

import { OMSClient } from '@0xsequence/oms-react-native-sdk'

const oms = new OMSClient({
  publishableKey: 'YOUR_PUBLISHABLE_KEY',
})

Parameters

Parameter	Type	Description
`publishableKey`	`string`	Publishable key. The SDK selects the matching OMS Wallet environment from this key.

Returns Returns an OMSClient instance with wallet, indexer, and supportedNetworks.

Start Email Auth

Send a one-time code to the user’s email address.

await oms.wallet.startEmailAuth('user@example.com')

Parameters

Parameter	Type	Description
`email`	`string`	Email address that receives the one-time code.

Returns Returns Promise<void>.

Complete Email Auth

Complete the flow with the code entered by the user. Automatic mode returns an active wallet when possible.

const result = await oms.wallet.completeEmailAuth({ code: '123456' })

if (result.type === 'walletSelected') {
  console.log('Wallet address:', result.walletAddress)
  console.log('Wallet ID:', result.wallet.id)
}

Use manual wallet selection when the app needs to choose between wallets before activating one.

const result = await oms.wallet.completeEmailAuth({
  code: '123456',
  walletSelection: 'manual',
  walletType: 'ethereum',
})

if (result.type === 'walletSelection') {
  await result.pendingSelection.createAndSelectWallet('main')
}

Parameters

Parameter	Type	Description
`code`	`string`	One-time code entered by the user.
`walletSelection`	`'automatic'` or `'manual'`	Defaults to `'automatic'`. Use `'manual'` to receive a pending wallet selection.
`walletType`	`'ethereum'` or undefined	Optional wallet type. Defaults to `ethereum`.
`sessionLifetimeSeconds`	`number`, `null`, or undefined	Optional requested wallet API session lifetime in seconds. Defaults to one week.

Returns Returns Promise<OmsCompleteAuthResult>.

Field	Type	Description
`type`	`'walletSelected'` or `'walletSelection'`	Indicates whether a wallet was activated or manual selection is pending.
`walletAddress`	`string` or `null`	Active OMS Wallet address in automatic mode.
`wallet`	`OmsWallet` or `null`	Selected or created wallet in automatic mode.
`wallets`	`OmsWallet[]`	Wallets returned by auth completion.
`credential`	`OmsCredentialInfo`	Credential added by auth completion.
`pendingSelection`	`OmsPendingWalletSelection` or undefined	Manual wallet selection helper.

Authenticate with a Google ID token.

const result = await oms.wallet.signInWithOidcIdToken({
  idToken: 'OIDC_ID_TOKEN',
  issuer: 'https://accounts.google.com',
  audience: 'YOUR_WEB_CLIENT_ID',
  walletSelection: 'automatic',
  walletType: 'ethereum',
})

if (result.type === 'walletSelected') {
  console.log('Wallet address:', result.walletAddress)
}

Parameters

Parameter	Type	Description
`idToken`	`string`	Google ID token issued to the app.
`issuer`	`string`	Expected token issuer, such as `https://accounts.google.com`.
`audience`	`string`	Expected token audience, such as the app’s Google client ID.
`walletSelection`	`'automatic'` or `'manual'`	Defaults to `'automatic'`. Use `'manual'` to receive a pending wallet selection.
`walletType`	`'ethereum'` or undefined	Optional wallet type. Defaults to `ethereum`.
`sessionLifetimeSeconds`	`number`, `null`, or undefined	Optional requested wallet API session lifetime in seconds. Defaults to one week.

Returns Returns Promise<OmsCompleteAuthResult>.

OIDC Provider Config

Use OidcProviders.google to build the provider config for Google redirect auth.

import { OidcProviders } from '@0xsequence/oms-react-native-sdk'

const provider = OidcProviders.google({
  clientId: 'YOUR_WEB_CLIENT_ID',
})

Parameters

Parameter	Type	Description
`clientId`	`string` or undefined	Google OAuth client ID. Defaults to the SDK’s configured Google client ID.
`scopes`	`string[]` or undefined	OAuth scopes. Defaults to `openid`, `email`, and `profile`.
`authorizeParams`	`Record<string, string>` or undefined	Extra authorization query parameters.

Returns Returns OidcProviderConfig.

Start OIDC Redirect Auth

Start a Google authorization-code PKCE flow. Apps own browser opening and deep-link handling. Open the authorization URL in the platform system auth browser, then pass the resulting app-link URL to handleOidcRedirectCallback.

import { OidcProviders } from '@0xsequence/oms-react-native-sdk'

const started = await oms.wallet.startOidcRedirectAuth({
  provider: OidcProviders.google({ clientId: 'YOUR_WEB_CLIENT_ID' }),
  redirectUri: 'yourapp://oauth/callback',
  walletType: 'ethereum',
})

console.log('Open this URL with system auth UI:', started.authorizationUrl)

// When the app receives the callback URL from its deep-link handler:
const result = await oms.wallet.handleOidcRedirectCallback({
  callbackUrl: 'yourapp://oauth/callback?code=CODE&state=STATE',
})

Parameters

Parameter	Type	Description
`provider`	`OidcProviderConfig`	Google provider config returned by `OidcProviders.google`.
`redirectUri`	`string`	App callback URL that receives the provider redirect. Configure this URL scheme or app link in your native app.
`walletType`	`'ethereum'` or undefined	Optional wallet type. Defaults to `ethereum`.
`authorizeParams`	`Record<string, string>` or `null`	Extra authorization query parameters.
`loginHint`	`string`, `null`, or undefined	Optional Google `login_hint`. When omitted for Google, the SDK can reuse the previous session email.

Returns Returns Promise<OmsStartOidcRedirectAuthResult>.

Field	Type	Description
`authorizationUrl`	`string`	Provider authorization URL to open with system auth UI.
`state`	`string`	OIDC state value stored for callback validation.
`challenge`	`string`	Wallet auth challenge used in the OIDC request.

Handle OIDC Redirect Callback

Complete redirect auth after the provider sends the user back to your app.

const result = await oms.wallet.handleOidcRedirectCallback({
  callbackUrl: 'com.example.app:/oauth/callback?code=CODE&state=STATE',
  walletSelection: 'manual',
})

if (result.type === 'walletSelection') {
  await result.pendingSelection.createAndSelectWallet('main')
}

Parameters

Parameter	Type	Description
`callbackUrl`	`string`, `null`, or undefined	Full callback URL containing OIDC `code` and `state`.
`walletSelection`	`'automatic'` or `'manual'`	Defaults to `'automatic'`. Use `'manual'` to receive a pending wallet selection.
`sessionLifetimeSeconds`	`number`, `null`, or undefined	Optional requested wallet API session lifetime in seconds. Defaults to one week.

Returns Returns Promise<OmsOidcRedirectAuthResult>.

Result `type`	Description
`completed`	Redirect auth completed and returned an active wallet.
`walletSelection`	Auth completed and manual wallet selection is pending.
`notOidcRedirectCallback`	The URL was not an OIDC redirect callback for this SDK.
`noPendingAuth`	There is no pending redirect auth flow to complete.
`failed`	Redirect auth failed and includes a `message`.

List Wallets

List wallets available to the authenticated credential.

const wallets = await oms.wallet.listWallets()

for (const wallet of wallets) {
  console.log(wallet.id, wallet.type, wallet.address)
}

Parameters Takes no parameters. Returns Returns Promise<OmsWallet[]>.

Use Wallet

Activate an existing wallet by server-side wallet ID.

const result = await oms.wallet.useWallet('wallet-id')

console.log('Wallet address:', result.walletAddress)

Parameters

Parameter	Type	Description
`walletId`	`string`	Wallet ID returned by auth completion or `listWallets`.

Returns Returns Promise<OmsWalletActivationResult>.

Create Wallet

Create and activate a new wallet for the authenticated user.

const result = await oms.wallet.createWallet({
  walletType: 'ethereum',
  reference: 'main',
})

console.log('New wallet:', result.walletAddress)

Parameters

Parameter	Type	Description
`walletType`	`'ethereum'` or undefined	Wallet type to create. Defaults to `ethereum`.
`reference`	`string`, `null`, or undefined	Optional app-defined wallet reference.

Returns Returns Promise<OmsWalletActivationResult>.

​Create The Client

​Start Email Auth

​Complete Email Auth

​Sign In With OIDC ID Token

​OIDC Provider Config

​Start OIDC Redirect Auth

​Handle OIDC Redirect Callback

​List Wallets

​Use Wallet

​Create Wallet

Create The Client

Start Email Auth

Complete Email Auth

Sign In With OIDC ID Token

OIDC Provider Config

Start OIDC Redirect Auth

Handle OIDC Redirect Callback

List Wallets

Use Wallet

Create Wallet