ArcenAgent client

The ArcenAgent class is the primary entry point for @arcenpay/agent.

Constructor

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

const agent = new ArcenAgent(config: AgentConfig);

`AgentConfig` Options

Option	Type	Required	Default	Description
`privateKey`	`string`	Yes	—	EVM hex private key (`0x...`), Stellar secret seed (`S...`), or Solana base58/JSON keypair.
`chainId`	`number`	Yes	—	Target blockchain chain ID (e.g. `677`, `9100000`, `5042002`, `9000001`).
`rpcUrl`	`string`	No	Chain default	Custom RPC URL for EVM, Stellar Horizon/Soroban, or Solana.
`maxAutoApprove`	`string`	No	`"0.01"`	Max decimal amount (USDC/USDT) to auto-approve per request without explicit override.
`maxDailySpend`	`string \| number`	No	`undefined`	Hard cumulative spend limit within a 24-hour UTC calendar window.
`apiUrl`	`string`	No	`"https://api.arcenpay.com"`	ArcenPay API control plane URL.
`apiKey`	`string`	No	`undefined`	ArcenPay Provider API Key (required for `createPaymentLink`).
`store`	`PersistentStore`	No	`MemoryStore`	Persistence adapter (`FileStore` or custom) to preserve nonces across restarts.
`sessionVaultAddress`	`string`	No	Auto-resolved	Override for SessionVault contract address.
`autoTopUp`	`AutoTopUpConfig`	No	`undefined`	Automated session balance replenishment configuration.
`dispatch`	`DispatchConfig`	No	`undefined`	Multi-channel notification settings (Telegram, Discord, Slack) for human alerts.

Core Methods

`agent.fetch(url, options?)`

Drop-in replacement for global fetch(). Automatically intercepts HTTP 402 Payment Required, verifies the requested price against guardrails, signs a cryptographic voucher, and retries the request transparently.

const response = await agent.fetch("https://api.marketintel.ai/v1/sentiment", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ query: "ETH" }),
  maxPrice: "0.05",    // Hard ceiling for this call
  autoApprove: true,   // Allow if <= maxAutoApprove
});

const data = await response.json();

The signed voucher is replayed in the X-PAYMENT request header after the 402 challenge; the provider verifies it and returns the resource.

Payment Link Methods

`agent.resolvePaymentLink(urlOrSlug)`

Fetches and normalizes the machine-readable specification (AgenticPaymentLinkSpec) for a checkout link. Does not spend funds.

const spec = await agent.resolvePaymentLink("https://app.arcenpay.com/pay/crypto-data-pack");

console.log(spec.slug);           // "crypto-data-pack"
console.log(spec.amount);         // "10.000000"
console.log(spec.currency);       // "USDC"
console.log(spec.chainId);        // 677
console.log(spec.recipientWallet);// "0xMerchant..."

`agent.payPaymentLink(urlOrSlug, options?)`

Executes end-to-end payment for a link:

Resolves spec and checks chain compatibility.
Validates options.maxPrice, maxAutoApprove, and daily spend limits.
Initiates checkout session via backend.
Executes on-chain ERC-20 transfer (EVM), SAC payment (Stellar), or SPL transfer (Solana).
Confirms session and returns cryptographic AgentPaymentReceipt.

const receipt = await agent.payPaymentLink("crypto-data-pack", {
  maxPrice: "15.00",
  maxAutoApprove: "15.00",
  customerName: "ResearchWorker-1",
});

console.log("TxHash:", receipt.txHash);
console.log("Session ID:", receipt.sessionId);

`agent.createPaymentLink(params)`

Allows autonomous agents acting as merchants to create payment links programmatically (isAgentic: true). Requires apiKey in the constructor (or per-call via params.apiKey). Token handling is fully automatic — currency ("USDC", "USDT") is resolved to the chain’s token contract address, or you can pass a raw address via acceptedToken. expiresInMinutes is converted to an ISO expiresAt for the control plane.

const linkSpec = await agent.createPaymentLink({
  title: "100 Custom Web Scraping Credits",
  amount: 2.00,
  currency: "USDC",          // symbol → resolved token address
  chainId: 9100000,          // optional — defaults to the agent's chainId
  description: "High-speed clean Markdown web scraping API",
  expiresInMinutes: 1440,
});

console.log("Hosted URL (share with humans):", linkSpec.checkoutUrl);
console.log("Machine spec URL:", linkSpec.agenticSpecUrl);
console.log("Resolved token:", linkSpec.acceptedToken);

The returned spec also carries slug, sessionUrl, and confirmUrl for the machine-readable /spec endpoint and checkout session flow. sessionUrl is directly callable. confirmUrl is a template — confirmation is scoped to a checkout session, so substitute :sessionId with the id returned by sessionUrl before calling it:

const { sessionId } = await session;                    // POST sessionUrl
const confirm = spec.confirmUrl.replace(":sessionId", sessionId);
await fetch(confirm, { method: "POST" });

