@pollar/react

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.12.0. It requires @pollar/core@^0.12.0 and talks to SDK API v3. For 0.11.x, see the 0.11 reference.

npm install @pollar/react @pollar/core

<PollarProvider>

Wraps your application root. Required for all hooks and components to work. It renders every Pollar modal itself, so you do not mount them: login, transaction, send, receive, KYC, ramp, transaction history, wallet balance, enabled assets, swap, earn, cards, sessions, distribution rules, co-sign approval, signature confirmation, wallet recovery and custody migration.

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

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

Props:

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

PollarClientConfig:

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

Signature confirmation

By default every signing call waits for the user: the provider shows the transaction in <ConfirmModal> and signs only when the user confirms, whatever the wallet's custody.

The app's policy is set in the dashboard, under Wallets > Wallet settings > Signature confirmation (guide): always ask, ask once and then sign for a window (5 minutes and 50 USD by default), or never ask. With confirmation unset the SDK follows the dashboard. When you set it, the stricter of the two applies: 'auto' in code skips the prompt only if the dashboard says never ask too.

• Inside a window, a signature signs without asking while the USD total of the window stays within maxUsd. Only a payment the SDK builds itself (sendPayment, runTx('payment', ...)) has a value it can read; any other signature (a raw signTx, a swap, a contract call) asks, and so does an asset with no price. The window closes on logout.
• A ramp leg always asks, whatever the policy.
• A declined prompt ends the call with SDK_CONFIRMATION_DECLINED; nothing was signed.

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,
    wallets,
    hasWallet,
    createWallet,
    login,
    logout,
    buildTx,
    signAndSubmitTx,
    signTx,
    submitTx,
    buildAndSignAndSubmitTx,
    runTx,
    sendPayment,
    tx,
    txHistory,
    network,
    setNetwork,
    walletBalance,
    refreshWalletBalance,
    enabledAssets,
    refreshAssets,
    setTrustline,
    getSwapConfig,
    getSwapTokens,
    getSwapQuote,
    swap,
    getEarnProviders,
    getEarnOpportunities,
    getEarnPosition,
    earnDeposit,
    earnWithdraw,
    cosign,
    confirmations,
    recovery,
    recoveryLocked,
    custodyMigration,
    getClient,
    openLoginModal,
    openTxModal,
    openKycModal,
    openRampModal,
    openRecoveryModal,
    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, recovery and confirmations

These fields matter for an app whose wallets live in Turnkey (co-signed or self-custody). See Co-signed Wallets.

Every co-signed transaction asks the user, wallet setup included (account creation, trustlines, a new chain): <CosignModal> opens for it. Each request is verified on the device before Approve is enabled. See useCosign() for a custom approval UI, and Passkeys and wallet recovery for the recovery flow.

App config

PollarLoginOptions:

Transactions

The transaction modal opens automatically when buildTx is called. Each signing call first passes the signature confirmation. 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

The widget runs the v3 ramps API: a ramp is an order of one or more legs (the provider, a swap, a bridge) that Pollar runs server-side. See Ramps and the ramp methods in @pollar/core for a headless flow.

Utilities

Modal entry points

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

<ConfirmModal> and <CustodyMigrationModal> have no entry point: the provider opens them when a signature waits for the user and when the server asks for the move.

Hooks

useChains()

The chains the app serves and the user holds a wallet on, in the order configured under Wallets > Wallet settings (guide). 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 wallet, for an app that renders its own approval 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: each adapter method becomes (params) => Promise<SubmitOutcome> that builds through the adapter and then calls signAndSubmitTx.

A method may instead return { unsignedAuthEntry, validUntilLedger, complete } when someone else submits (an x402 facilitator, a contract that pays the gas). The hook then signs the entry with signAuthEntry, submits nothing, and calls complete(signedAuthEntry); the method resolves to { status: 'completed', result } with what complete returned, or to the error / cosign_pending outcome of the signature. Example in Pay for APIs with x402.

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, sessions 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. While the wallet has no recovery method (recoveryLocked), the menu shows the lock with a way to add one.

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 requirement of a route the quote rejected.

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 (see @pollar/core).

<CosignModal>

The approval prompt of a Turnkey wallet. It verifies each request on the device before enabling Approve, so the user only confirms a transaction the device checked itself. Every co-signed request opens it, wallet setup included. 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)} />

