@pollar/react

@pollar 0.11.x. This page documents the 0.11 release line, which talks to SDK API v2. The current release is 0.12, documented under Latest. On 0.11.x the ramp methods answer 410 SDK_RAMPS_MOVED_TO_V3: ramps need 0.12. To move, read the 0.11 -> 0.12 upgrade notes.

React hooks and pre-built UI components for Pollar, for Stellar and Solana applications. Built on top of @pollar/core.

The modals are multichain: Send, Receive, Wallet balance, Enabled assets and Transaction history carry a network picker on an app with more than one chain, and each scopes its rows to the selected chain (Solana rows link to explorer.solana.com and show fees in lamports). Swap and Earn are Stellar modals. See Chain Support.

Version: 0.11.5

npm install @pollar/react

<PollarProvider>

Wraps your application root. Required for all hooks and components to work. Internally renders every Pollar modal — login, transaction, send, receive, KYC, ramp, tx history, wallet balance, enabled-assets, swap, earn, sessions, and distribution-rules — so you do not need to mount them manually.

import { PollarProvider } from '@pollar/react';

<PollarProvider
  client={{ apiKey: 'pub_testnet_xxxxxxxxxxxxxxxxxxxx' }}
>
  <App />
</PollarProvider>

Props:

To register wallet-login providers (Stellar Wallets Kit, Privy), put them on client.walletAdapters, not on this component. See Wallet Adapters.

PollarClientConfig:

Every other PollarClientConfig option (walletAdapters, cosignManual, loginTimeoutMs, storage, passkey, ...) is documented in @pollar/core.

usePollar()

The primary hook. Provides access to all Pollar functionality from a single import. Must be used inside <PollarProvider>.

'use client';
import { usePollar } from '@pollar/react';

function MyComponent() {
  const {
    isAuthenticated,
    verified,
    wallet,
    login,
    logout,
    buildTx,
    signAndSubmitTx,
    signTx,
    submitTx,
    buildAndSignAndSubmitTx,
    runTx,
    tx,
    txHistory,
    network,
    setNetwork,
    walletBalance,
    refreshWalletBalance,
    enabledAssets,
    refreshAssets,
    setTrustline,
    getSwapConfig,
    getSwapTokens,
    getSwapQuote,
    swap,
    getEarnProviders,
    getEarnOpportunities,
    getEarnPosition,
    earnDeposit,
    earnWithdraw,
    getClient,
    openLoginModal,
    openTxModal,
    openKycModal,
    openRampModal,
    openTxHistoryModal,
    openWalletBalanceModal,
    openSendModal,
    openReceiveModal,
    openEnabledAssetsModal,
    openSwapModal,
    openEarnModal,
    openSessionsModal,
    openDistributionRulesModal,
    sessions,
    appConfig,
    styles,
  } = usePollar();
}

Authentication

Wallets per chain

const { wallets } = usePollar();
const solana = wallets.find((w) => w.chain === 'SOLANA');

See useChains() for the app's chain order and the primary chain, and walletNotReadyReason(wallet, chain) for the message to show while a Stellar account is still being created.

Co-signed wallets and confirmations

Under the default confirmation: 'auto' a co-signed wallet behaves like a custodial one from the app's point of view: the device verifies and votes, and runTx resolves to success. See Co-signed wallets in @pollar/core and useCosign() for a custom approval UI.

App config

PollarLoginOptions:

Transactions

The transaction modal opens automatically when buildTx is called. See @pollar/core for TransactionState step details and the per-call BuildOutcome / SignOutcome / SubmitOutcome return types.

Network

Wallet Balance

For an arbitrary public key / network, use getClient().getWalletBalance(publicKey) from @pollar/core.

Enabled assets & trustlines

Swap

Earn

Transaction History

KYC

Without corridorId or providerId the modal walks the app's own KYC steps, as configured in the dashboard.

Ramps

Utilities

Modal entry points

All Pollar modals are mounted inside <PollarProvider> and controlled programmatically:

Hooks

