WaterfallLens

$0.30/call

LP/GP distribution waterfalls, solved exactly.

POST /api/agent-services/waterfall/distribute

financewaterfallprivate-equitycarried-interestpreferred-returnlp-gpreal-estatex402agent

What it does

Deterministic LP/GP distribution waterfall for private equity, venture, and real estate. Allocates distributable cash through the standard tiers — return of capital, preferred return (hurdle), GP catch-up, and carried-interest split — and returns the exact LP/GP split, per-tier breakdown, LP MOIC, GP carry, and effective carry %, with evidence-backed findings. The GP catch-up is solved so the GP lands at exactly its carry % of total profit. Pure math from caller-provided terms — no data feed, no fabrication.

Return of capital → preferred → catch-up → carry
Exact effective carry %, per-tier breakdown
Compounded or simple preferred return

Example request

POST /api/agent-services/waterfall/distribute

{
  "contributedCapital": 1000000,
  "distributable": 2000000,
  "carryPercentage": 0.2,
  "catchUpPercentage": 1,
  "preferredRate": 0.08,
  "years": 5,
  "compounding": "compounded"
}

Example response (HTTP 200)

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

{
  "service": "waterfall",
  "requestId": "wf-1a2b3c4d",
  "preferredReturn": 469328.08,
  "summary": {
    "totalDistributable": 2000000,
    "lpDistribution": 1800000,
    "gpDistribution": 200000,
    "lpProfit": 800000,
    "totalProfit": 1000000,
    "lpMultiple": 1.8,
    "gpCarry": 200000,
    "effectiveGpCarryPct": 0.2
  },
  "tiers": [
    {
      "tier": 1,
      "name": "return-of-capital",
      "lp": 1000000,
      "gp": 0,
      "total": 1000000
    },
    {
      "tier": 2,
      "name": "preferred-return",
      "lp": 469328.08,
      "gp": 0,
      "total": 469328.08
    },
    {
      "tier": 3,
      "name": "gp-catch-up",
      "lp": 0,
      "gp": 117332.02,
      "total": 117332.02
    },
    {
      "tier": 4,
      "name": "carried-interest-split",
      "lp": 330671.92,
      "gp": 82667.98,
      "total": 413339.9
    }
  ],
  "findings": [
    {
      "rule": "summary",
      "severity": "info",
      "why": "Effective GP carry as a share of total profit, with the preferred-return basis used.",
      "evidence": "effectiveGpCarryPct=0.2131 preferredBasis=compounded",
      "fix": null
    }
  ]
}

Input schema

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

Field	Type	Required	Description
contributedCapital	number	Yes	Total LP capital to be returned in tier 1 (required, > 0).
distributable	number	Yes	Total cash available to distribute through the waterfall (required, >= 0).
carryPercentage	number	—	GP carried interest as a fraction, e.g. 0.20 for 20% (default 0.20).
catchUpPercentage	number	—	GP share of distributions during the catch-up tier: 1.0 = full (100%) catch-up (default), 0 = no catch-up. Must exceed carryPercentage for a standard catch-up.
preferredReturnAmount	number	—	Explicit preferred-return (hurdle) dollar amount. Overrides preferredRate/years if given.
preferredRate	number	—	Annual preferred-return rate, e.g. 0.08 for 8%. Used with years when preferredReturnAmount is absent.
years	number	—	Holding period in years over which the preferred return accrues.
compounding	string	—	How the preferred return accrues from preferredRate/years: 'compounded' (default) or 'simple'.

How to call it over x402

1. Send the request. The first unpaid call returns HTTP 402 with an x402 payment challenge — $0.30, USDC on Base, and the recipient.
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. 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/waterfall/distribute", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
  "contributedCapital": 1000000,
  "distributable": 2000000,
  "carryPercentage": 0.2,
  "catchUpPercentage": 1,
  "preferredRate": 0.08,
  "years": 5,
  "compounding": "compounded"
}),
});

const result = await res.json();

Inspect the 402 with curl

curl -i -X POST https://hermesplant.com/api/agent-services/waterfall/distribute \
  -H "content-type: application/json" \
  -d '{"contributedCapital":1000000,"distributable":2000000,"carryPercentage":0.2,"catchUpPercentage":1,"preferredRate":0.08,"years":5,"compounding":"compounded"}'
# → 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 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.