SDK Reference

TypeScript client for interacting with the Agent Guardrails on-chain program. The SDK wraps every instruction, handles PDA derivation, and provides typed helpers for policy management, guarded execution, and kill switch operations.

Installation

terminal

npm install @agentguards/sdk

Initialization

client.ts

import { GuardrailsClient } from "@agentguards/sdk";
import { AnchorProvider } from "@coral-xyz/anchor";

const provider = AnchorProvider.env();
const client = new GuardrailsClient(provider);

PDA Derivation

The SDK provides two helpers that derive program-derived addresses used by all instructions. These mirror the seeds defined in the on-chain program.

pda.ts

import { findPolicyPda, findTrackerPda } from "@agentguards/sdk";

// Seeds: ["policy", owner, agent]
const [policyPda, policyBump] = findPolicyPda(ownerPubkey, agentPubkey);

// Seeds: ["tracker", policy]
const [trackerPda, trackerBump] = findTrackerPda(policyPda);

Policy Management

initializePolicy

Creates a new PermissionPolicy account and its associated SpendTracker. The caller (wallet) becomes the policy owner.

Param	Type	Description
`agent`	PublicKey	Public key of the AI agent keypair
`args`	InitializePolicyArgs	Policy configuration object (see below)

InitializePolicyArgs fields:

Field	Type	Description
`allowedPrograms`	Pubkey[]	Whitelisted program IDs (max 10)
`maxTxLamports`	u64	Per-transaction SOL cap in lamports
`maxTxTokenUnits`	u64	Per-transaction token unit cap
`dailyBudgetLamports`	u64	Rolling 24h budget in lamports
`sessionExpiry`	i64	Unix timestamp when the session expires
`squadsMultisig`	Option<Pubkey>	Squads v4 multisig for escalation (optional)
`escalationThreshold`	u64	Amount that triggers multisig escalation
`authorizedMonitors`	Pubkey[]	Keypairs allowed to pause the agent (max 3)

Returns the transaction signature.

init-policy.ts

const txSig = await client.initializePolicy(agentKeypair.publicKey, {
  allowedPrograms: [JUPITER_PROGRAM_ID, MARINADE_PROGRAM_ID],
  maxTxLamports: new BN(500_000_000),     // 0.5 SOL
  maxTxTokenUnits: new BN(1_000_000),
  dailyBudgetLamports: new BN(5_000_000_000), // 5 SOL
  sessionExpiry: new BN(Math.floor(Date.now() / 1000) + 86400),
  squadsMultisig: null,
  escalationThreshold: new BN(2_000_000_000), // 2 SOL
  authorizedMonitors: [monitorKeypair.publicKey],
});

updatePolicy

Modifies an existing policy. All fields are optional — only provided fields are updated.

Param	Type	Description
`policyPda`	PublicKey	Address of the PermissionPolicy account
`args`	UpdatePolicyArgs	Partial policy update (all fields optional)

update-policy.ts

await client.updatePolicy(policyPda, {
  maxTxLamports: new BN(1_000_000_000),   // raise to 1 SOL
  allowedPrograms: [JUPITER_PROGRAM_ID, MARINADE_PROGRAM_ID, DRIFT_PROGRAM_ID],
});

closePolicy

Permanently deletes a policy and its tracker. The policy must be paused first. Only the owner can close. Remaining lamports are refunded to the owner.

close-policy.ts

const txSig = await client.closePolicy(policyPda);

Execution

guardedExecute

The core instruction. Routes an agent transaction through the 12-step validation pipeline before executing the CPI. This is the only way an agent should interact with external programs.

Param	Type	Description
`agent`	Keypair	Agent keypair (must match policy)
`policyPda`	PublicKey	The PermissionPolicy PDA
`trackerPda`	PublicKey	The SpendTracker PDA
`targetProgram`	PublicKey	Program to invoke via CPI
`args`	GuardedExecuteArgs	Instruction data, amount hint, and optional input account index
`remainingAccounts`	AccountMeta[]	Accounts required by the target program

guarded-execute.ts

// Example: Jupiter swap through guarded execution
const txSig = await client.guardedExecute(
  agentKeypair,
  policyPda,
  trackerPda,
  JUPITER_PROGRAM_ID,
  {
    instructionData: swapIxData,
    amountHint: new BN(100_000_000), // 0.1 SOL
    inputAccountIndex: 2,
  },
  jupiterAccounts, // remaining accounts for the swap CPI
);

multisigExecute

Executes a transaction that has been approved by the Squads multisig. Used when an agent transaction exceeds the escalation threshold and requires human approval.

Param	Type	Description
`squadsProposal`	PublicKey	Squads v4 proposal account (must be in Approved state)

All other parameters are identical to guardedExecute. The multisig proposal serves as the authorization that replaces the standard budget check.

multisig-execute.ts

const txSig = await client.multisigExecute(
  agentKeypair,
  policyPda,
  trackerPda,
  JUPITER_PROGRAM_ID,
  {
    instructionData: swapIxData,
    amountHint: new BN(3_000_000_000), // 3 SOL (above threshold)
    inputAccountIndex: 2,
  },
  jupiterAccounts,
  squadsProposalPda,
);

Kill Switch

The kill switch immediately freezes all agent activity by setting isActive = false on the policy account. Any subsequent call to guarded_execute will fail with PolicyPaused.

kill-switch.ts

// Pause — callable by owner or any authorized monitor
const pauseTx = await client.pauseAgent(policyPda, "Anomalous transfer pattern detected");

// Resume — owner only
const resumeTx = await client.resumeAgent(policyPda);

pauseAgent can be called by the policy owner or any of the authorizedMonitors. resumeAgent is restricted to the owner only.

Key Rotation

Atomically swaps the agent keypair associated with a policy. Creates new PDAs under the new agent key, copies all configuration and budget state, transfers remaining funds, and closes the old accounts.

rotate-key.ts

const { txSig, newPolicyPda } = await client.rotateAgentKey(
  oldPolicyPda,
  newAgentKeypair.publicKey,
);

// Old policy + tracker PDAs are closed
// New policy + tracker PDAs are created with identical config

Types

Type	Kind	Description
`InitializePolicyArgs`	Instruction args	Configuration for creating a new policy (see initializePolicy above)
`UpdatePolicyArgs`	Instruction args	Partial update fields (all optional)
`GuardedExecuteArgs`	Instruction args	instructionData (Buffer), amountHint (BN), inputAccountIndex (number, optional)
`PermissionPolicy`	Account struct	On-chain policy state — owner, agent, limits, monitors, pause state
`SpendTracker`	Account struct	Rolling spend counters — 24h and 1h windows, transaction counts, destination tracking