Features

Feature 1: Smart Pricing (Purchasing Power Parity)

What is it?

Purchasing Power Parity (PPP) is an economic metric used to compare the standards of living between different countries. In the context of an API, "Smart Pricing" uses PPP data to suggest a fair price for a digital product based on a user's location.

Instead of charging a flat $50 USD globally (which is affordable in the US but expensive in India or Brazil), this function calculates a price that "feels" the same in terms of local purchasing power.

Who is this for?

SaaS Companies: (e.g., Project management tools, Email marketing) wanting to increase global subscribers.
E-Learning Platforms: (e.g., Udemy clones) selling courses globally.
Digital Goods: (e.g., E-books, Assets) where the marginal cost of replication is zero.

Why is it important?

Revenue Maximization: Lowering the price in lower-income countries often leads to a massive spike in volume, resulting in higher total revenue than keeping the price high.
Fairness: It builds brand loyalty by acknowledging economic disparities.

Scenario: A product costs 5,000 Indian Rupees, then getting the smart price for the same product in France should give a smart price of 148.32 EUR:

Request: get_smart_price(amount=5000, base_currency="India", target_country="France")

{
  "meta": {
    "origin": {
      "country": "IN",
      "ppp": 0.241464271880756,
      "currency": "INR"
    },
    "target": {
      "country": "FR",
      "ppp": 0.752596458009375,
      "currency": "EUR"
    },
    "adjustment_ratio": 3.12
  },
  "original": {
    "amount": 5000,
    "usd_forex_equiv": 55.38
  },
  "smart_price": {
    "amount": 148.32,
    "currency": "EUR",
    "formatted": "148.32 EUR"
  },
  "explanation": "Life in FR is 3.11680254866457x as expensive as IN. To match the purchasing power effort, the price is adjusted."
}

Feature 2: Margin & Spread Simulation

What is it?

Simulates the "Retail Rate" vs the "Interbank Rate". It allows businesses to calculate a custom exchange rate that includes their profit margin or risk buffer.

Usage

Scenario: An online store wants to convert $100 USD to EUR, but needs to add a 2.5% buffer to cover PayPal fees.

Request: simulate_margin(amount=100, base_currency='USD', target_currency='EUR', margin_percent=2.5)

Response:

{
  "request": {
    "amount": 100,
    "from": "USD",
    "to": "INR",
    "margin_percent": 3.0
  },
  "rates": {
    "mid_market_rate": 90.285478,
    "customer_rate": 92.994043,
    "spread_basis_points": 300
  },
  "totals": {
    "mid_market_value": 9028.55,
    "customer_value": 9299.4,
    "currency": "INR"
  },
  "margin_breakdown": {
    "fee_amount": 270.86,
    "message": "Includes a 3.0% markup (270.86 INR)"
  }
}

Explanation

1. Mid-Market Rate (The "Real" Price)

The Mid-Market Rate is the midpoint between the "Buy" price and the "Sell" price of a currency in the global market.

Bid Price: The highest price a buyer (bank) is willing to pay.
Ask Price: The lowest price a seller (bank) is willing to accept.
Mid-Market: (Bid + Ask) / 2

The Mid-Market rate is the fairest exchange rate possible. It is the rate used by banks when they trade millions of dollars with each other.

However, regular people never get this rate. When you go to a currency exchange booth, use PayPal, or pay with your credit card abroad, they do not give you the Mid-Market rate. They give you a "Retail Rate" which includes a markup.

2. Spread (The "Hidden Fee")

The Spread is the difference between the Mid-Market rate and the rate the customer is actually charged. This is how banks and exchange services make money.

Example:

Mid-Market Rate: 1 USD = 1.00 EUR
Bank Sells to You at: 1 USD = 0.98 EUR
The Spread: 0.02 EUR

In this example, the bank takes those 2 cents as profit on every dollar.

3. Basis Points (bps)

In finance, percentages can be confusing or too small to talk about easily (e.g., "0.015%"). To solve this, traders use Basis Points (pronounced "bips").

The math is simple: $$ 1 \text{ Basis Point (bps)} = 0.01\% $$ $$ 100 \text{ Basis Points} = 1\% $$

Conversion Table

Percentage	Basis Points (bps)	Meaning
0.01%	1 bps	Tiny fluctuation
0.50%	50 bps	Typical "Interbank" spread
1.00%	100 bps	Good Credit Card rate
2.50%	250 bps	Standard PayPal/Stripe fee
5.00%	500 bps	Airport Kiosk (Rip-off)

Feature 3: Point-in-Time (PIT) History

What is it?

Fetches the exchange rate exactly as it appeared at a specific second in history. Unlike other APIs that only store "Daily Close" rates, we store tick-level data.

Usage

Scenario: An accountant needs the exact USD to EUR rate on October 15th, 2023 at 14:30 UTC to close an audit.

Request: get_historical_rates(date_str="2026-01-14 21:30:00", base_currency="USD", symbols=['EUR', 'GBP'])

Note: date_str can also be a string like "5 minutes ago".

Response:

{
    "meta": {
        "requested_time": "2026-01-14T21:30:00.000000Z",
        "base_currency": "USD",
        "data_point_count": 3
    },
    "rates": {
        "EUR": 0.859381,
        "ADA": 2.398648,
        "INR": 90.27706
    }
}