SDK Reference

Installation

npm install @humbleaf/agentchain-sdk viem

Quick Start

import { createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { baseSepolia } from 'viem/chains';
import { AgentChain } from '@humbleaf/agentchain-sdk';

const ac = new AgentChain({
  apiKey: process.env.AGENTCHAIN_API_KEY,
});

const wallet = createWalletClient({
  account: privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`),
  chain: baseSepolia,
  transport: http(),
});

// Guard a transaction through the policy engine and execute if allowed
const { receipt, transactionHash } = await ac.evm.guardAndExecute(wallet, {
  chainId: 84532,
  from: wallet.account.address,
  to: '0x2626664c2603336E57B271c5C0b26F421741e481', // UniswapV3 Router
  data: '0x...',
  value: '0',
  policyId: 'pol_uniswap_safe',
});

console.log('decision:', receipt.decision);    // 'allow' | 'deny' | 'approval_required'
console.log('txHash:', transactionHash);        // null if not executed
console.log('signature:', receipt.signature);   // EIP-712 signed receipt

Modules

`ac.evm` — Pre-transaction guard

Method	Description
`ac.evm.guardTransaction(input)`	Submit for policy evaluation; returns signed `EvmGuardReceiptV2` (no execution)
`ac.evm.guardAndExecute(wallet, input)`	Guard + execute in one call; throws typed errors on non-allow decisions
`ac.evm.reportExecution(receiptId, txHash)`	Link an on-chain txHash to an `allow` receipt; transitions state to `executed`

Decision errors from `guardAndExecute`

import {
  AgentChainEvmPolicyDenied,
  AgentChainEvmApprovalRequired,
  AgentChainExpiredDecision,
} from '@humbleaf/agentchain-sdk';

try {
  const result = await ac.evm.guardAndExecute(wallet, txInput);
} catch (err) {
  if (err instanceof AgentChainEvmPolicyDenied) {
    console.error('Denied:', err.reasonCodes); // ['VALUE_EXCEEDED', ...]
  } else if (err instanceof AgentChainEvmApprovalRequired) {
    console.log('Needs approval:', err.approvalId);
  } else if (err instanceof AgentChainExpiredDecision) {
    console.warn('Receipt expired — re-guard and retry');
  } else {
    throw err;
  }
}

`ac.policies` — Gateway policy management

Method	Description
`ac.policies.create(body)`	Create a new policy
`ac.policies.get(policyId, chainId)`	Fetch the current active policy
`ac.policies.update(policyId, chainId, body)`	Bump policy version (creates new immutable snapshot)
`ac.policies.list()`	List all policies for the operator
`ac.policies.listVersions(policyId, chainId)`	List full version history
`ac.policies.hash(body)`	Compute `policyHash` locally (JCS + keccak256) — no network
`ac.policies.hashRemote(body)`	Compute `policyHash` server-side (parity check)

// Create
const policy = await ac.policies.create({
  policyId: 'pol_uniswap_safe',
  chainId: 84532,
  label: 'Safe Uniswap swaps on Base Sepolia',
  rules: {
    allowedTargets: ['0x2626664c2603336E57B271c5C0b26F421741e481'],
    allowedSelectors: ['0x414bf389'], // exactInputSingle
    maxValueWei: '1000000000000000000',
    maxSlippageBps: 100,
    dailyCapWei: '5000000000000000000',
    approvalThresholdWei: '500000000000000000',
  },
});

// Update (creates new snapshot version)
const updated = await ac.policies.update('pol_uniswap_safe', 84532, {
  rules: { ...policy.rules, maxValueWei: '2000000000000000000' },
});

`ac.receipts` — Receipt fetch and verification

Method	Description
`ac.receipts.get(receiptId)`	Fetch a stored receipt by ID
`ac.receipts.verify(digest, sig, signer)`	Verify EIP-712 signature locally — pure ECDSA, no HTTP
`ac.receipts.verifyRemote(receipt)`	Verify server-side (signature + expiry + state + signer registry)
`ac.receipts.verifyWithAnchor(receipt)`	Two-step: ECDSA verify + `SignerAnchor.isAuthorized()` on-chain check
`ac.receipts.getAnchorStatus(receiptId)`	Poll `ReceiptAnchor` for anchor state + `anchorTxHash`

Local verification (no network)

const valid = ac.receipts.verify(
  receipt.receiptHash as `0x${string}`,
  receipt.signature as `0x${string}`,
  receipt.signerAddress as `0x${string}`,
);

On-chain verification (trustless)

const ac = new AgentChain({
  apiKey: process.env.AGENTCHAIN_API_KEY,
  signerAnchorAddress: '0x36cbAE566545e8df3ad15C171a7840266526E28F',
  signerAnchorChainId: 84532,
  signerAnchorRpcUrl: 'https://sepolia.base.org',
});

const result = await ac.receipts.verifyWithAnchor(receipt);
// result.valid — boolean
// result.anchorState — 'authorized' | 'revoked' | 'unavailable'
// result.reasons — string[] (e.g. ['signer_anchor_unavailable'] if RPC fails)

The SDK degrades gracefully: if the SignerAnchor RPC call fails, anchorState is 'unavailable' and the result falls back to local ECDSA verification. Never a silent pass.

`ac.approvals` — Approval queue management

Method	Description
`ac.approvals.list(decision?)`	List approval requests filtered by status (`PENDING`, `APPROVED`, `DENIED`, `EXPIRED`)
`ac.approvals.get(id)`	Get full approval detail
`ac.approvals.count()`	Get the pending count (for badges / polling)
`ac.approvals.resolve(id, decision, note?)`	Approve or deny a pending request
`ac.approvals.registerWebhook(id, callbackUrl)`	Register a one-shot callback URL for a specific approval

// List pending approvals
const pending = await ac.approvals.list('PENDING');

// Approve with a note
await ac.approvals.resolve(pending[0].id, 'approved', 'Verified with finance');

For threshold configuration, auto-approve rules, and webhook setup, see Approval Queue.

`@agentchain/core` — Standalone Canonicalization

The @agentchain/core package ships independently and provides the deterministic primitives used by both the gateway and the SDK:

npm install @agentchain/core

Export	Description
`hashPolicy(body)`	Compute `policyHash` — JCS serialize then `keccak256(utf8(jcs))`
`verifyReceiptSignature(digest, sig, signer)`	Pure ECDSA recover + compare — no SDK dependency
`canonicalizePolicy(body)`	Strip ephemeral fields + lowercase targets (step before hashing)

Use @agentchain/core in environments where you want receipt/policy verification without pulling in the full SDK (e.g., a smart contract relayer, a Rust-adjacent TypeScript service, or an audit script).

Standalone Codecs

The SDK also exports IPFS ↔ bytes32 codecs:

import { cidToBytes32, bytes32ToCid } from '@humbleaf/agentchain-sdk';

// CID → on-chain storage (32 bytes)
const bytes32 = cidToBytes32('bafybeif...');

// On-chain → CID reconstruction
const cid = bytes32ToCid('0x1220...');

Getting Started

Core Protocol

Infrastructure

Installation

Quick Start

Modules

`ac.evm` — Pre-transaction guard

Decision errors from `guardAndExecute`

`ac.policies` — Gateway policy management

`ac.receipts` — Receipt fetch and verification

Local verification (no network)

On-chain verification (trustless)

`ac.approvals` — Approval queue management

`@agentchain/core` — Standalone Canonicalization

Standalone Codecs

​Installation

​Quick Start

​Modules

​ac.evm — Pre-transaction guard

​Decision errors from guardAndExecute

​ac.policies — Gateway policy management

​ac.receipts — Receipt fetch and verification

​Local verification (no network)

​On-chain verification (trustless)

​ac.approvals — Approval queue management

​@agentchain/core — Standalone Canonicalization

​Standalone Codecs

Installation

Quick Start

Modules

`ac.evm` — Pre-transaction guard

Decision errors from `guardAndExecute`

`ac.policies` — Gateway policy management

`ac.receipts` — Receipt fetch and verification

Local verification (no network)

On-chain verification (trustless)

`ac.approvals` — Approval queue management

`@agentchain/core` — Standalone Canonicalization

Standalone Codecs