Get started with ArcenPay

This guide walks you through integrating ArcenPay SDKs into your application.

Finish dashboard setup

Before writing any code, complete these steps in the ArcenPay dashboard:

Create at least one published plan in Catalog → Plans.
Configure any add-ons, credits, or payment links you want to expose.
Create and publish a billing component in Components.
Generate an API key and copy your publishable key from Settings → API Keys.

You need a published plan and a published billing component before ArcenEmbed can render a checkout or portal surface. Complete this step first.

Install the SDKs

Install the SDKs relevant to your application architecture:

npm install @arcenpay/react

npm install @arcenpay/node

npm install @arcenpay/agent

Add environment variables

Variables prefixed with NEXT_PUBLIC_ are safe to expose in the browser. Keep ARCENPAY_API_KEY, ARCENPAY_WEBHOOK_SECRET, and agent private keys strictly server-side.

# Browser-safe (React SDK)
NEXT_PUBLIC_ARCENPAY_PUBLISHABLE_KEY=pk_live_xxxxxxxxx   # or pk_test_ in development
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

# Server-only (Node SDK / AI Agents)
ARCENPAY_API_KEY=sk_live_xxxxxxxxxxxxxxxxxxxxxxxx   # secret key; full REST surface. sk_/rk_ keys are the only supported credential types.
ARCENPAY_WEBHOOK_SECRET=whsec_xxxxxxxxx
AGENT_PRIVATE_KEY=0x_your_private_key_here

Variable	Purpose
`NEXT_PUBLIC_ARCENPAY_PUBLISHABLE_KEY`	Publishable key from the dashboard (`pk_...`). Safe in the browser.
`NEXT_PUBLIC_ARCENPAY_COMPONENT_ID`	ID of the billing component you published (`cmp_...`).
`NEXT_PUBLIC_CHAIN_ID`	Active settlement chain ID: `677` (BOT Chain Mainnet), `9100000` (Solana Mainnet), `5042002` (Arc Testnet), `84532` (Base Sepolia), `9000001` (Stellar Testnet), or `9100001` (Solana Devnet).
`NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID`	WalletConnect project ID for wallet support in `ArcenEmbed`.
`ARCENPAY_API_KEY`	Server-side secret key (`sk_...`). Use a secret or restricted key for the full REST surface (companies, events, payment links, activation).
`ARCENPAY_WEBHOOK_SECRET`	HMAC secret for verifying webhook payloads.
`AGENT_PRIVATE_KEY`	EVM hex, Stellar secret seed (`S...`), or Solana base58 keypair for autonomous `ArcenAgent` signing.

See API keys and authentication for the definitive guide on which key works with which endpoint — including the modern sk_, pk_, and rk_ key types.

Wrap your app with ArcenPayProvider

ArcenPayProvider initializes the React SDK. Add it at the root of your app.

"use client";

import type { ReactNode } from "react";
import { ArcenPayProvider } from "@arcenpay/react";

export function Providers({ children }: { children: ReactNode }) {
  return (
    <ArcenPayProvider
      publishableKey={process.env.NEXT_PUBLIC_ARCENPAY_PUBLISHABLE_KEY}
      componentId={process.env.NEXT_PUBLIC_ARCENPAY_COMPONENT_ID}
    >
      {children}
    </ArcenPayProvider>
  );
}

ArcenPayProvider must render on the client. In Next.js App Router, add "use client" to the file and import it from your server-rendered root layout.

Identify the active customer

Call identify() once your app has resolved the customer’s identity.

"use client";

import { useEffect } from "react";
import { useArcenPay } from "@arcenpay/react";

export function BillingSession({
  companyId,
  wallet,
}: {
  companyId: string;
  wallet: string;
}) {
  const { identify, session } = useArcenPay();

  useEffect(() => {
    if (!wallet) return;
    if (session.company?.wallet?.toLowerCase() === wallet.toLowerCase()) return;

    void identify({
      company: { id: companyId, wallet, name: "Acme" },
      user: { id: `user-${companyId}`, wallet },
    });
  }, [companyId, identify, session.company?.wallet, wallet]);

  return null;
}

Render this component once near the top of your authenticated layout so billing state resolves before the customer navigates to a billing page.

Render ArcenEmbed

ArcenEmbed handles checkout, portal, payment, unsubscribe, and success states.

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

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

For server-issued tokens, mint one with the Node SDK and pass it via accessToken:

// Server-side: mint a token
import { ArcenClient } from "@arcenpay/node";

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

const session = await client.identify({
  company: { id: "company_123", wallet: "0xabc..." },
  user: { id: "user_123", wallet: "0xabc..." },
  expiresIn: 3600,
});

// Return session.token to the frontend

// Client-side: pass the token
<ArcenEmbed accessToken={token} componentId="cmp_123" />

See Sessions and access tokens for details on server-issued tokens.

Enforce access on the server

Never rely solely on client-side entitlement checks. Use the Node SDK to verify access in your API routes.

import { ArcenClient } from "@arcenpay/node";

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

// Check a feature entitlement
const entitlement = await client.checkEntitlement("scan", {
  id: "company_123",
});

if (!entitlement.enabled) {
  throw new Error("Upgrade required");
}

// Consume a metered entitlement
const result = await client.consumeEntitlement({
  featureKey: "scan",
  company: { id: "company_123" },
  idempotencyKey: `scan-${requestId}`,
});

Client-side hooks like useFlag and useEntitlement are for UI gating only. Always perform authoritative access checks server-side before executing sensitive or billable operations.

Enable AI Agents and MCP tools (Optional)

If your application interacts with AI agents or exposes autonomous billing workflows, use @arcenpay/agent to pay payment links or negotiate HTTP 402 micro-settlements:

import { ArcenAgent } from "@arcenpay/agent";

const agent = new ArcenAgent({
  privateKey: process.env.AGENT_PRIVATE_KEY!,
  rpcUrl: "https://rpc.botchain.ai", // or Solana / Arc / Base / Stellar
  chainId: 677, // BOT Chain Mainnet (or 9100000 Solana Mainnet)
});

// Pay an Agentic Payment Link autonomously
const receipt = await agent.payPaymentLink("api-credits-100");
console.log("Agent payment tx:", receipt.txHash);

// Or query an HTTP 402 paywalled endpoint (auto-pays & retries)
const response = await agent.fetch("https://api.example.com/premium/analysis");
const data = await response.json();

Next steps

Chains & networks — multi-chain settlement matrix and SDK network configuration
Agent payments guide — autonomous payments and x402 negotiation
15 MCP Tools reference — connect ArcenPay directly to Claude Desktop, Cursor, and LLMs
Subscription wall — gate entire routes behind an active subscription
Feature gating — show or hide features based on plan
Webhooks — listen for billing events to sync your app’s state

Get started

Core concepts

Guides

Integrations

Get started with ArcenPay

Next steps

​Next steps

Next steps