ArcenClient reference

ArcenClient is the HTTP client that communicates with the ArcenPay backend. It handles authentication, request serialization, and error normalization.

Constructor

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

const client = new ArcenClient({
  apiKey: process.env.ARCENPAY_API_KEY!,
  baseUrl: "https://api.arcenpay.com",  // optional; defaults to the platform URL
  timeoutMs: 10_000,                     // optional; request timeout in ms
});

Option	Type	Description
`apiKey`	`string`	A supported key prefix (`sk_` secret, `rk_` restricted, or `pk_` publishable). Which key you need depends on the endpoint — see the endpoint auth matrix.
`baseUrl`	`string`	Override the API base URL (defaults to the ArcenPay API).
`timeoutMs`	`number`	Request timeout in milliseconds (default `10_000`).

Company methods

identify()

Upserts a company and user, returns a session token for ArcenEmbed.

const session = await client.identify({
  company: {
    id: "company_123",        // your external ID
    wallet: "0xabc...",
    name: "Acme Corp",
    email: "[email protected]",
    traits: { industry: "fintech" },
  },
  user: {
    id: "user_123",
    wallet: "0xabc...",
  },
  expiresIn: 3600,           // default: 3600 (1 hour)
});

console.log(session.token);  // JWT for ArcenEmbed

createCompany()

Creates a new company record.

const company = await client.createCompany({
  id: "company_123",         // optional external ID
  name: "Acme Corp",
  wallet: "0xabc...",
  email: "[email protected]",
  traits: { industry: "fintech" },
  logoUrl: "https://acme.com/logo.png",
});

getCompany()

Fetches full company detail including entitlements, add-on grants, users, and overrides.

const company = await client.getCompany("cm_abc123");
// company.entitlements — array of resolved entitlements
// company.activePlan — current plan details
// company.addOns — active add-ons
// company.overrides — company-level flag overrides

updateCompany()

Updates a company’s name, traits, plan assignment, or add-on IDs.

await client.updateCompany("cm_abc123", {
  name: "Acme Corp (renamed)",
  traits: { tier: "enterprise" },
  activePlanId: "plan_pro",     // assign/change plan
  activeAddOnIds: ["addon_123"], // set active add-ons
});

listCompanies()

Returns a paginated list of companies.

const result = await client.listCompanies({
  limit: 50,
  cursor: "cm_abc",
  search: "acme",
});

// result.data — Company[]
// result.count — number of results
// result.nextCursor — cursor for next page

Company deletion is dashboard-managed

ArcenClient does not expose a deleteCompany() method. Removing a company permanently is a sensitive operation handled from the dashboard’s Customers → Companies screen (requires a catalog:write session role). If you need to remove a customer, use the dashboard UI — do not attempt to script it. Your backend can always anonymize or mark customers inactive through updateCompany().

Subscription methods

activateSubscription()

Executes first-time on-chain subscription activation.

const activation = await client.activateSubscription({
  planId: "plan_starter",
  paymentAccount: "0xabc...",
  company: { id: "company_123", wallet: "0xabc..." },
  subscriberEmail: "[email protected]",
});

console.log(activation.tokenId);  // Subscription NFT ID
console.log(activation.txHash);   // EVM transaction hash

Access check methods

checkFlag()

Simple boolean flag check.

const enabled = await client.checkFlag("scan", { id: "company_123" });

checkEntitlement()

Full entitlement check with usage state.

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

console.log(entitlement.enabled);
console.log(entitlement.usage);
console.log(entitlement.limit);
console.log(entitlement.remaining);
console.log(entitlement.exceeded);

consumeEntitlement()

Consume metered entitlement with idempotency.

const result = await client.consumeEntitlement({
  featureKey: "scan",
  company: { id: "company_123" },
  idempotencyKey: `scan-${requestId}`,
  amount: 1,                      // default: 1
});

if (result.exceeded) {
  throw new Error("Usage limit exceeded");
}

Event tracking

track()

Record an event for analytics or event-based flags.

await client.track({
  event: "scan_completed",
  company: { id: "company_123" },
  properties: { fileSize: 1024, source: "api" },
  timestamp: "2026-05-01T12:00:00.000Z", // optional
});

Additional access checks

checkFlags()

Checks multiple feature flags in one call and returns a record keyed by feature key:

const flags = await client.checkFlags(["scan", "export_pdf"], { id: "company_123" });
console.log(flags.scan.key);      // "scan"
console.log(flags.scan.enabled);  // boolean

listEntitlements()

Resolves the full entitlement map for a company:

const entitlements = await client.listEntitlements({ id: "company_123" });
// entitlements["scan"] — EntitlementResult

Payment link methods

listPaymentLinks()

Lists the payment links in your team:

const result = await client.listPaymentLinks();
// result.paymentLinks — PaymentLinkSummary[]

createPaymentLink()

Creates a hosted payment link. Accepts a token symbol or address for acceptedToken, an optional chainId, and isAgentic: true to enable the dual-mode /spec endpoint for autonomous agents:

const link = await client.createPaymentLink({
  kind: "CUSTOM",
  name: "Setup fee",
  amount: 25,
  acceptedToken: "USDC",            // symbol or token address
  chainId: 5042002,                 // BOT 677, Solana 9100000, Arc 5042002, Base Sepolia 84532, …
  recipientWallet: "0x7b2aF4D3e1c6E9f0A5b8dC1e2F3A4B5C6D7E8F90",
  isAgentic: true,                  // enables machine-readable /pay/:slug/spec
});

// link.paymentLink.checkoutUrl     — hosted checkout URL (share with humans)
// link.paymentLink.agenticSpecUrl  — machine-readable spec endpoint
// link.paymentLink.isAgentic       — true

