SDKsTypeScript

TypeScript SDK

arcanum-sdk lets an agent read its wallet, check a payment before sending it, and pay through the wallet’s policy. It talks to Arc directly; no Arcanum server is needed to pay.

npm install arcanum-sdk viem

Current version: 3.0.0 on npm.

Connect an agent to its wallet

import { ArcanumClient } from "arcanum-sdk"
import { ARC_MAINNET_RPC_URL, arcMainnet } from "arcanum-sdk/chains"
import { privateKeyToAccount } from "viem/accounts"
 
const arc = new ArcanumClient({
  walletAddress: process.env.GUARDED_WALLET as `0x${string}`,
  agentSigner: privateKeyToAccount(process.env.AGENT_PRIVATE_KEY as `0x${string}`),
  chain: arcMainnet,
  rpcUrl: process.env.ARC_MAINNET_RPC_URL ?? ARC_MAINNET_RPC_URL,
})

For testing, use arcTestnet and ARC_TESTNET_RPC_URL. To keep the agent’s key off your server, use Circle Wallets as the signer.

Pay

import { usdcErc20 } from "arcanum-sdk/chains"
 
const result = await arc.executeUSDC({
  to: "0x...",
  amount: usdcErc20(50),          // 50 USDC
  reason: "OpenAI API top-up",
  metadata: { category: "API" },
})

result.verdict tells the agent what happened:

VerdictMeaningAlso returned
ALLOWPaid.txHash
ESCALATEHeld for approval.txHash, escalationId
DENYRefused before sending. Nothing was submitted.error
FREEZEThe payment froze the wallet.txHash

Check before paying

const decision = await arc.simulate({ to: "0x...", amount: usdcErc20(500) })
// decision.verdict and decision.reason, without sending a transaction

Read the wallet

MethodReturns
getPolicy()The current policy.
getDailySpent()USDC spent in the current day window.
getMonthlySpent()USDC spent in the current 30-day window.
getVendor(address)Whether a vendor is allowed or blocked, and its cap.
onEscalationResolved(id, callback)Calls back when a held payment is settled.
onFrozen(callback)Calls back when the wallet freezes.

Payment intents and receipts

For audit trails, describe the payment as an intent with your own business reference, get a signed receipt for the decision, then pay and link the two:

  • createPaymentIntent({ ..., reference })
  • requestPaymentReceipt(intent)
  • executePaymentIntentWithReceipt(intent)

Version 3 renamed idempotencyKey to reference. The reference identifies the payment in your system; it does not stop a payment being sent twice.

When a payment outcome is unknown

If the SDK sent a transaction but could not confirm what happened (for example, the RPC dropped), it throws TransactionRecoveryError. This does not mean the payment failed.

  1. Save the submission as soon as it is sent, using the onSubmitted option.
  2. After an error, call reconcileUSDC(txHash, originalInput) to read the real outcome.
  3. Never retry automatically or with a new reference.
await arc.executeUSDC(input, {
  onSubmitted: async (submission) => saveToDatabase(submission),
})
⚠️

There is no exactly-once guarantee. If the process crashes before the transaction hash is saved, check the wallet’s history before paying again.

Errors

A policy denial is returned, not thrown: executeUSDC returns verdict: "DENY" with the PolicyDeniedError in result.error, and nothing is sent. The other errors are thrown.

ErrorMeaning
PolicyDeniedErrorThe policy refused the payment.
EscalationRequiredErrorThe payment needs approval.
WalletFrozenErrorThe wallet is frozen.
AgentNotAuthorizedErrorThis key is not a signer on the wallet.
InsufficientUSDCErrorThe wallet does not hold enough USDC.
TransferRevertedErrorThe transaction was sent but reverted onchain.
TransactionRecoveryErrorSent, outcome unknown. See above.

All except TransactionRecoveryError extend ArcanumError.