openapi: 3.0.4
info:
  title: We > Ultrarich API
  description: |
    We > Ultrarich (We Are Greater Than The Ultrarich) makes extreme wealth inequality tangible. It presents billionaire and trillionaire fortunes in personalized comparisons: Duration Of Daily Spend (Daily Spending), Height Of Stacked Money (Physical Size), Number Of Items Paid For (Purchasing Power), and Growth Of Compound Interest (Compound Interest).

    An MCP (Model Context Protocol) server exposing these operations as agent tools is available at https://api.wegtultrarich.org/mcp. The server answers both MCP revisions `2026-07-28` and `2025-11-25`.

    Free for any use, including commercial. Results are licensed CC BY 4.0 — please use the attribution "Source: We > Ultrarich (wegtultrarich.org)." The API's source code is not open source; view [LICENSE.md](https://wegtultrarich.org/LICENSE.md).

    Naming: Write it as `We > Ultrarich` (or `We Are Greater Than The Ultrarich` where > won't work). Use `wegtultrarich` in identifiers. Full guide in [LICENSE.md](https://wegtultrarich.org/LICENSE.md#name--wordmark--all-rights-reserved).
  termsOfService: https://wegtultrarich.org/terms-of-use.html
  version: '1.4.1'
  contact:
    name: We > Ultrarich Support
    email: info@wegtultrarich.org
    url: https://wegtultrarich.org/faq.html
  license:
    name: CC BY 4.0
    url: https://creativecommons.org/licenses/by/4.0/
  x-privacy-policy-url: "https://wegtultrarich.org/privacy-policy.html"
externalDocs:
  description: API Documentation
  url: https://api.wegtultrarich.org/README.md

servers:
  - url: https://api.wegtultrarich.org/v1
    description: Main (Production) Server

# Our API is public — no authentication is required for any operation.
security: []

tags:
  - name: Discovery
    description: Discover (list) the available endpoints.
  - name: Wealth Expression
    description: Express a single wealth through one of four lenses (daily spending, physical size, purchasing power, or compound interest).
  - name: Comparison
    description: Compare any wealth expression for two wealths ('yours' and 'theirs') in a single call — get both results as well as the ratio between them.

paths:
  /expressions:
    get:
      operationId: expressions
      summary: Available Endpoints
      description: Returns an array of routes listing the endpoint uri paths of the four wealth expressions plus the comparison.
      tags:
        - Discovery
      responses:
        '200':
          description: a JSON object with response data
          content:
            application/json:
              example:
                status: "success"
                data:
                  - route: "/v1/durationOfDailySpend"
                  - route: "/v1/heightOfMoneyStack"
                  - route: "/v1/numberOfItems"
                  - route: "/v1/growthOfCompoundInterest"
                  - route: "/v1/comparison"
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "success"
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        route:
                          type: string
                          description: The path to each available wealth expression.
                      required:
                        - "route"
                    example:
                      - route: "/v1/durationOfDailySpend"
                      - route: "/v1/heightOfMoneyStack"
                      - route: "/v1/numberOfItems"
                      - route: "/v1/growthOfCompoundInterest"
                      - route: "/v1/comparison"
                required:
                  - "status"
                  - "data"
        '429':
          description: rate limit exceeded
          headers:
            Retry-After:
              description: The number of seconds remaining until the rate-limit window resets.
              schema:
                type: integer
                example: 60
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "error"
                  error:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 429
                      message:
                        type: string
                        example: "Too Many Requests"
                      details:
                        type: string
                        example: "Rate limit exceeded. Try again in 60 seconds."
                      retryAfter:
                        type: integer
                        example: 60
                        description: The number of seconds remaining until the rate-limit window resets.
                    required:
                      - "code"
                      - "message"
                      - "details"
                      - "retryAfter"
                required:
                  - "status"
                  - "error"
      x-ratelimit:
        limit: 100
        period: 1 minute
        unit: requests
        scope: ip
        shared: true
        description: Rate limited to 100 requests per minute per IP, shared across all /v1 endpoints.

  /durationOfDailySpend:
    get:
      operationId: durationOfDailySpend
      summary: Duration Of Daily Spend
      description: Given a wealth and amount, returns the duration of time a specified-wealth would last when a specified-amount was spent daily.
      tags:
        - Wealth Expression
      parameters:
        - in: query
          name: wealth
          required: true
          schema:
            oneOf:
              - type: number
                description: a numeric amount with or without decimal places
                minimum: 1
                maximum: 1000000000000000000000000
                example: 1000000000
              - type: string
                description: a string with a local-formatted number (like 1,000,000) or shorthand (like 1M) with or without a URL-encoded currency symbol
          description: Wealth is the amount of money to be described via this expression.
        - in: query
          name: spend
          required: true
          schema:
            oneOf:
              - type: number
                description: a numeric amount with or without decimal places
                minimum: 1
                maximum: 1000000000000000000000000
                example: 1000
              - type: string
                description: a string with a local-formatted number (like 1,000,000) or shorthand (like 1M) with or without a URL-encoded currency symbol
          description: Spend is the amount of money to be spent daily (the crux of this expression).
      responses:
        '200':
          description: a JSON object with response data
          content:
            application/json:
              example:
                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)."
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "success"
                  data:
                    type: object
                    properties:
                      value:
                        type: number
                        example: 2739.72602739726
                        description: The value for duration of time.
                      unit:
                        type: string
                        example: "years"
                        description: The unit for duration of time.
                      type:
                        type: string
                        nullable: true
                        example: null
                        description: This expression doesn't have any types.
                      phrase:
                        type: string
                        example: "2.7 Millennia (2,740 Years)"
                        description: A phrase of the duration of time (title-cased for use as a standalone label).
                      sentence:
                        type: string
                        example: "A person with a wealth of $1,000,000,000 could spend $1,000 every day for 2.7 millennia (2,740 years)!"
                        description: A complete sentence summarizing the expression and its duration of time result (sentence-cased for use as inline prose).
                      scale:
                        type: string
                        nullable: true
                        example: "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)."
                        description: A complete sentence providing context for the expression and its duration of time result (sentence-cased for use as inline prose).
                    required:
                      - value
                      - unit
                      - type
                      - phrase
                      - sentence
                      - scale
                required:
                  - "status"
                  - "data"
        '400':
          description: a JSON object with error data
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "error"
                  error:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 400
                      message:
                        type: string
                        example: "Wealth Missing"
                        description: A human-readable error message like 'Wealth Missing', 'Wealth Malformed', 'Wealth Zero', etc.
                    required:
                      - "code"
                      - "message"
                required:
                  - "status"
                  - "error"
        '429':
          description: rate limit exceeded
          headers:
            Retry-After:
              description: The number of seconds remaining until the rate-limit window resets.
              schema:
                type: integer
                example: 60
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "error"
                  error:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 429
                      message:
                        type: string
                        example: "Too Many Requests"
                      details:
                        type: string
                        example: "Rate limit exceeded. Try again in 60 seconds."
                      retryAfter:
                        type: integer
                        example: 60
                        description: The number of seconds remaining until the rate-limit window resets.
                    required:
                      - "code"
                      - "message"
                      - "details"
                      - "retryAfter"
                required:
                  - "status"
                  - "error"
      x-ratelimit:
        limit: 100
        period: 1 minute
        unit: requests
        scope: ip
        shared: true
        description: Rate limited to 100 requests per minute per IP, shared across all /v1 endpoints.

  /heightOfMoneyStack:
    get:
      operationId: heightOfMoneyStack
      summary: Height Of Stacked Money
      description: Given a wealth and type of money, returns the height of a stack of the specified-wealth in the specified-type-of-money.
      tags:
        - Wealth Expression
      parameters:
        - in: query
          name: wealth
          required: true
          schema:
            oneOf:
              - type: number
                description: a numeric amount with or without decimal places
                minimum: 1
                maximum: 1000000000000000000000000
                example: 1000000000
              - type: string
                description: a string with a local-formatted number (like 1,000,000) or shorthand (like 1M) with or without a URL-encoded currency symbol
          description: Wealth is the amount of money to be described via this expression.
        - in: query
          name: typeOfMoney
          required: true
          schema:
            type: string
            enum: ["usd_1_coin","usd_100_bill","cad_1_coin","cad_100_bill","eur_1_coin","eur_100_bill","gbp_1_coin","gbp_100_bill","cny_1_coin","cny_100_bill","inr_1_coin","inr_100_bill","krw_1_coin","krw_1000_bill","rub_1_coin","rub_100_bill","try_1_coin","try_100_bill","chf_1_coin","chf_100_bill","brl_1_coin","brl_100_bill"]
          description: >
            Type Of Money is the money to be stacked (the crux of this expression):
            * `usd_1_coin` - Dollar Coins (USD; 2 mm per coin);
            * `usd_100_bill` - Hundred-Dollar Bills (USD; 0.11 mm per bill);
            * `cad_1_coin` - Loonies (CAD; 1.95 mm per coin);
            * `cad_100_bill` - Hundred-Dollar Bills (CAD; 0.0875 mm per bill);
            * `eur_1_coin` - Euro Coins (EUR; 2.33 mm per coin);
            * `eur_100_bill` - Hundred-Euro Bills (EUR; 0.12 mm per bill);
            * `gbp_1_coin` - Pound Coins (GBP; 2.8 mm per coin);
            * `gbp_100_bill` - Hundred-Pound Bills (GBP; 0.0825 mm per bill);
            * `cny_1_coin` - Yuan Coins (CNY; 1.85 mm per coin);
            * `cny_100_bill` - Hundred-Yuan Bills (CNY; 0.1 mm per bill);
            * `inr_1_coin` - Rupee Coins (INR; 1.45 mm per coin);
            * `inr_100_bill` - Hundred-Rupee Bills (INR; 0.11 mm per bill);
            * `krw_1_coin` - Won Coins (KRW; 1.45 mm per coin);
            * `krw_1000_bill` - Thousand-Won Bills (KRW; 0.1 mm per bill);
            * `rub_1_coin` - Ruble Coins (RUB; 1.5 mm per coin);
            * `rub_100_bill` - Hundred-Ruble Bills (RUB; 0.1 mm per bill);
            * `try_1_coin` - Lira Coins (TRY; 2 mm per coin);
            * `try_100_bill` - Hundred-Lira Bills (TRY; 0.105 mm per bill);
            * `chf_1_coin` - Franc Coins (CHF; 1.55 mm per coin);
            * `chf_100_bill` - Hundred-Franc Bills (CHF; 0.11 mm per bill);
            * `brl_1_coin` - Real Coins (BRL; 1.95 mm per coin); or
            * `brl_100_bill` - Hundred-Real Bills (BRL; 0.105 mm per bill).
      responses:
        '200':
          description: a JSON object with response data
          content:
            application/json:
              example:
                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)."
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "success"
                  data:
                    type: object
                    properties:
                      value:
                        type: number
                        example: 2000000
                        description: The value for height.
                      unit:
                        type: string
                        example: "meters"
                        description: The unit for height.
                      type:
                        type: string
                        example: "dollar coins"
                        description: The currency and kind of stacked money (coins or bills) per inputted typeOfMoney.
                      phrase:
                        type: string
                        example: "1,243 Miles (2,000 km)"
                        description: A phrase of the height (title-cased for use as a standalone label).
                      sentence:
                        type: string
                        example: "A person with a wealth of $1,000,000,000 would have a stack of dollar coins 1,243 miles (2,000 km) high!"
                        description: A complete sentence summarizing the expression and its height result (sentence-cased for use as inline prose).
                      scale:
                        type: string
                        nullable: true
                        example: "That's about 10 times the distance of a roundtrip to the edge of space (Kármán Line)."
                        description: A complete sentence providing context for the expression and its height result (sentence-cased for use as inline prose).
                    required:
                      - value
                      - unit
                      - type
                      - phrase
                      - sentence
                      - scale
                required:
                  - "status"
                  - "data"
        '400':
          description: a JSON object with error data
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "error"
                  error:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 400
                      message:
                        type: string
                        example: "Wealth Missing"
                        description: A human-readable error message like 'Wealth Missing', 'Wealth Malformed', 'Wealth Zero', etc.
                    required:
                      - "code"
                      - "message"
                required:
                  - "status"
                  - "error"
        '429':
          description: rate limit exceeded
          headers:
            Retry-After:
              description: The number of seconds remaining until the rate-limit window resets.
              schema:
                type: integer
                example: 60
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "error"
                  error:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 429
                      message:
                        type: string
                        example: "Too Many Requests"
                      details:
                        type: string
                        example: "Rate limit exceeded. Try again in 60 seconds."
                      retryAfter:
                        type: integer
                        example: 60
                        description: The number of seconds remaining until the rate-limit window resets.
                    required:
                      - "code"
                      - "message"
                      - "details"
                      - "retryAfter"
                required:
                  - "status"
                  - "error"
      x-ratelimit:
        limit: 100
        period: 1 minute
        unit: requests
        scope: ip
        shared: true
        description: Rate limited to 100 requests per minute per IP, shared across all /v1 endpoints.

  /numberOfItems:
    get:
      operationId: numberOfItems
      summary: Number Of Items Paid For
      description: Given a wealth and type of item, returns the number of specified-items the specified-wealth could buy or pay for/off. Note — 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.
      tags:
        - Wealth Expression
      parameters:
        - in: query
          name: wealth
          required: true
          schema:
            oneOf:
              - type: number
                description: a numeric amount with or without decimal places
                minimum: 1
                maximum: 1000000000000000000000000
                example: 1000000000
              - type: string
                description: a string with a local-formatted number (like 1,000,000) or shorthand (like 1M) with or without a URL-encoded currency symbol
          description: Wealth is the amount of money to be described via this expression.
        - in: query
          name: typeOfItem
          required: true
          schema:
            type: string
            enum: ["fancy_coffee", "quick_meal", "dinner_with_drinks", "iphone", "month_of_childcare", "rent_or_mortgage_payment", "year_of_low_minimum_wage_salary", "year_of_high_minimum_wage_salary", "student_loan_debt", "car", "year_of_salary_65k", "year_of_salary_100k", "luxury_car", "house", "yacht", "supercar", "island", "mansion", "estate_with_a_mega_mansion", "luxury_island", "superyacht"]
          description: >
            Type Of Item is the item to be bought or paid for/off (the crux of this expression):
            * `fancy_coffee` - $10 Fancy Coffee
            * `quick_meal` - $15 Quick Meal
            * `dinner_with_drinks` - $175 Dinner With Drinks
            * `iphone` - $1,400 iPhone
            * `month_of_childcare` - $1,750 Month Of Childcare
            * `rent_or_mortgage_payment` - $3,000 Rent Or Mortgage Payment
            * `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` - $40K Student Loan Debt
            * `car` - $50K Car
            * `year_of_salary_65k` - Year Of $65,000 Salary
            * `year_of_salary_100k` - Year Of $100,000 Salary
            * `luxury_car` - $275K Luxury Car
            * `house` - $500K House
            * `yacht` - $800K Yacht
            * `supercar` - $4M Supercar
            * `island` - $30M Island
            * `mansion` - $75M Mansion
            * `estate_with_a_mega_mansion` - $200M Estate With A Mega-Mansion
            * `luxury_island` - $300M Luxury Island
            * `superyacht` - $600M Superyacht
      responses:
        '200':
          description: a JSON object with response data
          content:
            application/json:
              example:
                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)."
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "success"
                  data:
                    type: object
                    properties:
                      value:
                        type: number
                        example: 2000
                        description: The number of items bought or paid for/off.
                      unit:
                        type: string
                        nullable: true
                        example: null
                        description: This expression doesn't have any units.
                      type:
                        type: string
                        example: "houses"
                        description: The kind of item bought or paid for/off.
                      phrase:
                        type: string
                        example: "2,000 Houses"
                        description: A phrase of the number of items bought or paid for/off (title-cased for use as a standalone label).
                      sentence:
                        type: string
                        example: "A person with a wealth of $1,000,000,000 could buy 2,000 houses all at once!"
                        description: A complete sentence summarizing the expression and its number of items bought or paid for/off result (sentence-cased for use as inline prose).
                      scale:
                        type: string
                        nullable: true
                        example: "That's approximately 1.3 times enough for every person in a village (typically between 1K–10K population)."
                        description: A complete sentence providing context for the expression and its number of items bought or paid for/off result (sentence-cased for use as inline prose).
                    required:
                      - value
                      - unit
                      - type
                      - phrase
                      - sentence
                      - scale
                required:
                  - "status"
                  - "data"
        '400':
          description: a JSON object with error data
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "error"
                  error:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 400
                      message:
                        type: string
                        example: "Wealth Missing"
                        description: A human-readable error message like 'Wealth Missing', 'Wealth Malformed', 'Wealth Zero', etc.
                    required:
                      - "code"
                      - "message"
                required:
                  - "status"
                  - "error"
        '429':
          description: rate limit exceeded
          headers:
            Retry-After:
              description: The number of seconds remaining until the rate-limit window resets.
              schema:
                type: integer
                example: 60
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "error"
                  error:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 429
                      message:
                        type: string
                        example: "Too Many Requests"
                      details:
                        type: string
                        example: "Rate limit exceeded. Try again in 60 seconds."
                      retryAfter:
                        type: integer
                        example: 60
                        description: The number of seconds remaining until the rate-limit window resets.
                    required:
                      - "code"
                      - "message"
                      - "details"
                      - "retryAfter"
                required:
                  - "status"
                  - "error"
      x-ratelimit:
        limit: 100
        period: 1 minute
        unit: requests
        scope: ip
        shared: true
        description: Rate limited to 100 requests per minute per IP, shared across all /v1 endpoints.

  /growthOfCompoundInterest:
    get:
      operationId: growthOfCompoundInterest
      summary: Growth Of Compound Interest
      description: Given a wealth and a rate, frequency, and period, returns the growth of a specified-wealth's compound interest at a specified-rate and specified-frequency for a specified-period.
      tags:
        - Wealth Expression
      parameters:
        - in: query
          name: wealth
          required: true
          schema:
            oneOf:
              - type: number
                description: a numeric amount with or without decimal places
                minimum: 1
                maximum: 1000000000000000000000000
                example: 1000000000
              - type: string
                description: a string with a local-formatted number (like 1,000,000) or shorthand (like 1M) with or without a URL-encoded currency symbol
          description: Wealth is the amount of money to be described via this expression.
        - in: query
          name: rate
          required: true
          schema:
            type: number
            format: float
            minimum: 0
            maximum: 1
            exclusiveMinimum: true
            exclusiveMaximum: true
            example: 0.01
          description: Rate is the interest rate at which the wealth is compounded (one-third of the crux of this expression).
        - in: query
          name: frequency
          required: true
          schema:
            type: string
            enum: ["1", "2", "4", "12", "365"]
          description: >
            Frequency is how often the wealth is compounded (one-third of the crux of this expression):
            * `1` - Annually
            * `2` - Semiannually
            * `4` - Quarterly
            * `12` - Monthly
            * `365` - Daily
        - in: query
          name: period
          required: true
          schema:
            type: number
            minimum: 0
            maximum: 100
            exclusiveMinimum: true
            exclusiveMaximum: true
            example: 20
          description: Period is the duration of time in years over which the wealth is compounded (one-third of the crux of this expression).
      responses:
        '200':
          description: a JSON object with response data
          content:
            application/json:
              example:
                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)."
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "success"
                  data:
                    type: object
                    properties:
                      value:
                        type: number
                        example: 220190040
                        description: The value for growth of compounded interest.
                      unit:
                        type: string
                        example: "dollars"
                        description: The unit for growth of compounded interest.
                      type:
                        type: string
                        nullable: true
                        example: null
                        description: This expression doesn't have any types.
                      phrase:
                        type: string
                        example: "By $220,190,040 Over 20 Years"
                        description: A phrase of the growth of compounded interest (title-cased for use as a standalone label).
                      sentence:
                        type: string
                        example: "With 1% interest compounded annually, a person with $1,000,000,000 would grow their wealth by $220,190,040 over 20 years!"
                        description: A complete sentence summarizing the expression and its growth of compounded interest result (sentence-cased for use as inline prose).
                      scale:
                        type: string
                        nullable: true
                        example: "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)."
                        description: A complete sentence providing context for the expression and its growth of compounded interest result (sentence-cased for use as inline prose).
                    required:
                      - value
                      - unit
                      - type
                      - phrase
                      - sentence
                      - scale
                required:
                  - "status"
                  - "data"
        '400':
          description: a JSON object with error data
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "error"
                  error:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 400
                      message:
                        type: string
                        example: "Wealth Missing"
                        description: A human-readable error message like 'Wealth Missing', 'Wealth Malformed', 'Wealth Zero', etc.
                    required:
                      - "code"
                      - "message"
                required:
                  - "status"
                  - "error"
        '429':
          description: rate limit exceeded
          headers:
            Retry-After:
              description: The number of seconds remaining until the rate-limit window resets.
              schema:
                type: integer
                example: 60
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "error"
                  error:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 429
                      message:
                        type: string
                        example: "Too Many Requests"
                      details:
                        type: string
                        example: "Rate limit exceeded. Try again in 60 seconds."
                      retryAfter:
                        type: integer
                        example: 60
                        description: The number of seconds remaining until the rate-limit window resets.
                    required:
                      - "code"
                      - "message"
                      - "details"
                      - "retryAfter"
                required:
                  - "status"
                  - "error"
      x-ratelimit:
        limit: 100
        period: 1 minute
        unit: requests
        scope: ip
        shared: true
        description: Rate limited to 100 requests per minute per IP, shared across all /v1 endpoints.
  /comparison:
    get:
      operationId: comparison
      summary: Full Comparison Of Two Wealths
      description: Given an expression, two wealths (yours and theirs), and that expression's own parameters, returns the expression's result for both wealths plus the ratio between them — a complete "them vs. you" comparison in a single call.
      tags:
        - Comparison
      parameters:
        - in: query
          name: expression
          required: true
          schema:
            type: string
            enum: ["durationOfDailySpend", "heightOfMoneyStack", "numberOfItems", "growthOfCompoundInterest"]
          description: >
            Expression is the wealth expression to compute for both wealths (the crux of this comparison):
            * `durationOfDailySpend` - also requires `spend`
            * `heightOfMoneyStack` - also requires `typeOfMoney`
            * `numberOfItems` - also requires `typeOfItem` (see note above about use of approximate U.S. benchmark prices denominated in USD)
            * `growthOfCompoundInterest` - also requires `rate`, `frequency`, and `period`
        - in: query
          name: wealthYours
          required: true
          schema:
            oneOf:
              - type: number
                description: a numeric amount with or without decimal places
                minimum: 1
                maximum: 1000000000000000000000000
                example: 1000000000
              - type: string
                description: a string with a local-formatted number (like 1,000,000) or shorthand (like 1M) with or without a URL-encoded currency symbol
          description: Wealth Yours is the amount of money of the user ("your" wealth) to be compared via the specified expression.
        - in: query
          name: wealthTheirs
          required: true
          schema:
            oneOf:
              - type: number
                description: a numeric amount with or without decimal places
                minimum: 1
                maximum: 1000000000000000000000000
                example: 1000000000
              - type: string
                description: a string with a local-formatted number (like 1,000,000) or shorthand (like 1M) with or without a URL-encoded currency symbol
          description: Wealth Theirs is the amount of money of the ultrarich ("their" wealth) to be compared via the specified expression.
        - in: query
          name: spend
          required: false
          schema:
            oneOf:
              - type: number
                description: a numeric amount with or without decimal places
                minimum: 1
                maximum: 1000000000000000000000000
                example: 1000
              - type: string
                description: a string with a local-formatted number (like 1,000,000) or shorthand (like 1M) with or without a URL-encoded currency symbol
          description: Spend is the amount of money to be spent daily. Required when expression is durationOfDailySpend; ignored otherwise.
        - in: query
          name: typeOfMoney
          required: false
          schema:
            type: string
            enum: ["usd_1_coin","usd_100_bill","cad_1_coin","cad_100_bill","eur_1_coin","eur_100_bill","gbp_1_coin","gbp_100_bill","cny_1_coin","cny_100_bill","inr_1_coin","inr_100_bill","krw_1_coin","krw_1000_bill","rub_1_coin","rub_100_bill","try_1_coin","try_100_bill","chf_1_coin","chf_100_bill","brl_1_coin","brl_100_bill"]
          description: >
            Type Of Money is the money to be stacked. Required when expression is heightOfMoneyStack; ignored otherwise.
            * `usd_1_coin` - Dollar Coins (USD; 2 mm per coin);
            * `usd_100_bill` - Hundred-Dollar Bills (USD; 0.11 mm per bill);
            * `cad_1_coin` - Loonies (CAD; 1.95 mm per coin);
            * `cad_100_bill` - Hundred-Dollar Bills (CAD; 0.0875 mm per bill);
            * `eur_1_coin` - Euro Coins (EUR; 2.33 mm per coin);
            * `eur_100_bill` - Hundred-Euro Bills (EUR; 0.12 mm per bill);
            * `gbp_1_coin` - Pound Coins (GBP; 2.8 mm per coin);
            * `gbp_100_bill` - Hundred-Pound Bills (GBP; 0.0825 mm per bill);
            * `cny_1_coin` - Yuan Coins (CNY; 1.85 mm per coin);
            * `cny_100_bill` - Hundred-Yuan Bills (CNY; 0.1 mm per bill);
            * `inr_1_coin` - Rupee Coins (INR; 1.45 mm per coin);
            * `inr_100_bill` - Hundred-Rupee Bills (INR; 0.11 mm per bill);
            * `krw_1_coin` - Won Coins (KRW; 1.45 mm per coin);
            * `krw_1000_bill` - Thousand-Won Bills (KRW; 0.1 mm per bill);
            * `rub_1_coin` - Ruble Coins (RUB; 1.5 mm per coin);
            * `rub_100_bill` - Hundred-Ruble Bills (RUB; 0.1 mm per bill);
            * `try_1_coin` - Lira Coins (TRY; 2 mm per coin);
            * `try_100_bill` - Hundred-Lira Bills (TRY; 0.105 mm per bill);
            * `chf_1_coin` - Franc Coins (CHF; 1.55 mm per coin);
            * `chf_100_bill` - Hundred-Franc Bills (CHF; 0.11 mm per bill);
            * `brl_1_coin` - Real Coins (BRL; 1.95 mm per coin); or
            * `brl_100_bill` - Hundred-Real Bills (BRL; 0.105 mm per bill).
        - in: query
          name: typeOfItem
          required: false
          schema:
            type: string
            enum: ["fancy_coffee", "quick_meal", "dinner_with_drinks", "iphone", "month_of_childcare", "rent_or_mortgage_payment", "year_of_low_minimum_wage_salary", "year_of_high_minimum_wage_salary", "student_loan_debt", "car", "year_of_salary_65k", "year_of_salary_100k", "luxury_car", "house", "yacht", "supercar", "island", "mansion", "estate_with_a_mega_mansion", "luxury_island", "superyacht"]
          description: >
            Type Of Item is the item to be bought or paid for/off. Required when expression is numberOfItems; ignored otherwise.
            * `fancy_coffee` - $10 Fancy Coffee
            * `quick_meal` - $15 Quick Meal
            * `dinner_with_drinks` - $175 Dinner With Drinks
            * `iphone` - $1,400 iPhone
            * `month_of_childcare` - $1,750 Month Of Childcare
            * `rent_or_mortgage_payment` - $3,000 Rent Or Mortgage Payment
            * `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` - $40K Student Loan Debt
            * `car` - $50K Car
            * `year_of_salary_65k` - Year Of $65,000 Salary
            * `year_of_salary_100k` - Year Of $100,000 Salary
            * `luxury_car` - $275K Luxury Car
            * `house` - $500K House
            * `yacht` - $800K Yacht
            * `supercar` - $4M Supercar
            * `island` - $30M Island
            * `mansion` - $75M Mansion
            * `estate_with_a_mega_mansion` - $200M Estate With A Mega-Mansion
            * `luxury_island` - $300M Luxury Island
            * `superyacht` - $600M Superyacht
        - in: query
          name: rate
          required: false
          schema:
            type: number
            format: float
            minimum: 0
            maximum: 1
            exclusiveMinimum: true
            exclusiveMaximum: true
            example: 0.01
          description: Rate is the interest rate at which the wealths are compounded. Required when expression is growthOfCompoundInterest; ignored otherwise.
        - in: query
          name: frequency
          required: false
          schema:
            type: string
            enum: ["1", "2", "4", "12", "365"]
          description: Frequency is how often the wealths are compounded (1 Annually; 2 Semiannually; 4 Quarterly; 12 Monthly; 365 Daily). Required when expression is growthOfCompoundInterest; ignored otherwise.
        - in: query
          name: period
          required: false
          schema:
            type: number
            minimum: 0
            maximum: 100
            exclusiveMinimum: true
            exclusiveMaximum: true
            example: 20
          description: Period is the duration of time in years over which the wealths are compounded. Required when expression is growthOfCompoundInterest; ignored otherwise.
      responses:
        '200':
          description: a JSON object with response data
          content:
            application/json:
              example:
                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."
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "success"
                  data:
                    type: object
                    properties:
                      expression:
                        type: string
                        example: "durationOfDailySpend"
                        description: The expression that was computed for both wealths (echoed so the payload is self-describing).
                      resultTheirs:
                        type: object
                        description: The expression's result for wealthTheirs. Same shape as the expression's own endpoint response data.
                        properties:
                          value:
                            type: number
                            example: 273972.602739726
                            description: The raw numeric result for their wealth.
                          unit:
                            type: string
                            nullable: true
                            example: "years"
                            description: The unit of the value (where applicable).
                          type:
                            type: string
                            nullable: true
                            example: null
                            description: The type of result (kind of stacked money, kind of item, or null).
                          phrase:
                            type: string
                            example: "274 Millennia (273,973 Years)"
                            description: A phrase of the result (title-cased for use as a standalone label).
                          sentence:
                            type: string
                            example: "A person with a wealth of $100,000,000,000 could spend $1,000 every day for 274 millennia (273,973 years)!"
                            description: A complete sentence summarizing the expression and its result (sentence-cased for use as inline prose).
                          scale:
                            type: string
                            nullable: true
                            example: "That's approximately 1.6 times as long ago as when Homo Sapiens began wearing primitive clothing (≈170K BCE)."
                            description: A complete sentence providing context for the result (sentence-cased for use as inline prose).
                        required:
                          - value
                          - unit
                          - type
                          - phrase
                          - sentence
                          - scale
                      resultYours:
                        type: object
                        description: The expression's result for wealthYours. Same shape as the expression's own endpoint response data.
                        properties:
                          value:
                            type: number
                            example: 0.273972602739726
                            description: The raw numeric result for your wealth.
                          unit:
                            type: string
                            nullable: true
                            example: "years"
                            description: The unit of the value (where applicable).
                          type:
                            type: string
                            nullable: true
                            example: null
                            description: The type of result (kind of stacked money, kind of item, or null).
                          phrase:
                            type: string
                            example: "100 Days"
                            description: A phrase of the result (title-cased for use as a standalone label).
                          sentence:
                            type: string
                            example: "A person with a wealth of $100,000 could spend $1,000 every day for 100 days!"
                            description: A complete sentence summarizing the expression and its result (sentence-cased for use as inline prose).
                          scale:
                            type: string
                            nullable: true
                            example: null
                            description: A complete sentence providing context for the result (sentence-cased for use as inline prose).
                        required:
                          - value
                          - unit
                          - type
                          - phrase
                          - sentence
                          - scale
                      ratio:
                        type: object
                        description: The ratio between the two wealths (wealthTheirs divided by wealthYours; values below 1 mean wealthYours is the larger).
                        properties:
                          value:
                            type: number
                            example: 1000000
                            description: The raw numeric ratio of wealthTheirs to wealthYours.
                          phrase:
                            type: string
                            example: "1,000,000 : 1"
                            description: A phrase of the ratio with the 1 on the smaller side (title-cased for use as a standalone label).
                          sentence:
                            type: string
                            example: "Their wealth is 1,000,000 times yours."
                            description: A complete direction-aware sentence summarizing the ratio (sentence-cased for use as inline prose).
                          scale:
                            type: string
                            nullable: true
                            example: "That's extreme wealth inequality."
                            description: A complete sentence assessing the ratio, tiered by magnitude (ratios of 200-to-1 or more are described as extreme wealth inequality — a rounded contextual threshold informed by a reported ~190:1 global disparity, not an official IMF definition).
                        required:
                          - value
                          - phrase
                          - sentence
                          - scale
                    required:
                      - "expression"
                      - "resultTheirs"
                      - "resultYours"
                      - "ratio"
                required:
                  - "status"
                  - "data"
        '400':
          description: a JSON object with error data
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "error"
                  error:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 400
                      message:
                        type: string
                        example: "Their Wealth Missing"
                        description: A human-readable error message like 'Expression Invalid', 'Your Wealth Zero', 'Their Wealth Missing', etc.
                    required:
                      - "code"
                      - "message"
                required:
                  - "status"
                  - "error"
        '429':
          description: rate limit exceeded
          headers:
            Retry-After:
              description: The number of seconds remaining until the rate-limit window resets.
              schema:
                type: integer
                example: 60
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "error"
                  error:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 429
                      message:
                        type: string
                        example: "Too Many Requests"
                      details:
                        type: string
                        example: "Rate limit exceeded. Try again in 60 seconds."
                      retryAfter:
                        type: integer
                        example: 60
                        description: The number of seconds remaining until the rate-limit window resets.
                    required:
                      - "code"
                      - "message"
                      - "details"
                      - "retryAfter"
                required:
                  - "status"
                  - "error"
      x-ratelimit:
        limit: 100
        period: 1 minute
        unit: requests
        scope: ip
        shared: true
        description: Rate limited to 100 requests per minute per IP, shared across all /v1 endpoints.