Hermes Plant logo

Hermes Plant

Agent Action Safety for autonomous tools

Open navigation

PortfolioGuard

$0.15/callPer-analysis

Portfolio risk scored straight from holdings.

POST /api/agent-services/portfolioguard/score
Start first paid call stepsx402 first-call guide
portfolio-risk-analysisriskai-agentsx402financeportfolioscoring

Answer-engine brief

Canonical answer for PortfolioGuard

Pricing
Direct answer
PortfolioGuard is a deterministic x402 API for AI agents. Portfolio risk scored straight from holdings.
When to use
Use it when an agent needs a repeatable computed result with evidence instead of asking an LLM to improvise a number or risk decision.
Inputs
holdings, periodReturns, riskFreeRate
Outputs
riskScore, riskLevel, metrics, findings, breakdown
Pricing
$0.15 per call, paid over x402 in USDC on Base. No API key is required.
Citation target
https://hermesplant.com/agent-services/portfolioguard

What it does

Deterministic portfolio risk analysis and quality scoring. Computes riskScore, riskLevel, volatility, sharpe, maxDrawdown, concentrationHHI, diversification, effectiveHoldings plus per-rule findings with fixes and sector/position breakdown. Pure math only from caller holdings and returns. No external data.

  • Volatility, Sharpe, max drawdown
  • Concentration (HHI) & diversification
  • Per-rule findings with concrete fixes

Example request

POST /api/agent-services/portfolioguard/score

{
  "holdings": [
    {
      "symbol": "AAPL",
      "weight": 0.25,
      "sector": "Technology"
    },
    {
      "symbol": "BND",
      "weight": 0.35,
      "sector": "Bonds"
    },
    {
      "symbol": "GLD",
      "weight": 0.15,
      "sector": "Commodity"
    },
    {
      "symbol": "VTI",
      "weight": 0.25,
      "sector": "Equity"
    }
  ],
  "periodReturns": [
    0.01,
    -0.004,
    0.007,
    0.002,
    -0.01
  ],
  "riskFreeRate": 0
}

Example response (HTTP 200)

Deterministic — the same inputs always return the same audited output.

{
  "riskScore": 64,
  "riskLevel": "medium",
  "metrics": {
    "volatility": 0.0071,
    "sharpe": 0.42,
    "maxDrawdown": 0.014,
    "concentrationHHI": 0.2375,
    "diversificationScore": 76,
    "effectiveHoldings": 4.21
  },
  "findings": [
    {
      "rule": "weights-sum-sanity",
      "severity": "info",
      "why": "Weights should sum to approximately 1.0.",
      "evidence": "sum=1",
      "fix": null
    },
    {
      "rule": "single-position-concentration",
      "severity": "info",
      "why": "No position exceeds 25%.",
      "evidence": "maxWeight=0.35",
      "fix": null
    }
  ],
  "breakdown": {
    "bySector": {
      "Technology": {
        "weight": 0.25,
        "count": 1
      },
      "Bonds": {
        "weight": 0.35,
        "count": 1
      }
    },
    "topPositions": [
      {
        "symbol": "BND",
        "weight": 0.35
      },
      {
        "symbol": "AAPL",
        "weight": 0.25
      }
    ]
  }
}

Input schema

Top-level request fields. Nested shapes are shown in the example above and the OpenAPI spec.

FieldTypeRequiredDescription
holdingsarrayYesList of positions with symbol, weight (0-1), optional returns[], sector, assetClass.
periodReturnsarray—Optional time series of portfolio or market period returns (preferred for volatility/sharpe/MDD).
riskFreeRatenumber—Optional risk-free rate for Sharpe (default 0).

How to call it over x402

  1. 1. Send the request. The first unpaid call returns HTTP 402 with an x402 payment challenge — $0.15, USDC on Base, and the recipient.
  2. 2. Pay per call. Your x402 client signs the USDC payment and retries automatically — no API key, no account, no subscription. New to x402?
  3. 3. Read the result. HTTP 200 returns the computed values plus evidence-backed findings.

