Use the TypeScript SDK with wagmi - Polygon Developer Docs

@polygonlabs/oms-wallet-wagmi-connector adapts the stateful wallet client to wagmi. It does not authenticate users or render auth UI. Authenticate and activate a wallet with @polygonlabs/oms-wallet, then connect that active address to wagmi. The connector does not wrap omsWallet.indexer. Continue to call the independent indexer client directly for public balance and history reads.

Install

pnpm add @polygonlabs/oms-wallet @polygonlabs/oms-wallet-wagmi-connector wagmi @wagmi/core viem @tanstack/react-query

Configure both network models

Wagmi Chain definitions provide RPC transports. OMS Network values select supported wallet API networks. They represent the same chains but are different types.

import {
  FeeOptionSelector,
  Networks,
  OMSWallet,
} from '@polygonlabs/oms-wallet'
import { omsWalletConnector } from '@polygonlabs/oms-wallet-wagmi-connector'
import { createConfig, http } from 'wagmi'
import { polygon, polygonAmoy } from 'wagmi/chains'

export const omsWallet = new OMSWallet({
  publishableKey: 'YOUR_PUBLISHABLE_KEY',
})

export const omsConnector = omsWalletConnector({
  omsWallet,
  initialChainId: polygonAmoy.id,
  networks: [Networks.amoy, Networks.polygon],
  transactionOptions: {
    selectFeeOption: FeeOptionSelector.firstAvailable,
  },
})

export const wagmiConfig = createConfig({
  chains: [polygonAmoy, polygon],
  connectors: [omsConnector],
  transports: {
    [polygonAmoy.id]: http(),
    [polygon.id]: http(),
  },
})

declare module 'wagmi' {
  interface Register {
    config: typeof wagmiConfig
  }
}

When networks is omitted, the connector accepts every value in the SDK’s closed Networks registry. Pass it to intentionally narrow the connector. initialChainId and later chain switches must exist in both the wagmi chain list and the connector’s OMS network list.

Add React providers

import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import type { ReactNode } from 'react'
import { WagmiProvider } from 'wagmi'
import { wagmiConfig } from './wagmiConfig'

const queryClient = new QueryClient()

export function Providers({ children }: { children: ReactNode }) {
  return (
    <WagmiProvider config={wagmiConfig}>
      <QueryClientProvider client={queryClient}>
        {children}
      </QueryClientProvider>
    </WagmiProvider>
  )
}

Authenticate before connecting

Use the SDK’s normal browser redirect path, then call wagmi connect only after callback completion or session restoration has produced walletAddress.

import { connect } from '@wagmi/core'
import { OmsRelayOidcProviders } from '@polygonlabs/oms-wallet'
import { polygonAmoy } from 'wagmi/chains'
import {
  omsConnector,
  omsWallet,
  wagmiConfig,
} from './wagmiConfig'

await omsWallet.wallet.completeOidcRedirectAuth()

if (omsWallet.wallet.walletAddress) {
  await connect(wagmiConfig, {
    connector: omsConnector,
    chainId: polygonAmoy.id,
  })
}

// Run this from the user's Google sign-in action.
await omsWallet.wallet.signInWithOidcRedirect({
  provider: OmsRelayOidcProviders.google,
})

The connector rejects connect when the SDK has no active wallet. Email OTP and provider ID-token auth work the same way: finish automatic wallet selection, or finish a returned PendingWalletSelection, before connecting. See authentication.

Disconnect and sign out

Wagmi disconnect changes connector state only. It leaves the OMS Wallet session active and records a manual disconnect so wagmi will not automatically reconnect it after refresh. A later explicit connect clears that marker. To end local application state in both layers:

import { disconnect } from '@wagmi/core'
import { omsWallet, wagmiConfig } from './wagmiConfig'

await disconnect(wagmiConfig)
await omsWallet.wallet.signOut()

SDK signOut is local-only and does not revoke server-side access grants. Manage revocation separately as described in sessions and access. Session expiry causes the connector to emit a disconnect event.

Apply OMS fee selection

Wagmi transaction parameters have no OMS fee selector field. Configure transactionOptions statically, as in the initial setup, or return options per transaction.

const omsConnector = omsWalletConnector({
  omsWallet,
  transactionOptions: ({ chainId, request }) => ({
    selectFeeOption: async (options) => {
      const affordableUsdc = options.find((option) =>
        option.feeOption.token.symbol === 'USDC' &&
        option.availableRaw !== undefined &&
        BigInt(option.availableRaw) >= BigInt(option.feeOption.value),
      )

      return affordableUsdc?.selection
    },
  }),
})

Testnet transactions are sponsored and skip the selector. On mainnet, the preparation response reports sponsorship or returns fee options. For an unsponsored transaction, no selector means the SDK uses the first returned fee option without checking affordability. FeeOptionSelector.firstAvailable instead uses optional indexer balance data and picks the first option whose raw balance covers the fee; it fails selection if no option qualifies. A React fee picker can return a promise from selectFeeOption and resolve it with the chosen option’s selection. Keep this bridge in application state rather than trying to add fee fields to wagmi’s transaction request.

Send with wagmi

import { sendTransaction } from '@wagmi/core'
import { parseUnits } from 'viem'
import { polygonAmoy } from 'wagmi/chains'
import { wagmiConfig } from './wagmiConfig'

const hash = await sendTransaction(wagmiConfig, {
  chainId: polygonAmoy.id,
  to: '0x1111111111111111111111111111111111111111',
  value: parseUnits('0.001', 18),
})

The connector always sets waitForStatus: true because wagmi sendTransaction must return an EVM transaction hash. waitForStatus: false is rejected. If the SDK result has no hash after status waiting, the connector throws and includes the OMS txnId in the error message when available. Use omsWallet.wallet.sendTransaction directly when your application needs to continue with txnId before a hash exists. The connector supports from, to, value, data, and chainId. It requires to, so recipient-free contract deployment is unavailable through this adapter. It ignores wallet-managed gas, fee, nonce, transaction type, and access-list fields; unknown fields are rejected.

Use the connector provider only for wallet methods

The provider supports account and chain state, chain switching, personal_sign, eth_signTypedData_v4, transaction submission, and wallet_getCapabilities. It does not provide general JSON-RPC reads such as eth_call, eth_getBalance, eth_estimateGas, receipts, code, nonce, or block queries. Use wagmi public transports for RPC reads and omsWallet.indexer for OMS indexer reads. personal_sign accepts text and hex that decodes to UTF-8 text. Raw byte messages, eth_sign, and legacy eth_signTypedData are not supported. wallet_getCapabilities currently returns an empty object.

​Install

​Configure both network models

​Add React providers

​Authenticate before connecting

​Disconnect and sign out

​Apply OMS fee selection

​Send with wagmi

​Use the connector provider only for wallet methods