Skip to main content

​
What is the Mandate SDK?

The @mandate.md/sdk package is a TypeScript SDK for the Mandate policy layer. It provides two main classes: MandateClient for low-level API calls, and MandateWallet for a high-level flow that validates, signs, broadcasts, and confirms transactions in one call. The SDK throws typed errors for every failure mode, so your agent can react to policy blocks, approval requests, and circuit breaker trips.

​
Installation

bun add @mandate.md/sdk

​
Quick start

Create a MandateClient and validate a transaction against your policies. 
import { MandateClient, PolicyBlockedError } from '@mandate.md/sdk';

const client = new MandateClient({
  runtimeKey: process.env.MANDATE_RUNTIME_KEY!,
});

try {
  const result = await client.validate({
    action: 'transfer',
    amount: '50',
    to: '0xRecipientAddress',
    token: 'USDC',
    reason: 'Payment for API access',
  });

  console.log('Intent ID:', result.intentId);
  console.log('Allowed:', result.allowed);
} catch (err) {
  if (err instanceof PolicyBlockedError) {
    console.log('Blocked:', err.blockReason);
  }
}
The validate() method sends an action-based request to the Mandate API. If the transaction passes all 14 policy checks, you get back a PreflightResult with allowed: true and an intentId. If it fails, the SDK throws a typed error with the specific block reason.

​
Exports

The SDK exposes the following from its main entry point.
ExportDescription
MandateClientLow-level API wrapper for validate, register, and status polling
MandateWalletHigh-level: validate, sign, broadcast, confirm in one call
MandateGuardAlias for MandateWallet
computeIntentHashkeccak256 of canonical tx string for raw validation
PolicyBlockedErrorTransaction blocked by policy (spend limit, allowlist, schedule)
MandateBlockedErrorAlias for PolicyBlockedError
CircuitBreakerErrorAgent emergency-stopped via circuit breaker
ApprovalRequiredErrorHuman approval needed before the transaction can proceed
RiskBlockedErrorRisk scanner blocked the transaction
MandateErrorBase error class for all Mandate errors
USDCUSDC contract addresses per chain
CHAIN_IDChain ID constants (mainnet + testnet)

​
Sub-path import

If you only need MandateClient and want a smaller bundle, import from the /client sub-path. This skips the viem dependency that MandateWallet requires. 
import { MandateClient } from '@mandate.md/sdk/client';
Use the sub-path import when your agent framework already handles signing and broadcasting. You get the same validate(), register(), and status() methods without pulling in viem.

​
How does the SDK handle errors?

Every failure mode has a dedicated error class. Your agent catches PolicyBlockedError for policy violations, ApprovalRequiredError when human review is needed, CircuitBreakerError when the agent is emergency-stopped, and RiskBlockedError when the risk scanner flags the transaction. All extend MandateError, so you can catch the base class as a fallback. See Error Handling for patterns and examples.

​
Next Steps

MandateClient

Low-level API methods: validate, register, poll status.

MandateWallet

High-level signing and broadcast flow with viem.

Error Handling

Typed error classes and recommended catch patterns.