Skip to main content

​
Quickstart

This guide walks you through building, testing, and deploying a policy using PolicyKit.

​
1. Create a Policy

Use the PolicyBuilder to define your policy: 
import { PolicyBuilder } from "@policy-kit/sdk";
import { parseEther } from "viem";

const policy = new PolicyBuilder("my-first-policy")
  // Tier 1: Stateless on-chain rules
  .allowTargets([
    "0x1234...5678", // Your DeFi protocol
    "0xabcd...ef01", // Another trusted contract
  ])
  .maxValue(parseEther("1")) // Max 1 ETH per tx

  // Tier 2: Stateful on-chain rules
  .spendLimit(
    "0xUSDC_ADDRESS",
    parseEther("10000"), // 10k USDC
    86400 // per day
  )
  .cooldown(60) // 60 seconds between transactions

  // Tier 3: Off-chain rules (Lit Protocol)
  .maxSlippageBps(100) // 1% max slippage
  .requireSimulation(true) // Must simulate successfully

  // Configuration
  .setFailMode("closed") // Block if Lit is unreachable
  .build();

​
2. Simulate Locally

Before deploying, test your policy locally with the PolicySimulator: 
import { PolicySimulator } from "@policy-kit/sdk";

const simulator = new PolicySimulator();

const report = await simulator.evaluate(policy, {
  target: "0x1234...5678",
  value: parseEther("0.5"),
  data: "0x...", // Transaction calldata
});

console.log(report.allowed); // true or false
console.log(report.results); // Detailed per-rule results

​
3. Deploy the Policy

Deploy your policy to IPFS and on-chain: 
import { PolicyKit } from "@policy-kit/sdk";
import { createPublicClient, createWalletClient, http } from "viem";
import { baseSepolia } from "viem/chains";

const publicClient = createPublicClient({
  chain: baseSepolia,
  transport: http(),
});

const walletClient = createWalletClient({
  chain: baseSepolia,
  transport: http(),
  account: "0xYOUR_ACCOUNT",
});

const pk = new PolicyKit({
  publicClient,
  walletClient,
  engineAddress: "0xPOLICY_ENGINE_ADDRESS",
  ipfsBackends: [
    {
      type: "pinata",
      jwt: process.env.PINATA_JWT,
    },
  ],
  litConfig: {
    network: "naga",
    litActionCID: "Qm...", // Deployed Lit Action CID
  },
});

// Deploy: pins to IPFS + registers on-chain
const result = await pk.deployPolicy(policy);
console.log("Policy CID:", result.cid);
console.log("Tx hash:", result.txHash);

​
4. Using the CLI

Alternatively, use the CLI for common operations: 
# Initialize a new policy from a template
policykit init --template smart-account

# Simulate a transaction against a policy
policykit simulate --policy ./policy.json --target 0x1234 --value 0.5

# Deploy a policy
policykit deploy --policy ./policy.json --chain base-sepolia

# Inspect an on-chain policy
policykit inspect --account 0xYOUR_ACCOUNT --chain base-sepolia

​
What’s Next?

Core Concepts

Understand policies and rules in depth.

Three-Tier Rules

Learn about the three tiers of rule evaluation.

PolicyBuilder API

Explore the full PolicyBuilder API reference.

Examples

See complete example implementations.