useChains()

The chains the app serves and the user holds a wallet on, in the order configured under Chains. Drive every chain selector from this, not from wallets alone: a chain can be enabled before this user is provisioned on it.

import { useChains, ChainSelect } from '@pollar/react';

const { chains, primaryChain, primaryAddress, ready } = useChains();
const [chain, setChain] = useState(primaryChain);

if (!ready) return null;
<ChainSelect value={chain} options={chains} onChange={setChain} />

Helpers exported alongside: chainsOf(wallets, order?), addressForChain(wallets, chain), resolveChain(chain) (pre-multichain records are Stellar), and walletNotReadyReason(wallet, chain), which returns the message to show while a Stellar account is CREATING or FAILED, and null on every other chain.

useCosign()

The user's side of a Turnkey co-signed wallet, for an app that renders its own confirmation UI instead of <CosignModal>. Subscribes to the client's co-sign store and loads the pending requests once on mount.

createPollarAdapterHook(key)

Builds a hook over a transaction adapter registered through the adapters prop (for example @pollar/accesly-adapter): each adapter method becomes (params) => Promise<SubmitOutcome> that builds through the adapter and then calls signAndSubmitTx.

Components

<WalletButton>

Pre-built button that handles the complete authentication flow. When logged out, opens the login modal. When logged in, shows the wallet address with a dropdown for balance, transaction history, and logout.

Signed in without a wallet, it shows No wallet with Create wallet, active sessions and logout. For an app whose wallet creation is Never it shows Signed in without Create wallet.

import { WalletButton } from '@pollar/react';

<WalletButton />

No props required. Appearance comes from your remote dashboard configuration (or the appConfig override passed to <PollarProvider>), exposed as styles on usePollar(). To override colors and corners from your own CSS, see Theming.

<KycModal>

Pre-built KYC verification modal. Can be rendered directly when you need more control than openKycModal() provides.

import { KycModal } from '@pollar/react';

<KycModal
  onClose={() => setOpen(false)}
  country="US"
  level="basic"
  onApproved={() => console.log('KYC approved')}
/>

<KycStatus>

A display-only badge for a KYC status value. It fetches nothing: pass the status you read from getKycStatus().

import { KycStatus } from '@pollar/react';

<KycStatus status={status} />

<RequirementFormModal>

One FORM requirement step of a ramp route. Renders the form the backend names, prefilled with the user's previous answers, and stores the answers encrypted. <RampWidget> opens it by itself; render it directly when you build your own route list from the quote's requirementsRequired.

import { RequirementFormModal } from '@pollar/react';

<RequirementFormModal
  formId={step.optionId}
  progress={{ position: step.completed + 1, total: step.total }}
  onClose={() => setOpen(false)}
  onSubmitted={() => requote()}
/>

A 422 KYC_FORM_INVALID_ANSWERS is shown per field; numbers and dates are checked locally before the request.

<RegistryCheckModal>

One REGISTRY_CHECK step (SEGIP, the Bolivian civil registry, through Stereum). Shows the user's verified identity prefilled and read-only; only the surname split and the CI complement can be edited. A check the registry did not confirm is held for review and the modal shows that state with nothing to retry.

import { RegistryCheckModal } from '@pollar/react';

<RegistryCheckModal
  optionId={step.optionId}
  progress={{ position: step.completed + 1, total: step.total }}
  onClose={() => setOpen(false)}
  onApproved={() => requote()}
/>

prefill.applies === false (the document is not one the registry checks) shows a notice and only lets the user close. A 409 KYC_REGISTRY_IDENTITY_REQUIRED means the KYC step before it is not complete.

<ProviderRegistrationModal>

One PROVIDER_REGISTRATION step. Lists what the ramp provider receives (identity, form answers, registry validation) and registers the user with it when they consent. A user already registered is passed through at once.

import { ProviderRegistrationModal } from '@pollar/react';

<ProviderRegistrationModal
  corridorId={step.corridorId}
  progress={{ position: step.completed + 1, total: step.total }}
  onClose={() => setOpen(false)}
  onRegistered={() => requote()}
