Developer Documentation

Integrate SentinelCRE in 30 minutes. 5-method SDK for proactive AI agent security.

Quick Start

Install the SDK:

Terminal

npm install @sentinel-cre/sdk
# or
bun add @sentinel-cre/sdk

Submit your first proposal for evaluation:

API Key Required

All SDK calls require an API key. The key authenticates your protocol, meters usage for billing, and tracks your Proof of Protection metrics. Contact us for your API key →

evaluate.ts

import { SentinelClient } from '@sentinel-cre/sdk'

const sentinel = new SentinelClient({
  apiKey: process.env.SENTINEL_API_KEY,  // Required — get yours at sentinelcre.ai/protocols
  rpcUrl: process.env.RPC_URL,
  contracts: {
    guardian: '0x...', // SentinelGuardian address
    registry: '0x...', // AgentRegistry address
  },
  chainId: 11155111,   // Sepolia
})

const verdict = await sentinel.evaluate({
  agentId: '0x...', // bytes32 agent identifier
  targetContract: '0x...',
  functionSignature: '0xa9059cbb',
  value: '1000000000000000000',
  mintAmount: '0',
  description: 'Transfer 1 ETH to vault',
})

if (verdict.consensus === 'DENIED') {
  console.log('Blocked:', verdict.model1.reason)
  // Handle denial — do not proceed with transaction
}

if (verdict.consensus === 'APPROVED') {
  // Safe to execute the on-chain action
}

API Reference

The SDK exposes 5 methods. evaluate() calls the evaluation service over HTTP. The remaining 4 methods read directly from the SentinelGuardian contract on-chain and require rpcUrl and contracts in the config.

evaluate(proposal)

Submit an AI agent's proposed action through the full 3-layer defense pipeline: policy enforcement, behavioral anomaly detection, and dual-AI consensus. This is the primary method most integrators need.

Signature

async evaluate(proposal: ProposedAction) => Promise<SentinelVerdict>

Parameters

proposalProposedActionThe proposed on-chain action to evaluate

Example

const verdict = await sentinel.evaluate({
  agentId: '0x00...01',
  targetContract: '0xUniswapRouter...',
  functionSignature: '0x38ed1739',
  value: '500000000000000000',
  mintAmount: '0',
  description: 'Swap 0.5 ETH for USDC',
})
// verdict.consensus === 'APPROVED' | 'DENIED'

getAgentPolicy(agentId)

Read an agent's policy configuration from the SentinelGuardian contract. Returns value limits, rate limits, and consensus requirements.

Signature

async getAgentPolicy(agentId: string) => Promise<AgentPolicy>

Parameters

agentIdstringbytes32 hex agent identifier

Example

const policy = await sentinel.getAgentPolicy('0x00...01')
// policy.maxTransactionValue  — bigint (wei)
// policy.rateLimit            — bigint
// policy.requireMultiAiConsensus — boolean

getAgentState(agentId)

Read an agent's current state. Returns 'Active', 'Frozen', or 'Revoked'. Frozen agents have triggered a circuit breaker and require manual review.

Signature

async getAgentState(agentId: string) => Promise<AgentState>

Parameters

agentIdstringbytes32 hex agent identifier

Example

const state = await sentinel.getAgentState('0x00...01')
if (state === 'Frozen') {
  // Agent is under review — do not submit actions
}

getActionStats(agentId)

Read action statistics for an agent: approved and denied counts, current rate-limit window actions, and daily volume.

Signature

async getActionStats(agentId: string) => Promise<ActionStats>

Parameters

agentIdstringbytes32 hex agent identifier

Example

const stats = await sentinel.getActionStats('0x00...01')
console.log(`Approved: ${stats.approved}, Denied: ${stats.denied}`)
console.log(`Daily volume: ${stats.currentDailyVolume} wei`)

isAgentActive(agentId)

Quick convenience check — returns true if the agent is registered and in the Active state. Use this for fast gate checks before submitting proposals.

Signature

async isAgentActive(agentId: string) => Promise<boolean>

Parameters

agentIdstringbytes32 hex agent identifier

