@humbleaf/agentchain-sdk

Policy-checked actions with settlement-aware receipts.

A framework-agnostic TypeScript client for submitting risky actions, evaluating policy, and tracking release, denial, or approval via AgentChain.

import { AgentChain } from '@humbleaf/agentchain-sdk';

const ac = new AgentChain({
  apiKey: process.env.AGENTCHAIN_API_KEY,
  agentId: 'agent_invoice-bot_a1b2c3',
});

const receipt = await ac.submitAction({
  actionType: 'spend_control',
  operation: 'transfer_usdc',
  target: '0xVendorWallet',
  requestedValue: 480,
  currency: 'USDC',
  evidence: { invoiceHash: '0xabc...' },
});

if (receipt.policyVerdict === 'released') {
  console.log('✓ Settlement released:', receipt.receiptId);
} else if (receipt.policyVerdict === 'pending_approval') {
  console.log('⏳ Needs approval:', receipt.approvalUrl);
} else {
  console.log('✗ Denied:', receipt.reasonCodes);
}

What Problem Does This Solve?

AI agents and automated workflows are already making decisions that move value: processing invoices, deploying code, issuing refunds, sending outreach. But there's no standard way to enforce policy before those actions settle.

AgentChain is the trust and settlement layer. This SDK lets any framework submit actions for policy evaluation and get back a receipt that is safe to settle against.

Core Methods

| Method | Description | |---|---| | submitAction(input) | Submit an action for server-side policy evaluation | | getReceipt(id) | Get the current state of a receipt | | listReceipts(opts) | List recent receipts for this agent | | getAgent() | Get agent info (trust level, capabilities) | | dryRunAction(input) | Evaluate policy without creating a real action | | waitForReceipt(id, opts) | Poll until receipt reaches terminal state | | getPolicySummary() | Get active policies for this agent |

Receipt Example

{
  "receiptId": "rcpt_abc123",
  "policyVerdict": "released",
  "settlementStatus": "released",
  "policyEvaluations": [
    { "policyName": "Max Value Per Action", "result": "pass", "why": "480 <= 1000" },
    { "policyName": "Approved Counterparty", "result": "pass", "why": "Vendor on allowlist" }
  ],
  "reasonCodes": [],
  "attestationUid": "0x...",
  "easscanUrl": "https://base.easscan.org/attestation/view/0x..."
}

policyVerdict vs settlementStatus

| policyVerdict | settlementStatus | What it means | |---|---|---| | released | released | Policy passed, value moved | | released | pending_dispute_window | Policy passed, value held during dispute window | | pending_approval | pending_approval | Policy needs human sign-off | | denied | denied | Policy blocked, nothing moved |

policyVerdict = did the rules pass? settlementStatus = is value allowed to move yet?

Installation

npm install @humbleaf/agentchain-sdk
# or
pnpm add @humbleaf/agentchain-sdk

License

MIT