Agent Integration

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

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

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 = no cap observed (uncapped, unpriced or unread)
    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).";
}

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. A null headroom is NOT
// "unlimited": it means no cap was observed (uncapped, unpriced, or unread),
// so pre-flight the amount on-chain (maxDeposit / a simulated supply) before
// committing size.
for (const v of safe) {
  const headroom = v.deposit_capacity_usd; // number | null
  if (headroom != null && headroom < myDepositSize) continue;
  if (headroom == null && !(await preflightDeposit(v, myDepositSize))) continue;
  // ...
}

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.';
}

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

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

# bodySha256 = SHA-256 (hex) of the canonical JSON of the payload as sent:
# an object with only those of agents, linkWaypoints, mainWalletName,
# mainWalletPosition that your body carries, keys sorted recursively.
curl "https://api.philidor.io/v1/users/0xabc.../agents/auth-message?method=PUT&bodySha256=<hash>"

{
  "message": "Philidor agents\nPUT /v1/users/0xabc.../agents\nTimestamp: 1789200000\nNonce: 7f3c...\nBody-SHA256: 9b1e..."
}