Session & Accounting Methods

`agent.fundSession(amount)`

Deposits amount USDC/USDT into the agent’s on-chain SessionVault. Returns the created sessionId.

const sessionId = await agent.fundSession("25.00"); // Deposit $25

Under the hood, funding is chain-specific: EVM approves the token and calls SessionVault.fundSession; Stellar transfers SAC USDC then calls the Soroban fund_session; Solana invokes the Anchor fund_session instruction, which creates or tops up the session vault.

`agent.getBalance()`

Returns the agent’s remaining unspent balance locked in the active session vault in atomic micros (bigint).

const balanceMicros = await agent.getBalance();
console.log("Remaining Balance:", Number(balanceMicros) / 1_000_000, "USDC");

`agent.getSpendSummary()`

Returns structured diagnostic metrics:

const summary = agent.getSpendSummary();
console.log(summary.dailySpent); // e.g. "1.450000"
console.log(summary.totalSpent); // e.g. "12.800000"

Auto-Topup & Dispatch Notifications

ArcenAgent supports human-in-the-loop and autonomous treasury replenishment when available balance drops below a threshold.

Configuration Example

const agent = new ArcenAgent({
  privateKey: process.env.AGENT_PRIVATE_KEY!,
  chainId: 5042002, // Arc Testnet
  autoTopUp: {
    mode: "dispatch",      // "auto" (instant refill) | "dispatch" (human approval) | "off"
    threshold: "1.00",     // trigger when balance drops below 1 USDC
    dailyLimit: "25.00",   // cumulative max daily top-up
    perTxnLimit: "5.00",   // max amount per individual top-up
  },
  dispatch: {
    enabled: true,
    cooldownSeconds: 120,
    maxRetries: 3,
    providers: [
      {
        type: "telegram",
        label: "Team Telegram Alerts",
        botToken: process.env.TELEGRAM_BOT_TOKEN!,
        chatId: process.env.TELEGRAM_CHAT_ID!,
        enabled: true,
      },
    ],
  },
});

`agent.sendDispatchRequest(amount, reason)`

Sends a top-up approval request to all enabled dispatch providers (Telegram inline buttons, Discord webhook, Slack, or Email):

const requests = await agent.sendDispatchRequest("5.00", "Top-up required for heavy LLM inference run");
console.log("Created request ID:", requests[0].id);

On Telegram, this sends an HTML message with interactive ✅ Approve and ❌ Deny callback buttons.

`agent.getPendingDispatchRequests()`

Returns all active dispatch requests awaiting human approval:

const pending = agent.getPendingDispatchRequests();
console.log(`Pending requests: ${pending.length}`);

`agent.resolveDispatchRequest(requestId, approved)`

Marks a dispatch request as approved or denied. If approved, the agent automatically executes the on-chain session top-up:

const resolved = agent.resolveDispatchRequest("topup_1789712108267_46c35b58", true);
console.log("Status:", resolved?.status); // "approved"

React SDK

Node.js SDK

Agent SDK

ArcenAgent client

Constructor

`AgentConfig` Options

Core Methods

`agent.fetch(url, options?)`

Payment Link Methods

`agent.resolvePaymentLink(urlOrSlug)`

`agent.payPaymentLink(urlOrSlug, options?)`

`agent.createPaymentLink(params)`

Session & Accounting Methods

`agent.fundSession(amount)`

`agent.getBalance()`

`agent.getSpendSummary()`

Auto-Topup & Dispatch Notifications

Configuration Example

`agent.sendDispatchRequest(amount, reason)`

`agent.getPendingDispatchRequests()`

`agent.resolveDispatchRequest(requestId, approved)`

​Constructor

​AgentConfig Options

​Core Methods

​agent.fetch(url, options?)

​Payment Link Methods

​agent.resolvePaymentLink(urlOrSlug)

​agent.payPaymentLink(urlOrSlug, options?)

​agent.createPaymentLink(params)

​Session & Accounting Methods

​agent.fundSession(amount)

​agent.getBalance()

​agent.getSpendSummary()

​Auto-Topup & Dispatch Notifications

​Configuration Example

​agent.sendDispatchRequest(amount, reason)

​agent.getPendingDispatchRequests()

​agent.resolveDispatchRequest(requestId, approved)

Constructor

`AgentConfig` Options

Core Methods

`agent.fetch(url, options?)`

Payment Link Methods

`agent.resolvePaymentLink(urlOrSlug)`

`agent.payPaymentLink(urlOrSlug, options?)`

`agent.createPaymentLink(params)`

Session & Accounting Methods

`agent.fundSession(amount)`

`agent.getBalance()`

`agent.getSpendSummary()`

Auto-Topup & Dispatch Notifications

Configuration Example

`agent.sendDispatchRequest(amount, reason)`

`agent.getPendingDispatchRequests()`

`agent.resolveDispatchRequest(requestId, approved)`