Example

const active = await sentinel.isAgentActive('0x00...01')
if (!active) {
  throw new Error('Agent is not active')
}

Configuration

SentinelClient accepts a SentinelConfig object. apiKey is required for all evaluation calls. On-chain reads need rpcUrl and contracts.

Property	Type	Required	Description
apiUrl	string	Yes	Evaluation service endpoint
apiKey	string	Yes	Your API key — authenticates requests, meters usage, tracks Proof of Protection. Contact usBearer token for authenticated requests
rpcUrl	string	On-chain reads	Blockchain RPC endpoint (e.g. Alchemy, Infura)
contracts	{ guardian, registry }	On-chain reads	SentinelGuardian and AgentRegistry contract addresses
chainId	number	No	Chain ID (defaults to 1). Determines viem chain for on-chain reads.

Supported Chains

Network	Chain ID	Status
Ethereum Mainnet	1	Configured
Sepolia Testnet	11155111	Active
Base	8453	Configured
Arbitrum One	42161	Configured
Foundry (Local)	31337	Dev

Types Reference

All types are exported from @sentinel-cre/sdk and can be imported directly.

ProposedAction

interface ProposedAction {
  agentId: string           // bytes32 hex — agent identifier
  targetContract: string    // address — target contract
  functionSignature: string // bytes4 hex — function selector
  value: string             // numeric string — tx value in wei
  mintAmount: string        // numeric string — mint amount (0 if not minting)
  calldata?: string         // hex — raw calldata (optional)
  description: string       // human-readable action description
  recentValues?: number[]   // recent tx values for behavioral analysis
  recentTimestamps?: number[] // recent timestamps for velocity scoring
}

SentinelVerdict

interface SentinelVerdict {
  consensus: 'APPROVED' | 'DENIED'
  model1: AIModelVerdict
  model2: AIModelVerdict
  proposal: ProposedAction
  timestamp: number
  severity?: 'LOW' | 'MEDIUM' | 'CRITICAL'
  anomalyScore: number | null
  anomalyFlagged: boolean
  anomalyDimensions: AnomalyDimension[] | null
  challengeWindowExpiry?: number
  challengeStatus?: 'PENDING' | 'APPEALED' | 'UPHELD' | 'OVERTURNED' | 'EXPIRED'
  layerCatchInfo?: LayerCatchInfo
  fallback?: boolean
}

AIModelVerdict

interface AIModelVerdict {
  verdict: 'APPROVED' | 'DENIED'
  confidence: number   // 0-1
  reason: string
}

AgentPolicy

interface AgentPolicy {
  maxTransactionValue: bigint
  maxDailyVolume: bigint
  maxMintAmount: bigint
  rateLimit: bigint
  rateLimitWindow: bigint
  requireMultiAiConsensus: boolean
  isActive: boolean
}

AgentState

type AgentState = 'Active' | 'Frozen' | 'Revoked'

ActionStats

interface ActionStats {
  approved: bigint
  denied: bigint
  currentWindowActions: bigint
  currentDailyVolume: bigint
}

Integration Paths

SDK Only

~30 min

Evaluate proposals via the SDK before executing on-chain. No contract changes needed. Works with any wallet or agent framework.

Try live demo →

Safe Guard

~15 min

Install SentinelSafeGuard on your Gnosis Safe. Every transaction is automatically checked against policy before execution. No code changes to your agent.

Try live demo →

ERC-7579 Validator

~20 min

Add SentinelValidator as a module on any ERC-7579 smart account. UserOps are validated against policy and behavioral baselines before execution.

Try live demo →

What Your API Key Enables

Metered Billing

Every evaluation call is logged against your key. Pay for what you use.

Proof of Protection

Running counter of attacks blocked and value saved — verifiable on-chain.

Behavioral Profiles

Your agents build behavioral baselines that improve detection over time.

API keys are issued during onboarding. Email us to get started.

Security Note

The SDK evaluates proposals — it does not expose detection methodology. Behavioral scoring weights, AI prompts, and detection thresholds are proprietary and protected via Confidential Compute.