API

The waterfall engine, inside your systems.

Send a cap table from your fund administration, portfolio monitoring or cap table platform. Get back who receives what, every breakpoint, and plain-language explanations: the same engine as the tool, exact to the cent.

Get API access Interactive reference

1. Get a key

On a Firm plan, or any paid plan with the API add-on, open your account and press Create a key. Copy it: it is shown once.

2. Send a cap table

POST JSON to an endpoint below with Authorization: Bearer wiq_.... Keep the key on your server, never in a web page.

3. Use the result

Every class's payout, per-share value, multiple and a sentence explaining it. The classes always add up to the equity value.

Endpoints

POST	What it returns
`/api/v1/waterfall`	Who receives what at one or more exit values (with debt, expenses and stock consideration per scenario).
`/api/v1/breakpoints`	Every exit value where the split of the next dollar changes, with the reason.
`/api/v1/curve`	Each class's payout across a range of exit values, for charts.
`/api/v1/explain`	A plain-language explanation of each class's result at one exit value.
`/api/v1/offers`	Offers with escrow and earnouts compared by cash at close, expected value and present value.
`/api/v1/check`	Another party's allocation checked, with the most likely reasons for any difference.
`GET /api/v1/usage`	Calls used and left this month (free).

Full field-by-field reference, with a "try it" button: /api/v1/docs.

Example: one investor, one sale

Series A invested $10M for 2,000,000 shares with a 1x participating preference; founders hold 8,000,000 shares. The company sells for $40M.

curl -X POST https://waterfalliq.com/api/v1/waterfall \
  -H "Authorization: Bearer $WATERFALLIQ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cap_table": {
      "company": "Acme Robotics",
      "securities": [
        {"id": "common", "name": "Founders", "kind": "common", "shares": 8000000},
        {"id": "series_a", "name": "Series A", "kind": "preferred", "invested": 10000000,
         "price": 5.0, "seniority": 1, "lp_multiple": 1, "participation": "participating"}
      ]
    },
    "scenarios": [{"exit_value": 40000000}]
  }'

The answer (shortened):

{
  "scenarios": [{
    "exit_value": 40000000.0,
    "equity_value": 40000000.0,
    "sentence": "At a $40.00M exit, $40.00M reaches equity holders: Founders $24.00M (60%), Investors $16.00M (40%).",
    "classes": [
      {"id": "common",   "name": "Founders", "total": 24000000.0, "pct_of_proceeds": 0.6, ...},
      {"id": "series_a", "name": "Series A", "total": 16000000.0, "pct_of_proceeds": 0.4, ...}
    ]
  }]
}

The same in Python

import os, requests

r = requests.post("https://waterfalliq.com/api/v1/waterfall",
                  headers={"Authorization": f"Bearer {os.environ['WATERFALLIQ_KEY']}"},
                  json=payload, timeout=30)
r.raise_for_status()
for c in r.json()["scenarios"][0]["classes"]:
    print(c["name"], round(c["total"], 2))
print("Calls left this month:", r.headers["X-Quota-Remaining"])

Cap table fields

Each security has an id, a name and a kind (preferred, common, option, warrant, safe or note), plus the terms that apply: shares, invested, price (issue price, or strike for options), seniority (1 is paid first; equal numbers share), lp_multiple, participation (non_participating, participating, participating_capped with cap_multiple), dividends, SAFE valuation_cap and discount, and note interest_rate. Anything left out takes the standard value. The reference lists every field.

Limits and errors

Status	Meaning
200	Done. `X-Quota-Remaining` says how many calls are left this month.
401	Missing, wrong or deleted key.
402	The account's plan does not include the API.
422	The cap table could not be calculated; the message says why (for example a post-money SAFE cap above 100%).
429	This month's calls are used up, or more than 120 calls in a minute.

Pricing

Firm includes 5,000 calls a month. On any other paid plan, the API add-on is $499 a month for 2,000 calls, then $199 for each extra 1,000. Enterprise plans set their own volume. Calls renew on the 1st of each month. Talk to us about volumes or a trial key.

Your cap tables are calculated and returned; the API does not keep them. See the privacy notice and how the engine is tested.