# We > Ultrarich API

How much is a billion dollars, really? This API turns abstract sums into concrete,
quotable figures — how long the money would last, how tall it would stack, what it
could buy, how fast it grows untouched — and sets one person's wealth against
another's.

We > Ultrarich is a public-interest project, operated noncommercially, that presents
billionaire and trillionaire fortunes in tangible expressions and personalized
comparisons. Its goal is to make the scale of extreme wealth inequality
comprehensible, shareable, and a spur to action.

The API is free, requires no authentication, is read-only, and requests no account or
personal information. Every result it returns is licensed CC BY 4.0 and is free to
reuse for any purpose, including commercially, with [attribution](#attribution).
There is no paywall and no ads.

| | |
|---|---|
| **Origin** | `https://api.wegtultrarich.org` — hosts the spec, the MCP server, and agent files |
| **REST Base URL** | `https://api.wegtultrarich.org/v1` — all endpoint paths below are relative to this |
| **MCP Endpoint** | `https://api.wegtultrarich.org/mcp` — Streamable HTTP, no auth |

Last Updated 5 August 2026

## Contents

- [Quick Start](#quick-start)
- [Endpoints](#endpoints)
- [Money Values](#money-values)
- [Response Format](#response-format)
- [Using Results Well](#using-results-well)
- [Errors](#errors)
- [Access And Rate Limits](#access-and-rate-limits)
- [Attribution](#attribution)
- [Expression Reference](#expression-reference)
- [MCP Server](#mcp-server)
- [For LLMs And Agents](#for-llms-and-agents)
- [Discovery And Governance](#discovery-and-governance)
- [Licensing And Naming](#licensing-and-naming)

## Quick Start

One call, no key, no signup. This compares two wealths and returns both results plus
the ratio between them:

```bash
curl "https://api.wegtultrarich.org/v1/comparison?expression=durationOfDailySpend&wealthYours=100K&wealthTheirs=100B&spend=1000"
```

You get back three ready-to-quote sentences:

> **Theirs** — A person with a wealth of $100,000,000,000 could spend $1,000 every day for 274 millennia (273,973 years)!
>
> **Yours** — A person with a wealth of $100,000 could spend $1,000 every day for 100 days!
>
> **Ratio** — Their wealth is 1,000,000 times yours. *That's extreme wealth inequality.*

Publish any of that and include the attribution line:

```
Source: We > Ultrarich (wegtultrarich.org).
```

Three things to know before you go further:

1. **Quote the prose fields.** `sentence`, `phrase`, and `scale` are the product.
   `value` is raw and unformatted — use it for your own arithmetic, not for display.
   See [Using Results Well](#using-results-well).
2. **`scale` can be null.** Always branch on it. Never print `null`.
3. **Money values accept shorthand.** `1000000000`, `1,000,000,000`, and `1B` are the
   same value. Words are not. See [Money Values](#money-values).

## Endpoints

All paths are relative to the REST Base URL `https://api.wegtultrarich.org/v1`, and
all are `GET`.

| Answers | Path | Required parameters |
|---|---|---|
| How long the money would last | [`/durationOfDailySpend`](#duration-of-daily-spend) | `wealth`, `spend` |
| How tall the money would stack | [`/heightOfMoneyStack`](#height-of-money-stack) | `wealth`, `typeOfMoney` |
| What the money could buy | [`/numberOfItems`](#number-of-items-paid-for) | `wealth`, `typeOfItem` |
| How much it grows untouched | [`/growthOfCompoundInterest`](#growth-of-compound-interest) | `wealth`, `rate`, `frequency`, `period` |
| Two wealths compared, with ratio | [`/comparison`](#full-comparison-of-two-wealths) | `expression`, `wealthYours`, `wealthTheirs`, plus that expression's own parameters |
| Which routes exist | [`/expressions`](#list-available-expressions) | none |

Prefer `/comparison` whenever you have both wealths. It returns both results and the
direction-aware ratio in a single call, and the ratio is usually the part that lands.

## Money Values

Four parameters take money values: `wealth`, `wealthYours`, `wealthTheirs`, and
`spend`. They all share this contract.

**Accepted notations**

- Plain numbers — `1000000000`
- Grouped numbers in US or European convention — `1,000,000,000`, `1.000.000.000`
- Decimal fractions in either convention — `1,000,000.50`, `1.000.000,50`
- Case-insensitive magnitude suffixes — `K`, `M`, `B`, `T`, `Q` (e.g. `1B`, `1b`)
- Surrounding whitespace, which is ignored

**Requirements**

- Must contain digits. `one billion` is not valid — convert it before calling.
- Must be at least `1`. Zero and negative values have their own error categories.

**Currency**

Currency is a symbol prefix on the value itself, not a separate parameter, and it is a
**label only** — no exchange rate is ever applied.

- Defaults to USD when no symbol is given.
- `$` and `%24` are both valid for an ASCII dollar sign.
- Other symbols must be URL-encoded: `%E2%82%AC` is valid, a literal `€` is not. Most
  HTTP clients reject literal non-ASCII in a URL before the request is ever sent.
- For `/heightOfMoneyStack`, the currency implied by `typeOfMoney` overrides whatever
  symbol you prefixed.

**Two traps worth internalising**

1. **Shell interpolation eats `$`.** Inside a double-quoted shell command, an
   unencoded `$` is consumed by the shell, so the server receives a bare magnitude
   letter and returns `Wealth Malformed`. Use `%24`, or single-quote the URL.
2. **Q-scale values are approximate.** Values at `Q` scale exceed float64's
   exact-integer range, so `value` is approximate in its last few digits. Another
   reason to quote the prose fields rather than the number.

Rejections are categorised — see [Errors](#errors).

## Response Format

Every expression returns a `data` object with six fields.

| Field | Type | Purpose |
|---|---|---|
| `value` | `number` | The raw numeric result. For your own calculations, not for display. |
| `unit` | `string \| null` | The unit of `value`. |
| `type` | `string \| null` | The result subtype — kind of stacked money, kind of item, or null. |
| `phrase` | `string` | A short title-cased statement of the result, for use as a standalone label. |
| `sentence` | `string` | A complete sentence-cased statement, for quoting or display as inline prose. |
| `scale` | `string \| null` | Sentence-cased real-world context. **Null when the result is too small to have a meaningful real-world anchor.** |

Successful responses are wrapped in an envelope:

```json
{"status":"success","data":{ ... }}
```

`/comparison` returns `expression`, `resultYours`, and `resultTheirs` (each in the
format above) plus a `ratio` object — see
[Full Comparison Of Two Wealths](#full-comparison-of-two-wealths).

`/expressions` is the one endpoint whose `data` is an array rather than an object.

## Using Results Well

The prose fields are written to be quoted. Rebuilding them from `value` loses the
formatting, the rounding conventions, and the real-world anchor.

- **Quote `sentence`.** It is usually what you want. `phrase` suits headings and
  cards; `scale` adds the "for scale" line.
- **Branch on `scale`.** It is nullable by design. Never print `null`, and don't
  invent your own comparison to fill the gap — omit the line.
- **Don't re-round.** The prose fields already apply the project's rounding
  conventions. Re-rounding `value` yourself produces figures that disagree with the
  `sentence` you are quoting beside them.
- **These are calculations, not estimates.** Every result is deterministic arithmetic
  from published formulas. Present them as computed figures. Any uncertainty lives in
  the wealth values you supply, in the approximate U.S. benchmark item prices, or in
  the approximate nature of some real-world scale references — not in the arithmetic.
- **This is not a source of net worth figures.** It computes from values *you*
  supply. For headline figures — billionaire counts, total wealth, UHNWI populations
  — use the maintained dataset at <https://wegtultrarich.org/data/> and cite the
  `metric_id`.

## Errors

### 400 — Request Error

```json
{"status":"error","error":{"code":400,"message":"Wealth Malformed"}}
```

The message names the offending parameter and then the category, so it tells you both
which parameter to fix and why. **Parameter names appear in prose, not camelCase:**

| In the message | Parameter |
|---|---|
| `Wealth` | `wealth` |
| `Your Wealth` | `wealthYours` |
| `Their Wealth` | `wealthTheirs` |
| `Spend` | `spend` |
| `Type Of Money` | `typeOfMoney` |
| `Type Of Item` | `typeOfItem` |
| `Rate` | `rate` |
| `Frequency` | `frequency` |
| `Period` | `period` |
| `Expression` | `expression` |

**Money parameters** (`wealth`, `wealthYours`, `wealthTheirs`, `spend`) return one of
six categories:

| Category | Cause | Example message |
|---|---|---|
| `Missing` | Absent or empty value, or a bare currency symbol | `Wealth Missing` |
| `Malformed` | A magnitude letter with no digits (e.g. `wealth=B`) | `Wealth Malformed` |
| `Invalid` | Non-money input | `Spend Invalid` |
| `Not-a-Number` | Legal tokens in an illegal order | `Their Wealth Not-a-Number` |
| `Zero` | A value of zero | `Wealth Zero` |
| `Negative` | A value below zero | `Spend Negative` |

**`rate` and `period`** return `Missing`, `Malformed`, `Invalid`, or `Outside Range`.
Their bounds are exclusive and are never clamped. `Invalid` names the excluded bound
the value landed on exactly — `Rate Invalid (0)`, `Rate Invalid (1)`,
`Period Invalid (0)`, `Period Invalid (100)` — while a value past a bound returns
`Rate Outside Range` or `Period Outside Range`.

**Enum parameters** (`typeOfMoney`, `typeOfItem`, `frequency`, `expression`) return
`Missing` or `Invalid` — e.g. `Type Of Money Invalid`, `Expression Invalid`.

Some representative rejections:

```bash
curl "https://api.wegtultrarich.org/v1/durationOfDailySpend?wealth=B&spend=1K"
# {"status":"error","error":{"code":400,"message":"Wealth Malformed"}}

curl "https://api.wegtultrarich.org/v1/durationOfDailySpend?wealth=1B&spend=-1,000"
# {"status":"error","error":{"code":400,"message":"Spend Negative"}}

curl "https://api.wegtultrarich.org/v1/comparison?expression=durationOfDailySpend&wealthTheirs=100B&spend=1000"
# {"status":"error","error":{"code":400,"message":"Your Wealth Missing"}}

curl "https://api.wegtultrarich.org/v1/comparison?expression=stackOfPancakes&wealthYours=100K&wealthTheirs=100B"
# {"status":"error","error":{"code":400,"message":"Expression Invalid"}}

curl "https://api.wegtultrarich.org/v1/growthOfCompoundInterest?wealth=1B&rate=1&frequency=1&period=20"
# {"status":"error","error":{"code":400,"message":"Rate Invalid (1)"}}

curl "https://api.wegtultrarich.org/v1/growthOfCompoundInterest?wealth=1B&rate=2&frequency=1&period=20"
# {"status":"error","error":{"code":400,"message":"Rate Outside Range"}}
```

### 429 — Rate Limit Exceeded

A rate-limit response carries code `429`, not `400`, and two fields the 400 envelope
does not have — `details` and `retryAfter`:

```json
{"status":"error","error":{"code":429,"message":"Too Many Requests","details":"Rate limit exceeded. Try again in 60 seconds.","retryAfter":60}}
```

It also sets a `Retry-After` response header. Both `retryAfter` and the header give
the seconds remaining until the window resets, and both agree with `RateLimit-Reset`.
The full header family is documented under [Access And Rate Limits](#access-and-rate-limits) 
— it appears on every response, not just this one.

### Status Codes

| Code | Meaning |
|---|---|
| `200` | Success |
| `400` | Request error — read the message |
| `429` | Rate limit exceeded — retry in the next window |

## Access And Rate Limits

No authentication. No account. No personal information requested. Technical request
data is processed transiently for rate limiting, security, and operations, and the
site uses only basic privacy-first analytics. See the [Privacy Policy](https://wegtultrarich.org/privacy-policy.html).

Every endpoint sends `Access-Control-Allow-Origin: *`, so browser-side code —
including generated artifacts and canvases — can call it directly.

Rate limits are per IP:

| Surface | Limit |
|---|---|
| All `/v1` endpoints (shared) | 100 requests/minute |
| MCP server | 300 requests/minute |
| Docs | 500 requests/minute |

Exceeding a limit returns [429](#429--rate-limit-exceeded).

**Every response carries its rate-limit state**, not only the ones that fail. Read
these and slow down before you're refused:

| Header | Example | Meaning |
|---|---|---|
| `RateLimit-Policy` | `100;w=60` | The quota and its window, in seconds |
| `RateLimit-Limit` | `100` | Requests permitted per window |
| `RateLimit-Remaining` | `0` | Requests left in the current window |
| `RateLimit-Reset` | `2` | Seconds until the window resets |

`X-RateLimit-Limit` and `X-RateLimit-Remaining` are legacy aliases carrying the same
values. `X-RateLimit-Reset` is the exception — it's a Unix epoch timestamp rather
than a count of seconds, and it rounds up where `RateLimit-Reset` rounds down, so
the two can disagree by a second. Prefer the unprefixed `RateLimit-*` family, and
treat `Retry-After` as authoritative on a 429.

Successful responses are cacheable (`max-age=3600`), and a response served from a
cache carries the `RateLimit-*` values from when it was stored. Use them as a hint,
not a ledger — a 429 is the authoritative signal.

Use of this API is subject to our [Terms Of Use](https://wegtultrarich.org/terms-of-use.html).
Content is licensed [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) — reuse it
anywhere, including commercially, with attribution.

## Attribution

Every result is licensed CC BY 4.0 and free to reuse, including commercially. In
exchange, attribute it. When you surface a figure to a user, include:

```
Source: We > Ultrarich (wegtultrarich.org).
```

MCP tool results embed an `attribution` field — use that string directly rather than
composing your own.

Write the name as `We > Ultrarich`, or `We Are Greater Than The Ultrarich` where `>`
won't render. Use `wegtultrarich` in identifiers.

## Expression Reference

Parameters shared across endpoints are documented once above: money values in
[Money Values](#money-values), response fields in
[Response Format](#response-format), rejections in [Errors](#errors).
`openapi.yaml` is normative for parameters and schemas.

### List Available Expressions

**`GET /expressions`** — no parameters. Lists the routes of the four wealth
expressions plus the comparison. Its `data` is an array, unlike every other endpoint.

```bash
curl "https://api.wegtultrarich.org/v1/expressions"
```

```json
{"status":"success","data":[{"route":"/v1/durationOfDailySpend"},{"route":"/v1/heightOfMoneyStack"},{"route":"/v1/numberOfItems"},{"route":"/v1/growthOfCompoundInterest"},{"route":"/v1/comparison"}]}
```

### Duration Of Daily Spend

**`GET /durationOfDailySpend`** — describes a wealth as the length of time a given
amount could be spent every day. The daily spending comparison type.

| Parameter | Type | | Description |
|---|---|---|---|
| `wealth` | `number \| string` | required | The amount of money to describe. [Money value](#money-values). |
| `spend` | `number \| string` | required | The amount spent daily — the crux of this expression. [Money value](#money-values). |

```bash
curl "https://api.wegtultrarich.org/v1/durationOfDailySpend?wealth=1B&spend=1000"
```

```json
{"status":"success","data":{"value":2739.72602739726,"unit":"years","type":null,"phrase":"2.7 Millennia (2,740 Years)","sentence":"A person with a wealth of $1,000,000,000 could spend $1,000 every day for 2.7 millennia (2,740 years)!","scale":"That's approximately 1.4 times as long ago as when modern religions began to take shape in what was considered ancient history (≈4,000 BCE to 1,000 AD)."}}
```

The same call in euros, showing the currency prefix URL-encoded. Note that the figures
are identical — the symbol is a label, not a conversion:

```bash
curl "https://api.wegtultrarich.org/v1/durationOfDailySpend?wealth=%E2%82%AC1,000,000,000&spend=1K"
```

```json
{"status":"success","data":{"value":2739.72602739726,"unit":"years","type":null,"phrase":"2.7 Millennia (2,740 Years)","sentence":"A person with a wealth of €1,000,000,000 could spend €1,000 every day for 2.7 millennia (2,740 years)!","scale":"That's approximately 1.4 times as long ago as when modern religions began to take shape in what was considered ancient history (≈4,000 BCE to 1,000 AD)."}}
```

### Height Of Money Stack

**`GET /heightOfMoneyStack`** — describes a wealth as the height of a stack of a given
kind of money. The physical size comparison type.

| Parameter | Type | | Description |
|---|---|---|---|
| `wealth` | `number \| string` | required | The amount of money to describe. [Money value](#money-values). |
| `typeOfMoney` | `enum` | required | The money to be stacked — the crux of this expression. One of the values below. |

Stack height = (wealth ÷ denomination) × thickness. No currency conversion is
performed, and the currency of `typeOfMoney` overrides any symbol given with `wealth`.

| Value | Money | Currency | Denomination | Thickness |
|---|---|---|---|---|
| `usd_1_coin` | Dollar Coins | USD | 1 | 2 mm |
| `usd_100_bill` | Hundred-Dollar Bills | USD | 100 | 0.11 mm |
| `cad_1_coin` | Loonies | CAD | 1 | 1.95 mm |
| `cad_100_bill` | Hundred-Dollar Bills | CAD | 100 | 0.0875 mm |
| `eur_1_coin` | Euro Coins | EUR | 1 | 2.33 mm |
| `eur_100_bill` | Hundred-Euro Bills | EUR | 100 | 0.12 mm |
| `gbp_1_coin` | Pound Coins | GBP | 1 | 2.8 mm |
| `gbp_100_bill` | Hundred-Pound Bills | GBP | 100 | 0.0825 mm |
| `cny_1_coin` | Yuan Coins | CNY | 1 | 1.85 mm |
| `cny_100_bill` | Hundred-Yuan Bills | CNY | 100 | 0.1 mm |
| `inr_1_coin` | Rupee Coins | INR | 1 | 1.45 mm |
| `inr_100_bill` | Hundred-Rupee Bills | INR | 100 | 0.11 mm |
| `krw_1_coin` | Won Coins | KRW | 1 | 1.45 mm |
| `krw_1000_bill` | Thousand-Won Bills | KRW | 1,000 | 0.1 mm |
| `rub_1_coin` | Ruble Coins | RUB | 1 | 1.5 mm |
| `rub_100_bill` | Hundred-Ruble Bills | RUB | 100 | 0.1 mm |
| `try_1_coin` | Lira Coins | TRY | 1 | 2 mm |
| `try_100_bill` | Hundred-Lira Bills | TRY | 100 | 0.105 mm |
| `chf_1_coin` | Franc Coins | CHF | 1 | 1.55 mm |
| `chf_100_bill` | Hundred-Franc Bills | CHF | 100 | 0.11 mm |
| `brl_1_coin` | Real Coins | BRL | 1 | 1.95 mm |
| `brl_100_bill` | Hundred-Real Bills | BRL | 100 | 0.105 mm |

```bash
curl "https://api.wegtultrarich.org/v1/heightOfMoneyStack?wealth=1B&typeOfMoney=usd_1_coin"
```

```json
{"status":"success","data":{"value":2000000,"unit":"meters","type":"dollar coins","phrase":"1,243 Miles (2,000 km)","sentence":"A person with a wealth of $1,000,000,000 would have a stack of dollar coins 1,243 miles (2,000 km) high!","scale":"That's about 10 times the distance of a roundtrip to the edge of space (Kármán Line)."}}
```

### Number Of Items Paid For

**`GET /numberOfItems`** — describes a wealth as the number of a given item that could
be bought or paid off. The purchasing power comparison type.

> **Item prices are approximate U.S. benchmark prices denominated in USD.** A currency
> symbol supplied with a wealth value changes the currency label shown in the result;
> it does not convert or localize the item prices. Until localized item sets are
> introduced, use USD wealth values for the most meaningful purchasing-power results.

| Parameter | Type | | Description |
|---|---|---|---|
| `wealth` | `number \| string` | required | The amount of money to describe. [Money value](#money-values). |
| `typeOfItem` | `enum` | required | The item to be bought or paid off — the crux of this expression. One of the values below. |

| Value | Item | Benchmark price |
|---|---|---|
| `fancy_coffee` | Fancy Coffee | $10 |
| `quick_meal` | Quick Meal | $15 |
| `dinner_with_drinks` | Dinner With Drinks | $175 |
| `iphone` | iPhone | $1,400 |
| `month_of_childcare` | Month Of Childcare | $1,750 |
| `rent_or_mortgage_payment` | Rent Or Mortgage Payment | $3,000 |
| `year_of_low_minimum_wage_salary` | Year Of Low Minimum Wage Salary | $15,080 |
| `year_of_high_minimum_wage_salary` | Year Of High Minimum Wage Salary | $32,240 |
| `student_loan_debt` | Student Loan Debt | $40,000 |
| `car` | Car | $50,000 |
| `year_of_salary_65k` | Year Of $65,000 Salary | $65,000 |
| `year_of_salary_100k` | Year Of $100,000 Salary | $100,000 |
| `luxury_car` | Luxury Car | $275,000 |
| `house` | House | $500,000 |
| `yacht` | Yacht | $800,000 |
| `supercar` | Supercar | $4,000,000 |
| `island` | Island | $30,000,000 |
| `mansion` | Mansion | $75,000,000 |
| `estate_with_a_mega_mansion` | Estate With A Mega-Mansion | $200,000,000 |
| `luxury_island` | Luxury Island | $300,000,000 |
| `superyacht` | Superyacht | $600,000,000 |

```bash
curl "https://api.wegtultrarich.org/v1/numberOfItems?wealth=1B&typeOfItem=house"
```

```json
{"status":"success","data":{"value":2000,"unit":null,"type":"houses","phrase":"2,000 Houses","sentence":"A person with a wealth of $1,000,000,000 could buy 2,000 houses all at once!","scale":"That's approximately 1.3 times enough for every person in a village (typically between 1K–10K population)."}}
```

### Growth Of Compound Interest

**`GET /growthOfCompoundInterest`** — describes the growth that a wealth would produce
over a period of time at a given rate and compounding frequency. The compound interest
comparison type.

| Parameter | Type | | Description |
|---|---|---|---|
| `wealth` | `number \| string` | required | The amount of money to describe. [Money value](#money-values). |
| `rate` | `number` | required | The interest rate. Between 0 and 1, **exclusive**, where `0.01` = 1%. |
| `frequency` | `enum` | required | How often the wealth compounds. Exactly one of `1` (annually), `2` (semiannually), `4` (quarterly), `12` (monthly), `365` (daily). |
| `period` | `number` | required | Duration in years. Between 0 and 100, **exclusive**. |

The bounds on `rate` and `period` are exclusive and are never clamped. A value sitting
exactly on an excluded bound returns `Invalid`; a value beyond it returns
`Outside Range`. See [Errors](#errors).

```bash
curl "https://api.wegtultrarich.org/v1/growthOfCompoundInterest?wealth=1B&rate=0.01&frequency=1&period=20"
```

```json
{"status":"success","data":{"value":220190040,"unit":"dollars","type":null,"phrase":"By $220,190,040 Over 20 Years","sentence":"With 1% interest compounded annually, a person with $1,000,000,000 would grow their wealth by $220,190,040 over 20 years!","scale":"This growth in their wealth — not the principal, just the interest they earned during this single period of time — is approximately 2.2 times the annual recurring revenue goal for a best-in-class startup company (≈$100M)."}}
```

### Full Comparison Of Two Wealths

**`GET /comparison`** — computes any expression for two wealths and returns both
results plus the ratio between them. A complete "them vs. you" comparison in one call.

| Parameter | Type | | Description |
|---|---|---|---|
| `expression` | `enum` | required | The expression to compute for both wealths. See below. |
| `wealthYours` | `number \| string` | required | The user's ("your") wealth. [Money value](#money-values). |
| `wealthTheirs` | `number \| string` | required | The ultrarich ("their") wealth. [Money value](#money-values). |

`expression` must be one of the following, and each also requires that expression's own
parameters:

| Value | Also requires |
|---|---|
| `durationOfDailySpend` | `spend` |
| `heightOfMoneyStack` | `typeOfMoney` |
| `numberOfItems` | `typeOfItem` |
| `growthOfCompoundInterest` | `rate`, `frequency`, `period` |

**Response.** In addition to echoing `expression`, the `data` object contains
`resultYours` and `resultTheirs` — each in the standard
[response format](#response-format) — plus a `ratio` object with four fields.

| Field | Type | Purpose |
|---|---|---|
| `ratio.value` | `number` | The raw ratio of `wealthTheirs` to `wealthYours`. **A value below 1 means `wealthYours` is the larger.** |
| `ratio.phrase` | `string` | A short title-cased statement of the ratio, with the 1 on the smaller side. |
| `ratio.sentence` | `string` | A direction-aware summary, already phrased correctly whichever way the comparison runs. |
| `ratio.scale` | `string \| null` | An assessment of the ratio, tiered by magnitude. Nullable — branch on it. |

> Ratios of 200:1 or more are described as extreme wealth inequality. **The 200:1
> threshold is ours** — a rounded contextual figure informed by the roughly 190:1
> global disparity reported in
> [our cited source](https://www.imf.org/en/publications/fandd/issues/2022/03/global-inequalities-stanley).
> It is not an official IMF definition and shouldn't be attributed as one.

```bash
curl "https://api.wegtultrarich.org/v1/comparison?expression=durationOfDailySpend&wealthYours=100K&wealthTheirs=100B&spend=1000"
```

```json
{
  "status": "success",
  "data": {
    "expression": "durationOfDailySpend",
    "resultTheirs": {
      "value": 273972.602739726,
      "unit": "years",
      "type": null,
      "phrase": "274 Millennia (273,973 Years)",
      "sentence": "A person with a wealth of $100,000,000,000 could spend $1,000 every day for 274 millennia (273,973 years)!",
      "scale": "That's approximately 1.6 times as long ago as when Homo Sapiens began wearing primitive clothing (≈170K BCE)."
    },
    "resultYours": {
      "value": 0.273972602739726,
      "unit": "years",
      "type": null,
      "phrase": "100 Days",
      "sentence": "A person with a wealth of $100,000 could spend $1,000 every day for 100 days!",
      "scale": null
    },
    "ratio": {
      "value": 1000000,
      "phrase": "1,000,000 : 1",
      "sentence": "Their wealth is 1,000,000 times yours.",
      "scale": "That's extreme wealth inequality."
    }
  }
}
```

Note `resultYours.scale` is `null` here — omit that line rather than printing it.

When `wealthYours` is the larger, the ratio inverts and the prose adapts. With
`wealthYours=10B&wealthTheirs=1B`:

```json
"ratio": {
  "value": 0.1,
  "phrase": "1 : 10",
  "sentence": "Your wealth is 10 times theirs.",
  "scale": "That's wealth inequality."
}
```

## MCP Server

The API is also available as a Model Context Protocol server.

| | |
|---|---|
| **Endpoint** | `https://api.wegtultrarich.org/mcp` |
| **Transport** | Streamable HTTP |
| **Authentication** | None |
| **Rate limit** | 300 requests/minute per IP |
| **Protocol Revisions** | `2026-07-28` and `2025-11-25`, selected per request |
| **Session State** | None — no `Mcp-Session-Id`, no initialize handshake |

It exposes five tools. **Tool names are snake_case, but their input fields use the
same camelCase parameter names as the REST API.**

| Tool | REST equivalent |
|---|---|
| `duration_of_daily_spend` | `/v1/durationOfDailySpend` |
| `height_of_money_stack` | `/v1/heightOfMoneyStack` |
| `number_of_items` | `/v1/numberOfItems` |
| `growth_of_compound_interest` | `/v1/growthOfCompoundInterest` |
| `comparison` | `/v1/comparison` |

Most notable is `comparison`, which computes any expression for two wealths and
returns both results and their ratio in a single call.

**The response envelope differs from REST.** A tool result is the bare data object
with an added `attribution` field — it is *not* wrapped in `{status, data}`, and there
is no `status` field to check. Check the error flag your client exposes instead:

- Native MCP SDK / result model — `CallToolResult.isError`
- Anthropic Messages API connector — `mcp_tool_result.is_error`

The presence of expected fields such as `ratio` gives an additional success check.

### Protocol Revisions

Both `2026-07-28` and `2025-11-25` are answered from the same endpoint. Clients
select a revision per request; nothing is configured on your side and no client
action is needed.

Tool names, input fields, and the data payload are identical under both. The
protocol envelope differs:

- **Cacheable catalogue.** On `2026-07-28`, `tools/list` carries `ttlMs`
  (<VALUE>) and `cacheScope: public`. The five tools never vary by caller, so
  cache the list for the advertised TTL — `tools/list` counts against the same
  300 req/min budget as tool calls.
- **Required headers.** `2026-07-28` requests must carry `Mcp-Method` and
  `Mcp-Name`. SDKs set these for you; hand-rolled HTTP callers must send them,
  and the server rejects requests whose headers and body disagree.
- **`resultType`.** Results on `2026-07-28` carry this field. Every result from
  this server is `complete` — no tool here uses Multi Round-Trip Requests.

### Connecting

The endpoint is `https://api.wegtultrarich.org/mcp`. It uses Streamable HTTP and
requires no authentication and no API key.

Most MCP-capable clients accept that URL directly. The steps below were last
verified against official client documentation in July 2026 — client names,
menus, and plan requirements change often, so follow the linked docs if what
you see doesn't match.

**Command Line**

```bash
# Claude Code — add --scope user to make it available in every project
claude mcp add --transport http wegtultrarich https://api.wegtultrarich.org/mcp

# Codex CLI
codex mcp add wegtultrarich --url https://api.wegtultrarich.org/mcp

# Gemini CLI — default scope is the current project; add -s user for all projects
gemini mcp add --transport http wegtultrarich https://api.wegtultrarich.org/mcp
```

Docs: [Claude Code](https://code.claude.com/docs/en/mcp) ·
[Codex CLI](https://developers.openai.com/codex/mcp) ·
[Gemini CLI](https://github.com/google-gemini/gemini-cli)

**Config File**

```jsonc
// Cursor — ~/.cursor/mcp.json (global) or .cursor/mcp.json (project)
{ "mcpServers": { "wegtultrarich": { "url": "https://api.wegtultrarich.org/mcp" } } }

// VS Code — mcp.json; note the `servers` key and the required `type`
{ "servers": { "wegtultrarich": { "type": "http", "url": "https://api.wegtultrarich.org/mcp" } } }

// Windsurf — ~/.codeium/windsurf/mcp_config.json
{ "mcpServers": { "wegtultrarich": { "serverUrl": "https://api.wegtultrarich.org/mcp" } } }
```

Docs: [Cursor](https://cursor.com/docs/mcp) ·
[VS Code](https://code.visualstudio.com/docs/agent-customization/mcp-servers) ·
[Windsurf](https://docs.windsurf.com/windsurf/cascade/mcp)

**Chat Clients**

- **Claude** (web, desktop, mobile, Cowork) — Settings » Connectors » 
  Add custom connector › Name = `We > Ultrarich`, URL as above › Add. On Team
  and Enterprise, an Owner adds it first under Organization settings ›
  Connectors › Add › Custom › Web; members then click Connect. Free accounts
  are limited to one custom connector.
  [Docs](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)
- **ChatGPT** — added as a custom MCP connector with Developer mode enabled
  (Settings › Apps › Advanced settings › Developer mode; beta, web only, paid
  plans). On Business, Enterprise, and Edu workspaces, an admin controls
  whether Developer mode is available.
  [Docs](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt)

**Anything Else** — any client supporting remote Streamable HTTP MCP works with
the URL directly.

To inspect: `npx @modelcontextprotocol/inspector`, transport "Streamable HTTP".

### Calling Via The Anthropic Messages API

If you're invoking these tools through the Anthropic Messages API rather than an
MCP client, two extra request elements are required — **without both, the
server's tools won't be available to the model.**

1. The beta header `anthropic-beta: mcp-client-2025-11-20` (an Anthropic API beta flag, 
   unrelated to the MCP revision 2025-11-25the earlier), `mcp-client-2025-04-04` is deprecated
2. An `mcp_toolset` entry in `tools` for each server in `mcp_servers`

```javascript
const MODEL = "claude-sonnet-4-6"; // any current model; not part of this server's contract

body: JSON.stringify({
  model: MODEL,
  max_tokens: 1000,
  messages: [{ role: "user", content: "Compare $193K and $250B via durationOfDailySpend." }],
  mcp_servers: [
    { type: "url", url: "https://api.wegtultrarich.org/mcp", name: "wegtultrarich" }
  ],
  tools: [
    { type: "mcp_toolset", mcp_server_name: "wegtultrarich" }
  ]
})
```

`name` and `mcp_server_name` are local labels — any value, as long as they match.
Each server you use needs a corresponding toolset entry.

Inside claude.ai artifacts no API key is needed; the user sees a one-time
connector-consent dialog before the first tool call.

**Parsing The Response.** The reply's `content` array contains blocks of several
types. Find them by `type`, never by position: `mcp_tool_use` shows the
invocation, `mcp_tool_result` carries the data.

## For LLMs And Agents

Free, no-auth, read-only, computation-only. Four wealth expressions plus one complete
comparison, for making extreme wealth and extreme wealth inequality legible.

- **REST Base URL** — `https://api.wegtultrarich.org/v1` (paths below are relative to it)
- **Endpoints (GET)** — `/durationOfDailySpend`, `/heightOfMoneyStack`, `/numberOfItems`, `/growthOfCompoundInterest`, `/comparison`, `/expressions`
- **Spec** — `https://api.wegtultrarich.org/openapi.yaml` (normative for parameters and schemas)
- **MCP** — `https://api.wegtultrarich.org/mcp`, Streamable HTTP, five snake_case tools with camelCase input fields; results are the bare data object plus `attribution`, not the REST envelope; speaks protocol revisions 2026-07-28 and 2025-11-25
- **Money values** — plain (`1000000000`), formatted (`1,000,000,000`), or suffixed (`1B`). Words are not valid; convert first. Currency is a symbol prefix and a label only, never a conversion. [Details](#money-values)
- **Responses** — `{status, data}`; each result has `value`, `unit`, `type`, `phrase`, `sentence`, `scale`. Quote the prose; `scale` is nullable, so branch on it. [Details](#using-results-well)
- **Errors** — `{status, error:{code, message}}`; the message names the parameter in prose and then the category. [Catalogue](#errors)
- **Rate limits** — 100/min per IP across `/v1`, 300/min for MCP; 429 carries `retryAfter` and a `Retry-After` header
- **Attribution** — `Source: We > Ultrarich (wegtultrarich.org).`

Task-oriented guidance on *using the results well* lives in
[agent-prompt.md](https://api.wegtultrarich.org/prompts/agent-prompt.md). The complete
reference — every enum value, constant, and formula — lives in
[llms-full.txt](https://wegtultrarich.org/llms-full.txt).

## Discovery And Governance

Machine-readable entry points, for agents and for tooling:

- [apis.json](https://api.wegtultrarich.org/apis.json) — APIs.json 0.21 index of everything below
- [openapi.yaml](https://api.wegtultrarich.org/openapi.yaml) — OpenAPI 3.0.4 specification
- [agent-prompt.md](https://api.wegtultrarich.org/prompts/agent-prompt.md) — how to call this API well, written for agents
- [spectral.yaml](https://api.wegtultrarich.org/governance/spectral.yaml) — the governance rules the spec is linted against
- [llms.txt](https://wegtultrarich.org/llms.txt) / [llms-full.txt](https://wegtultrarich.org/llms-full.txt) — project summary and full agent reference

### Documentation Authority

1. `openapi.yaml` is normative for REST paths, parameters, schemas, status codes, and response structures.
2. This README is the explanatory reference for behavior, examples, and MCP access.
3. The MCP repository README will be the canonical client-setup guide once publicly accessible.
4. `agent-prompt.md` and `llms-full.txt` are derived task-oriented and curated guidance.
5. `llms.txt` and `apis.json` are discovery indexes.

## Licensing And Naming

We > Ultrarich ("We Are Greater Than The Ultrarich"), our wordmark, and our code are
copyright © 2026 Blonde Rocket Scientist LLC.

Our **content** — the figures, text, graphics, and dataset on our website as well as the 
results returned by our API and MCP server — is licensed under [CC BY 4.0](#attribution). 
Our **software**, including this API and MCP server, is not open source; see
[LICENSE.md](https://wegtultrarich.org/LICENSE.md) for details.

Write the name as `We > Ultrarich`, or `We Are Greater Than The Ultrarich` where `>`
won't render. Use `wegtultrarich` in identifiers. Full guide in
[LICENSE.md](https://wegtultrarich.org/LICENSE.md#name--wordmark--all-rights-reserved).

The project advocates reducing extreme wealth inequality but is not affiliated with
and does not endorse any specific measure, campaign, candidate, or party.

Canonical copies of [CHANGELOG.md](https://wegtultrarich.org/CHANGELOG.md),
[SECURITY.md](https://wegtultrarich.org/SECURITY.md), and
[LICENSE.md](https://wegtultrarich.org/LICENSE.md) are published on our website. Our
documentation-only GitHub organization, repository, and issue tracker are temporarily
unavailable pending GitHub account restoration.

Questions: info@wegtultrarich.org