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 viemKeep 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 paymentsCreate 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_WALLETUSDC 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.