React SDK overview

The @arcenpay/react package is the browser-side SDK for ArcenPay. It provides a context provider for initialization, a drop-in billing component, and hooks for feature gating and entitlements. Payment link creation and management is a server-side concern — do it with @arcenpay/node (ArcenClient) or @arcenpay/agent, then use the returned checkoutUrl in your React UI.

Installation

npm install @arcenpay/react

Exports

Export	Type	Description
`ArcenPayProvider`	Component	Context provider — wrap your app to initialize the SDK.
`useArcenPay`	Hook	Access the SDK context and call `identify()`.
`ArcenEmbed`	Component	Drop-in billing surface with checkout, portal, payment, unsubscribe, and success views.
`FeatureFlagGuard`	Component	Conditionally render children based on a feature flag.
`TemplateRenderer`	Component	Render versioned billing templates from the dashboard.
`useFlag`	Hook	Check a single boolean feature flag.
`useFlags`	Hook	Check multiple feature flags at once.
`useEntitlement`	Hook	Check a full entitlement with usage state.
`useConsumeEntitlement`	Hook	Consume a metered entitlement (decrement usage counter).
`useTrack`	Hook	Track an event for analytics or event-based flags.

Payment links

The React SDK does not create payment links — that is a backend job that requires an API key. Create and manage them with:

@arcenpay/node — client.createPaymentLink(), listPaymentLinks(), getPaymentLink(), updatePaymentLink() (server-side).
@arcenpay/agent — agent.createPaymentLink() for autonomous AI merchant links.
Dashboard — Catalog → Payment Links.

Each created link returns a checkoutUrl (e.g. https://app.arcenpay.com/pay/…). Use that URL for human redirects, or render ArcenEmbed for in-app checkout. Never construct checkoutUrls by hand in the browser — always use the URL returned by the backend.

Quick example

"use client";

import { ArcenPayProvider, ArcenEmbed } from "@arcenpay/react";

export function App() {
  return (
    <ArcenPayProvider
      publishableKey={process.env.NEXT_PUBLIC_ARCENPAY_PUBLISHABLE_KEY}
      componentId={process.env.NEXT_PUBLIC_ARCENPAY_COMPONENT_ID}
    >
      <BillingPage />
    </ArcenPayProvider>
  );
}

function BillingPage() {
  return <ArcenEmbed mode="modal" />;
}

Environmental variables

NEXT_PUBLIC_ARCENPAY_PUBLISHABLE_KEY=pk_xxxxxxxxx
NEXT_PUBLIC_ARCENPAY_COMPONENT_ID=cmp_xxxxxxxxx
# Target Chain ID: 677 (BOT Chain Mainnet), 9100000 (Solana Mainnet), 5042002 (Arc Testnet),
# 84532 (Base Sepolia), 9000001 (Stellar Testnet), or 9100001 (Solana Devnet)
NEXT_PUBLIC_CHAIN_ID=677
NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=xxxxxxxxx

Client-only

All components and hooks in @arcenpay/react require the browser. In Next.js App Router, add "use client" to any file that imports from @arcenpay/react.

Optional: smart account gas sponsorship

ArcenPay integrates ERC-7579 smart accounts for gas sponsorship. The SDK fetches the configured bundler and paymaster endpoints automatically, so your customers don’t need gas tokens for on-chain actions.

Optional: RainbowKit / wagmi

If your app uses RainbowKit or wagmi, wrap ArcenPayProvider inside your existing wallet provider. ArcenPay builds on wagmi and shares the wallet connection.

Next steps

ArcenPayProvider — provider configuration and identify() reference
Hooks reference — all hooks with examples
ArcenEmbed reference — component props and view configuration

React SDK

Node.js SDK

Agent SDK

React SDK overview

Installation

Exports

Payment links

Quick example

Environmental variables

Client-only

Optional: smart account gas sponsorship

Optional: RainbowKit / wagmi

Next steps

​Installation

​Exports

​Payment links

​Quick example

​Environmental variables

​Client-only

​Optional: smart account gas sponsorship

​Optional: RainbowKit / wagmi

​Next steps

Installation

Exports

Payment links

Quick example

Environmental variables

Client-only

Optional: smart account gas sponsorship

Optional: RainbowKit / wagmi

Next steps