Quickstart

Quickstart

In this guide you create an agent wallet, give it a spending policy, fund it, and send a payment that the contract checks before any USDC moves. It takes about ten minutes.

This guide uses Arc Testnet, so no real money moves. To use Arc Mainnet, import arcMainnet and ARC_MAINNET_RPC_URL instead and use the mainnet factory address from Deployments.

You need: Node.js, a key with a little testnet USDC for gas (the owner), and a second key for the agent.

Install the SDK

npm install arcanum-sdk viem

Keep keys in environment variables, never in source code:

OWNER_PRIVATE_KEY=0x...   # owns the wallet and changes its rules
AGENT_PRIVATE_KEY=0x...   # the agent; it can only request payments

Create the wallet with a policy

The policy below lets the agent spend up to 100 USDC per payment, 200 USDC per day and 1,000 USDC per month. Any payment above 50 USDC waits for approval.

import { WalletFactoryAbi } from "arcanum-sdk"
import { ARC_TESTNET_RPC_URL, arcTestnet } from "arcanum-sdk/chains"
import { createWalletClient, http, parseUnits } from "viem"
import { privateKeyToAccount } from "viem/accounts"
 
const owner = privateKeyToAccount(process.env.OWNER_PRIVATE_KEY as `0x${string}`)
const agent = privateKeyToAccount(process.env.AGENT_PRIVATE_KEY as `0x${string}`)
 
const ownerClient = createWalletClient({
  account: owner,
  chain: arcTestnet,
  transport: http(ARC_TESTNET_RPC_URL),
})
 
const policy = {
  perTxCap: parseUnits("100", 6),
  daily24hCap: parseUnits("200", 6),
  monthlyCap: parseUnits("1000", 6),
  allowedCategories: 0b11111n, // all five vendor categories
  escalationThreshold: parseUnits("50", 6),
  requireAllowlist: false,
  freezeOnBlockedVendor: true,
}
 
const hash = await ownerClient.writeContract({
  address: "0xbE1bC48F26e7166D872828d40e82A6407dbD350C", // WalletFactory, Arc Testnet
  abi: WalletFactoryAbi,
  functionName: "createWallet",
  args: [
    owner.address,      // owner
    "research-agent",   // label
    policy,             // first policy
    [agent.address],    // agent signers
    [owner.address],    // approvers for held payments
    1,                  // approvals needed
    3600,               // a held payment expires after one hour
  ],
})

Read the new wallet’s address from the WalletCreated event:

import { createPublicClient, parseEventLogs } from "viem"
 
const publicClient = createPublicClient({ chain: arcTestnet, transport: http(ARC_TESTNET_RPC_URL) })
const receipt = await publicClient.waitForTransactionReceipt({ hash })
const [created] = parseEventLogs({ abi: WalletFactoryAbi, eventName: "WalletCreated", logs: receipt.logs })
console.log(created.args.wallet) // save this as GUARDED_WALLET

USDC amounts in a policy use 6 decimals, which is why the example uses parseUnits(..., 6).

Fund the wallet

Send testnet USDC to the new wallet address from any wallet. Arcanum never holds these funds; they sit in your wallet contract.

Send a payment as the agent

import { ArcanumClient } from "arcanum-sdk"
 
const arc = new ArcanumClient({
  walletAddress: process.env.GUARDED_WALLET as `0x${string}`,
  agentSigner: agent,
  chain: arcTestnet,
  rpcUrl: ARC_TESTNET_RPC_URL,
})
 
const result = await arc.executeUSDC({
  to: "0x...",              // the vendor you are paying
  amount: parseUnits("20", 6),
  reason: "Search API credits",
})
 
console.log(result.verdict, result.txHash) // "ALLOW", "0x..."

20 USDC is under every limit, so the contract allows it and the USDC moves in the same transaction.

Try a payment that needs approval

Send 75 USDC. It is under the 100 USDC per-payment cap but above the 50 USDC approval threshold, so the wallet holds it. result.verdict is "ESCALATE" and result.escalationId identifies the held payment. Approve it from the approver address (here, the owner):

import { EscalationManagerAbi } from "arcanum-sdk"
 
await ownerClient.writeContract({
  address: "0xb5907700Df79B9030FafDaA48C26AE355512cCcd", // EscalationManager, Arc Testnet
  abi: EscalationManagerAbi,
  functionName: "approve",
  args: [result.escalationId!],
})

With one approval required, this releases the payment. On Arc Mainnet, approvers can also use the hosted app at thearcanum.in.

Next steps

  • Read Policies to see every rule and the order they run in.
  • Read Escalations to see how held payments are approved.
  • Use Vendors to restrict the agent to known recipients.