React hooks reference

The React SDK provides hooks for reading feature flags, checking entitlements, consuming metered usage, and tracking events. All hooks require ArcenPayProvider to be mounted.

useFlag

Returns true or false for a single feature flag.

import { useFlag } from "@arcenpay/react";

function ExportButton() {
  const enabled = useFlag("export_pdf");

  if (!enabled) return null;
  return <button>Export PDF</button>;
}

Signature

function useFlag(featureKey: string): boolean

Returns false while the session is loading. Once the session resolves, returns the flag’s resolved value for the current company.

useFlags

Checks multiple flags at once and returns a record of results.

import { useFlags } from "@arcenpay/react";

function Dashboard() {
  const flags = useFlags(["analytics_export", "scan", "priority_support"]);

  return (
    <div>
      {flags.analytics_export && <AnalyticsPanel />}
      {flags.scan && <ScanButton />}
      {flags.priority_support && <PriorityBadge />}
    </div>
  );
}

Signature

function useFlags(featureKeys: string[]): Record<string, boolean>

useEntitlement

Returns subscription state plus the resolved feature map for a wallet. Pass featureKey to filter the resolved feature map to a single feature.

import { useEntitlement } from "@arcenpay/react";

function UsageMeter({ walletAddress }: { walletAddress: string }) {
  const { isSubscribed, features, planTier, isLoading } = useEntitlement(
    walletAddress,
    "scan",
  );

  if (isLoading) return <Spinner />;

  const canScan = isSubscribed && features.scan === true;

  return (
    <div>
      <p>{canScan ? "Active" : "Not available"}</p>
      {planTier && <p>Plan: {planTier}</p>}
    </div>
  );
}

Signature

function useEntitlement(
  walletAddress?: string,
  featureKey?: string
): {
  isSubscribed: boolean;
  planTier: "free" | "starter" | "pro" | "enterprise" | null;
  features: Record<string, boolean | string | number>;
  expiresAt: bigint | null;
  tokenId: bigint | null;
  sources: Record<string, unknown>;
  freshness: Record<string, unknown>;
  isLoading: boolean;
  error: Error | null;
  refetch: () => void;
}

Use this hook when you need on-chain subscription status or a feature map derived from dashboard entitlements, compatibility endpoints, and configured fallback feature values.

useConsumeEntitlement

Returns a consume function that decrements a metered entitlement.

import { useConsumeEntitlement } from "@arcenpay/react";

function ScanButton() {
  const { consume } = useConsumeEntitlement();

  async function handleScan() {
    const result = await consume("scan");
    if (result.exceeded) {
      alert("Scan limit reached. Upgrade your plan.");
    }
  }

  return <button onClick={handleScan}>Scan Document</button>;
}

Signature

function useConsumeEntitlement(): {
  consume: (featureKey: string) => Promise<{
    consumed: boolean;
    usage: number;
    limit: number;
    remaining: number;
    exceeded: boolean;
  }>
}

Use client.consumeEntitlement() from the Node SDK when you need server-controlled idempotency keys or authoritative metered enforcement.

useTrack

Returns a track function for emitting usage events.

import { useTrack } from "@arcenpay/react";

function AnalyticsTracker() {
  const { track } = useTrack();

  async function handlePageView(page: string) {
    await track("page_viewed", { page, referrer: document.referrer });
  }

  return null; // Imperative tracking — no UI needed
}

Signature

function useTrack(): {
  track: (event: string, properties?: Record<string, unknown>) => Promise<void>
}

Events tracked via useTrack are sent to the ArcenPay backend and can be used for event-based feature flags and analytics.

FeatureFlagGuard

A component that conditionally renders children based on a flag:

import { FeatureFlagGuard } from "@arcenpay/react";

<FeatureFlagGuard featureKey="export_pdf" walletAddress={walletAddress}>
  <ExportButton />
</FeatureFlagGuard>

Props

Prop	Type	Required	Description
`featureKey`	`string`	Yes	The flag key to check.
`walletAddress`	`string`	Yes	The customer’s wallet address.
`children`	`ReactNode`	Yes	Content to render when the flag is enabled.
`fallback`	`ReactNode`	No	Content to render when the flag is disabled.

TemplateRenderer

Renders billing templates from JSON blocks created in the dashboard template library:

import { TemplateRenderer } from "@arcenpay/react";

<TemplateRenderer
  name="pricing-page"
  blocks={[
    { type: "heading", content: "Startups" },
    { type: "text", content: "Everything you need to launch." },
    { type: "price", amount: "$49", interval: "/month" },
    { type: "feature-list", items: ["Unlimited scans", "PDF export"] },
    { type: "cta", content: "Upgrade", href: "/checkout?plan=pro" },
  ]}
/>

Block types: heading, text, price, feature-list, and cta.

Payment links

Payment links are created and managed server-side — the React SDK has no payment-link creation API (browser code can’t hold API keys).

Create / manage: ArcenClient.createPaymentLink(), listPaymentLinks(), getPaymentLink(), updatePaymentLink() from @arcenpay/node (see ArcenClient reference).
Agentic links: agent.createPaymentLink() from @arcenpay/agent for autonomous AI merchant flows (see ArcenAgent client).
Redirect humans: use the checkoutUrl the backend returns — it points to the hosted checkout page at /pay/:slug.

// server-side — @arcenpay/node
import { ArcenClient } from "@arcenpay/node";

const client = new ArcenClient({ apiKey: process.env.ARCENPAY_API_KEY! });

const { paymentLink } = await client.createPaymentLink({
  kind: "CUSTOM",
  name: "Setup fee",
  amount: 25,
  chainId: 5042002,
  acceptedToken: "USDC", // symbol or token address
  recipientWallet: "0x7b2aF4D3e1c6E9f0A5b8dC1e2F3A4B5C6D7E8F90",
});
// paymentLink.checkoutUrl → https://app.arcenpay.com/pay/… (share with humans)

Next steps

Entitlements concept — understand the entitlement model
Feature flags concept — flag types and rules engine
ArcenEmbed reference — the billing UI component

React SDK

Node.js SDK

Agent SDK

React hooks reference

useFlag

Signature

useFlags

Signature

useEntitlement

Signature

useConsumeEntitlement

Signature

useTrack

Signature

FeatureFlagGuard

Props

TemplateRenderer

Payment links

Next steps

​useFlag

​Signature

​useFlags

​Signature

​useEntitlement

​Signature

​useConsumeEntitlement

​Signature

​useTrack

​Signature

​FeatureFlagGuard

​Props

​TemplateRenderer

​Payment links

​Next steps

useFlag

Signature

useFlags

Signature

useEntitlement

Signature

useConsumeEntitlement

Signature

useTrack

Signature

FeatureFlagGuard

Props

TemplateRenderer

Payment links

Next steps