<RecoveryModal>

The recovery methods of the user's Turnkey wallet: add or remove a passkey, confirm an email with a code Turnkey sends, approve or reject a device that asks to join, recover this device with a passkey or an email code, and export the recovery phrase. The methods go straight to Turnkey from the device; Pollar never sets or confirms them. The provider mounts it for openRecoveryModal(), after a custody migration, and from the wallet menu while recoveryLocked.

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

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

See Passkeys and wallet recovery.

<CustodyMigrationModal>

Moves the user's custodial wallets to a Turnkey wallet on this device, for an app that keeps its wallets in Turnkey. The provider opens it after login while custodyMigration.required, before anything else; the user can leave it for later. A wallet that cannot move yet lists the reasons (SDK_CUSTODY_MIGRATION_BLOCKED).

<RampWidget>

Pre-built fiat on/off-ramp widget on the v3 ramps API. It lists the routes, quotes them, asks for the fields a quote needs, creates the order and follows it at the pace the server suggests. The order's pending action shows as it comes: a payment QR or bank details, Authorize for a signature, the co-sign approval or a verification step. A route the quote rejected shows why, with the fix when the user can make it (verify, add a trustline, set up or move a wallet).

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

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

Signing a leg only runs on a user press; polling never signs. When the app registered no signer for a leg (registerRampSigningHandler in @pollar/core), the widget signs with the user's connected wallet after checking the payload: a Stellar XDR must run every operation as the connected account (assertRampStellarSigner), and a Solana transfer must be built from the connected Solana wallet (signed through signSolanaTransaction).

RouteDisplay renders one quote and RejectedRouteDisplay one rejected route, for an app that lists routes itself.

<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.

Props a custom template must handle:

• CosignModalTemplateProps: theme, accentColor, pending, current, verification, busy ('approving' \| 'rejecting' \| null), error, onSelect, onApprove, onReject and onClose are required; styleOverrides, approveBlocked, lastResolved, explorerUrl, closesIn and nextStep are optional.
• RampWidgetTemplate takes the v3 flow: direction, countries, fiats / fiat, assets / asset, amount, quotes, rejected, fields / fieldValues, order, pendingOrders, the step (RampStep: 'input' \| 'loading_quote' \| 'select_route' \| 'contact' \| 'status' \| 'error') and its handlers (onFindRoute, onSelectQuote, onSign, onApprove, onResumeOrder, onNewOrder, onBack, onRetry, ...). Optional: onVerifyRoute, onTrustAsset, onWalletStep with walletBusy and custodyChoice, onRetryOrder, onSetUpRecovery with recoveryMissing, onCheckPayment with checkingPayment, notice and pollTrouble.
• WalletButtonTemplateProps takes theme, accentColor and an optional styleOverrides, like the modal templates, plus recoveryLocked / onRecovery, creatingWallet / createWalletError, custodyChoice and onCreateWallet(custody?).
• RecoveryModalTemplateProps carries the recovery state, the devices, the current view, busy, error, notice and one handler per action (onAddPasskey, onSendEmailCode, onConfirmEmail, onApproveDevice, onRecoverWithPasskey, onExport, ...).
• CustodyMigrationModalTemplateProps: state, busy, error, blockedReasons, onMove(custody?), onLater and onLogout.

Other required props: SendModalTemplateProps.onMax / onPaste, SwapModalTemplateProps.onReverse / onMax, SessionsModalTemplateProps.revokeError. The Send, Receive and WalletButton templates take an optional notReadyReason (from walletNotReadyReason).

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

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 for smart wallets, and browserRecoveryPasskey the one it installs for Turnkey wallet recovery (recoveryPasskey). Export them to a client you build yourself.

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,
  RecoveryView,
  UseCosignResult,
  UseChainsResult,
  TransactionModalTemplateProps,
  WalletBalanceModalTemplateProps,
  CosignModalTemplateProps,
  RecoveryModalTemplateProps,
  CustodyMigrationModalTemplateProps,
  // 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, RampQuote, RampOrder, CosignCustody, RecoveryState, CustodyMigrationState, ConfirmationPolicy, PollarLoginOptions, StellarNetwork, and WalletType are imported directly from @pollar/core.