getPaymentLink()

Fetches a single payment link by ID:

const link = await client.getPaymentLink("pl_abc123");
// link.paymentLink.checkoutUrl — hosted checkout URL

updatePaymentLink()

Updates an existing payment link — for example, to deactivate or archive it:

await client.updatePaymentLink("pl_abc123", { status: "ARCHIVED" });

Status values: ACTIVE, INACTIVE, ARCHIVED.

Checkout session methods

createCheckoutSession()

Creates a server-side checkout session, typically for a payment link:

const session = await client.createCheckoutSession({
  paymentLinkId: "pl_abc123",
  companyId: "cm_abc123",
  customerEmail: "[email protected]",
});

getCheckoutSession()

Fetches a checkout session by ID:

const session = await client.getCheckoutSession("cs_abc123");

listCheckoutSessions()

Lists your team’s checkout sessions:

const result = await client.listCheckoutSessions();
// result.checkoutSessions — CheckoutSessionSummary[]

getCheckoutSessionStatus()

Resolves a session’s current status — PENDING, PAID, EXPIRED, CANCELLED, or FAILED:

const status = await client.getCheckoutSessionStatus("cs_abc123");
console.log(status.status); // "PENDING" | "PAID" | ...

createHostedCheckout()

Creates a checkout session for an existing payment link and returns the hosted checkoutUrl ready to redirect customers:

const result = await client.createHostedCheckout({
  paymentLinkId: "pl_abc123",
  customer: { email: "[email protected]", name: "Acme Corp" },
  successUrl: "https://myapp.com/billing/success",
  expiresInSeconds: 3600,
});

// result.checkoutUrl — hosted checkout URL (with session attached)
// result.sessionId  — session ID for status polling

chargeCustomer()

One-call helper that creates a CUSTOM payment link and checkout session for a one-time charge, with an idempotency key to prevent duplicate charges:

const result = await client.chargeCustomer({
  name: "Priority setup fee",
  amount: 49,
  recipientWallet: "0x7b2aF4D3e1c6E9f0A5b8dC1e2F3A4B5C6D7E8F90",
  company: { id: "cm_abc123" },
  customer: { email: "[email protected]" },
  successUrl: "https://myapp.com/setup/success",
});

// result.checkoutUrl — hosted checkout URL
// result.paymentLinkId / result.sessionId / result.slug

regenerateCheckoutSession()

Creates a fresh checkout session for an existing payment link (useful when a previous session expired) and returns a new hosted checkoutUrl:

const result = await client.regenerateCheckoutSession("pl_abc123", {
  expiresInSeconds: 3600,
});

Company overrides

setCompanyOverride()

Sets a manual per-company flag override:

await client.setCompanyOverride("cm_abc123", "scan", false, "Blocked by ops");

Error handling

All client methods throw ArcenApiError on non-2xx responses.

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

try {
  await client.getCompany("nonexistent");
} catch (error) {
  if (error instanceof ArcenApiError) {
    console.log(error.statusCode);   // 404
    console.log(error.message);       // "Company not found"
  }
}

ArcenApiError fields

Field	Type	Description
`message`	`string`	Human-readable error message.
`statusCode`	`number`	HTTP status code.

Access checks reference — detailed entitlement enforcement patterns
Webhooks reference — signature verification
Node SDK overview — all exports and services

React SDK

Node.js SDK

Agent SDK

ArcenClient reference

Constructor

Company methods

identify()

createCompany()

getCompany()

updateCompany()

listCompanies()

Company deletion is dashboard-managed

Subscription methods

activateSubscription()

Access check methods

checkFlag()

checkEntitlement()

consumeEntitlement()

Event tracking

track()

Additional access checks

checkFlags()

listEntitlements()

Payment link methods

listPaymentLinks()

createPaymentLink()

getPaymentLink()

updatePaymentLink()

Checkout session methods

createCheckoutSession()

getCheckoutSession()

listCheckoutSessions()

getCheckoutSessionStatus()

createHostedCheckout()

chargeCustomer()

regenerateCheckoutSession()

Company overrides

setCompanyOverride()

Error handling

ArcenApiError fields

​Constructor

​Company methods

​identify()

​createCompany()

​getCompany()

​updateCompany()

​listCompanies()

​Company deletion is dashboard-managed

​Subscription methods

​activateSubscription()

​Access check methods

​checkFlag()

​checkEntitlement()

​consumeEntitlement()

​Event tracking

​track()

​Additional access checks

​checkFlags()

​listEntitlements()

​Payment link methods

​listPaymentLinks()

​createPaymentLink()

​getPaymentLink()

​updatePaymentLink()

​Checkout session methods

​createCheckoutSession()

​getCheckoutSession()

​listCheckoutSessions()

​getCheckoutSessionStatus()

​createHostedCheckout()

​chargeCustomer()

​regenerateCheckoutSession()

​Company overrides

​setCompanyOverride()

​Error handling

​ArcenApiError fields

​Related

Constructor

Company methods

identify()

createCompany()

getCompany()

updateCompany()

listCompanies()

Company deletion is dashboard-managed

Subscription methods

activateSubscription()

Access check methods

checkFlag()

checkEntitlement()

consumeEntitlement()

Event tracking

track()

Additional access checks

checkFlags()

listEntitlements()

Payment link methods

listPaymentLinks()

createPaymentLink()

getPaymentLink()

updatePaymentLink()

Checkout session methods

createCheckoutSession()

getCheckoutSession()

listCheckoutSessions()

getCheckoutSessionStatus()

createHostedCheckout()

chargeCustomer()

regenerateCheckoutSession()

Company overrides

setCompanyOverride()

Error handling

ArcenApiError fields

Related