Agent Integration

Wire Philidor risk checks into your AI agent workflow for pre-trade screening, portfolio monitoring, and automated alerts.

AI agents making DeFi decisions should check risk before executing. Philidor provides the data layer for risk-aware autonomous agents.

Architecture

User Request → AI Agent → Philidor MCP/API → Risk Data → Decision

The agent receives a request (e.g., "deposit USDC into highest-yield vault"), queries Philidor for risk scores, and makes an informed decision rather than optimizing purely for yield.

MCP Integration (Preferred)

The fastest path is connecting your agent to the MCP server:

claude mcp add philidor --transport http https://mcp.philidor.io/api/mcp

The agent automatically gets access to 10 tools, 3 resources, and 3 prompts.

Example Agent Workflow

User: "Find USDC vaults ranked by net APY"
Agent calls search_vaults with asset=USDC, sortBy=apr_net, sortOrder=desc
Agent calls get_vault_risk_breakdown for the top-ranked result
Agent checks if risk tier is acceptable (Prime or Core)
Agent surfaces the vault with its risk context

REST API Integration

For agents that don't support MCP, use the REST API directly:

async function checkVaultRisk(network: string, address: string) {
  const res = await fetch(`https://api.philidor.io/v1/vault/${network}/${address}`);
  const { data } = await res.json();
  const vault = data.vault;

  return {
    score: Number(vault.total_score),
    tier: vault.risk_tier,
    isAudited: vault.is_audited,
    // deposit_status is the canonical tri-state signal - read this, not the
    // boolean. 'open' = confirmed accepting deposits, 'closed' = maxDeposit
    // is zero on chain, 'unknown' = not yet probed (typically non-ERC4626).
    depositStatus: vault.deposit_status as 'open' | 'closed' | 'unknown',
    capacityUsd: vault.deposit_capacity_usd, // null when uncapped/unknown
    isSafe:
      Number(vault.total_score) >= 8.0 && vault.is_audited && vault.deposit_status !== 'closed',
  };
}

// Agent decision logic
const risk = await checkVaultRisk('ethereum', '0x8eB67...');
if (risk.depositStatus === 'closed') {
  return 'This vault is currently rejecting new deposits on-chain (caps reached, paused, or queue saturated). Pick a different vault.';
}
if (risk.depositStatus === 'unknown') {
  // Optional: do a pre-flight maxDeposit call from the user's wallet here
  // before composing the deposit tx, to avoid the rare revert path.
}
if (!risk.isSafe) {
  return "This vault doesn't meet the minimum safety threshold (Prime tier, audited).";
}

Pre-trade screening at the list level

When routing capital across many vaults - picking the best USDC vault, for example - exclude confirmed-closed vaults at the server with ?depositable=true, then apply your strictness policy on the response:

const res = await fetch(
  'https://api.philidor.io/v1/vaults?asset=USDC&depositable=true&sortBy=apr_net&sortOrder=desc&limit=20'
);
const { data: candidates } = await res.json();

// Server-side `depositable=true` drops `closed` but keeps `unknown`. Conservative
// routers should additionally require deposit_status === 'open' here.
const safe = candidates.filter((v) => v.deposit_status === 'open');

// Size each candidate against its remaining cap (when known).
for (const v of safe) {
  const headroom = v.deposit_capacity_usd; // number | null
  const sizeable = headroom == null || headroom >= myDepositSize;
  if (!sizeable) continue;
  // ...
}

This is the single most common foot-gun for yield-seeking agents: a vault can show 20%+ APY but have maxDeposit == 0 at the contract level - the yield is residual interest on the existing position and new principal cannot enter.

Risk Guardrails

Agents should enforce risk guardrails before executing DeFi operations:

Guardrail	Check	Threshold
Accepts deposits	`deposit_status`	Must be `"open"` (strict) or not `"closed"`
Withdrawals work	`withdraw_status`	Must be `"open"` for symmetric round-trip routing
Data is fresh	`freshness_seconds`	`< 3600` (or your tolerance) - never route on stale state
Minimum risk tier	`risk_tier`	Prime or Core
Audit requirement	`is_audited`	Must be true
Minimum TVL	`tvl_usd`	Above your minimum liquidity threshold
Capacity available	`deposit_capacity_usd`	Null or ≥ planned size
Oracle quality	Asset vector score	>= 7
No recent incidents	Check events endpoint	No incidents in 90 days
No recent state flapping	`/v1/vault/{network}/{address}/events`	Sanity-check the last 24h before routing large size

Portfolio-Level Checks

Before adding a new position, check portfolio concentration:

const positions = await fetch(`https://api.philidor.io/v1/address/${wallet}/positions`);
const { data } = await positions.json();

// Check if adding this vault would exceed protocol concentration
const protocolExposure = data.positions
  .filter((p) => p.protocol_name === newVault.protocol_name)
  .reduce((sum, p) => sum + parseFloat(p.balance_usd), 0);

const totalValue = Number(data.aggregates.total_value_usd) + depositAmount;
const concentration = (protocolExposure + depositAmount) / totalValue;

if (concentration > 0.5) {
  return 'Adding this position would exceed 50% concentration in one protocol.';
}

CLI For Agents

The CLI supports structured output for agent workflows.

philidor vaults --asset USDC --risk-tier prime --json
philidor screen conservative --json
philidor schema vault --json

Use --enable-commands to run the CLI in sandbox mode with an explicit comma-separated allowlist.

philidor --enable-commands stats,vaults,search stats

The packaged OpenClaw skill wraps the CLI for agent runtimes that use skill files.

Signals And Alerts

The public /v1/signals feed exposes published risk signals from The Wire. Use it alongside events for market and protocol monitoring.

Webhook delivery exists for basket subscriptions on eligible plans. Risk Graph simulation and personalized agent policy surfaces remain roadmap items.

Agent Integration

On this page