With the x402 fetch client (Node / TypeScript)

import { wrapFetchWithPayment } from "@x402/fetch";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.AGENT_WALLET_KEY);
const pay = wrapFetchWithPayment(fetch, account); // USDC on Base

const res = await pay("https://hermesplant.com/api/agent-services/portfolioguard/score", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
  "holdings": [
    {
      "symbol": "AAPL",
      "weight": 0.25,
      "sector": "Technology"
    },
    {
      "symbol": "BND",
      "weight": 0.35,
      "sector": "Bonds"
    },
    {
      "symbol": "GLD",
      "weight": 0.15,
      "sector": "Commodity"
    },
    {
      "symbol": "VTI",
      "weight": 0.25,
      "sector": "Equity"
    }
  ],
  "periodReturns": [
    0.01,
    -0.004,
    0.007,
    0.002,
    -0.01
  ],
  "riskFreeRate": 0
}),
});

const result = await res.json();

Inspect the 402 with curl

curl -i -X POST https://hermesplant.com/api/agent-services/portfolioguard/score \
  -H "content-type: application/json" \
  -d '{"holdings":[{"symbol":"AAPL","weight":0.25,"sector":"Technology"},{"symbol":"BND","weight":0.35,"sector":"Bonds"},{"symbol":"GLD","weight":0.15,"sector":"Commodity"},{"symbol":"VTI","weight":0.25,"sector":"Equity"}],"periodReturns":[0.01,-0.004,0.007,0.002,-0.01],"riskFreeRate":0}'
# → HTTP/1.1 402 Payment Required  (x402 challenge: price, USDC asset, Base network, recipient)
# → sign the USDC-on-Base payment and retry to receive HTTP 200

Prefer no wallet? Get a free API key (250 calls/mo) and send it as X-API-Key instead of signing an x402 payment — the same call, no crypto, ideal for looping over many records.

Prefer zero code? This endpoint is also exposed as a tool on the Hermes Plant MCP server, so an MCP-capable agent can call it with its own x402 wallet.

Other agent services

Agent Action Safety Quick Gate$0.01

A one-cent safety gate for every consequential agent action.

Agent Action Safety Loop$0.25

Score, triage, receipt, and status in one agent-safety workflow.

x402 Demand Provenance Check$0.05

Separate candidate demand from owner-funded and duplicate x402 activity.

Assurance Attest$0.05

A signed, verifiable receipt for every action your agent takes.

Payment Policy Decision API$0.05

Decide whether an agent should pay before it signs.

Evidence Verification API$0.05

Verify the evidence bundle before trusting a paid agent result.

MCP Server Risk Analyzer$0.05

Score an MCP server before your agent installs it.

DestructGuard Command Score$0.10

Catch destructive agent commands before they run.

ReviewQueue Agent Submit$0.25

Route risky agent actions to human approval.

EmailGuard$0.02

Validate & normalize every contact record your agent touches.

WalletGuard$0.10

Per-wallet AML screening inside your agent's loop.

CashflowLens$0.20

NPV, IRR, XIRR & DCF valuation in a single call.

WaterfallLens$0.25

LP/GP distribution waterfalls, solved exactly.

OptionLens$0.25

Black-Scholes option pricing with the full Greeks.

BondLens$0.25

Yield, duration, convexity & loan amortization.

DealAnalyzer$0.25

Full deal underwriting — DCF, returns, sensitivity & waterfall in one call.

Agent Spend Assurance$0.25

One signed preflight for an autonomous x402 payment: WalletGuard counterparty screening, Payment Policy challenge validation, and structured evidence verification.

Investment Evidence Bundle$0.25

CashflowLens return and DCF analytics plus PortfolioGuard concentration and risk scoring in one paid call, with structured internal evidence and a tamper-evident signed receipt.

Start first paid call stepsAPI docs← All agent services

Need a calculator that isn’t here yet? contact@hermesplant.com