/>

A 409 KYC_REGISTRATION_STEPS_PENDING means an earlier step is still open; a 422 KYC_REGISTRATION_MISSING_DATA lists the fields the identity or the forms lack.

<CardModal>

The Cards flow: provider steps (KYC, forms, registry check, provider registration), the provider's own KYC form with terms, verification polling, issuing, the card face with limit / available / to pay, recent activity, Reveal (decrypted on the device, auto-hidden after 30 s) and Add funds (from the user's Stellar wallet, shown as "Step n of 4" until credited, or a deposit address for another wallet).

import { CardModal } from '@pollar/react';

<CardModal onClose={() => setOpen(false)} />

Headless: the card methods on PollarClient (Cards).

<CosignModal>

The approval prompt of a Turnkey co-signed wallet. It verifies each request against Turnkey before enabling Approve, so the user only confirms a transaction the device checked itself. The provider opens it by itself when a request arrives; render it yourself only to control placement.

import { CosignModal } from '@pollar/react';

<CosignModal onClose={() => setOpen(false)} />

<RampWidget>

Pre-built fiat on/off-ramp widget with support for on-ramp (fiat → crypto) and off-ramp (crypto → fiat) flows.

import { RampWidget } from '@pollar/react';

<RampWidget onClose={() => setOpen(false)} />

<WalletBalanceModal>

Displays the token balances of the authenticated wallet with a manual refresh option.

import { WalletBalanceModal } from '@pollar/react';

<WalletBalanceModal onClose={() => setOpen(false)} />

Template components

Template components handle rendering only — they receive all data and callbacks as props and contain no internal logic. Use them to build fully custom UI while reusing Pollar's layout and visual structure.

Some template props are required because the live modals need them: SendModalTemplateProps.onMax / onPaste, SwapModalTemplateProps.onReverse / onMax, SessionsModalTemplateProps.revokeError, RampWidgetTemplateProps.kycRequired / onVerifyRoute. WalletButtonTemplateProps takes theme, accentColor and an optional styleOverrides, like the modal templates. The Send, Receive and WalletButton templates take an optional notReadyReason (from walletNotReadyReason), and the ramp template an optional onboardingStatus.

Live (non-template) modal components are also exported for direct rendering: SendModal, SwapModal, EarnModal, CardModal, CosignModal, ReceiveModal, EnabledAssetsModal, WalletBalanceModal, SessionsModal, DistributionRulesModal, KycModal, RequirementFormModal, RegistryCheckModal, ProviderRegistrationModal, plus KycStatus, RouteDisplay, ChainSelect and TxStatusView. Each live modal takes onClose.

Styling helpers: buildModalCssVars(theme, accentColor, overrides?, variant?), modalChrome(styles), readableTextOn(background) and the ModalStyleOverrides type (backgroundColor, textColor, buttonColor, modalBorderRadius, buttonBorderRadius). The CSS variables they feed are listed in Theming. Passkeys: browserPasskeyCeremony and browserPasskeySigner are the WebAuthn implementations the provider installs on the client.

Import the corresponding *Props type for full type safety:

import {
  TransactionModalTemplate,
  type TransactionModalTemplateProps,
  WalletBalanceModalTemplate,
  type WalletBalanceModalTemplateProps,
} from '@pollar/react';

Types

import type {
  PollarConfig,
  PollarStyles,
  LoginButtonProps,
  AuthModalProps,
  KycStep,
  RampStep,
  TransactionModalTemplateProps,
  WalletBalanceModalTemplateProps,
  // re-exported from @pollar/core so you can author custom login providers
  PollarAuthProvider,
  AuthProviderContext,
} from '@pollar/react';

Core types such as WalletInfo, TransactionState, TxHistoryState, EnabledAssetsState, WalletBalanceContent, SwapQuote, EarnOpportunity, PollarLoginOptions, StellarNetwork, and WalletType are imported directly from @pollar/core.