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 viemCurrent 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:
| Verdict | Meaning | Also returned |
|---|---|---|
ALLOW | Paid. | txHash |
ESCALATE | Held for approval. | txHash, escalationId |
DENY | Refused before sending. Nothing was submitted. | error |
FREEZE | The 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 transactionRead the wallet
| Method | Returns |
|---|---|
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.
- Save the submission as soon as it is sent, using the
onSubmittedoption. - After an error, call
reconcileUSDC(txHash, originalInput)to read the real outcome. - 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.
| Error | Meaning |
|---|---|
PolicyDeniedError | The policy refused the payment. |
EscalationRequiredError | The payment needs approval. |
WalletFrozenError | The wallet is frozen. |
AgentNotAuthorizedError | This key is not a signer on the wallet. |
InsufficientUSDCError | The wallet does not hold enough USDC. |
TransferRevertedError | The transaction was sent but reverted onchain. |
TransactionRecoveryError | Sent, outcome unknown. See above. |
All except TransactionRecoveryError extend ArcanumError.