@allratestoday/sdk 1.4.7 → 1.4.9

package/README.md

@@ -95,6 +95,8 @@ console.log(data);
 
 ### Historical Exchange Rates
 
+> Historical methods (`forDate`, `timeSeries`, `getHistoricalRates` and `convert` with a `date`) need a paid plan from €4.99/month. Free and trial keys get latest rates only and receive a 403 `historical_requires_paid_plan` for history.
+
 Travel back in time to get rates from any date:
 
 ```typescript
@@ -121,7 +123,7 @@ console.log(data);
 
 ### Currency Conversion
 
-Convert any amount between currencies — including historical conversions:
+Convert any amount between currencies — including historical conversions (paid plans):
 
 ```typescript
 // Current conversion
@@ -197,7 +199,7 @@ console.log(data);
 
 ### Time Series Data
 
-Get exchange rates over a date range for trend analysis and charting:
+Get exchange rates over a date range for trend analysis and charting (paid plans):
 
 ```typescript
 const data = await client.timeSeries('2026-01-01', '2026-03-31', {
@@ -282,13 +284,13 @@ console.log(sources.map((s) => `${s.code} ${s.latest}${s.stale ? ' (stale)' : ''
 ```
 
 Always cite the returned `rate_date` — it is the institution's publication date,
-not the time of your call. Dated tables, history and publication calendars sit
-behind the free key on `/api/v1/central-bank/{bank}/{date}`; see the
+not the time of your call. Dated tables and history need a paid plan and use
+`/api/v1/central-bank/{bank}/{date}`; publication calendars work on any key. See the
 [central bank rates API](https://allratestoday.com/central-bank-rates-api/).
 
 ### Historical Rates by Period
 
-Get historical rates using preset periods — no date math needed:
+Get historical rates using preset periods — no date math needed (paid plans):
 
 ```typescript
 const history = await client.getHistoricalRates('USD', 'EUR', '30d');
@@ -467,6 +469,8 @@ console.log(await getPrice(99.99, 'GBP')); // "78.90 GBP"
 
 ### Historical Chart Data
 
+Needs a paid plan (history is not included in free or trial keys).
+
 ```typescript
 import AllRatesToday from '@allratestoday/sdk';
 
@@ -492,13 +496,13 @@ console.log({ labels, values });
 | Method | Description |
 | ------ | ----------- |
 | `latest(options?)` | Get latest rates for one or more currencies |
-| `forDate(date, options?)` | Get rates for a specific historical date |
-| `convert(from, to, amount, options?)` | Convert amount between currencies (supports historical date) |
-| `timeSeries(start, end, options?)` | Get rates across a custom date range |
+| `forDate(date, options?)` | Get rates for a specific historical date (paid plan) |
+| `convert(from, to, amount, options?)` | Convert amount between currencies (historical `date` needs a paid plan) |
+| `timeSeries(start, end, options?)` | Get rates across a custom date range (paid plan) |
 | `symbols(options?)` | List all 160+ supported currency codes and names |
 | `getRate(from, to, amount?, options?)` | Get a single exchange rate |
 | `getRates(source, target, options?)` | Get rates with full metadata |
-| `getHistoricalRates(source, target, period?, options?)` | Historical rates by preset period (1d/7d/30d/1y) |
+| `getHistoricalRates(source, target, period?, options?)` | Historical rates by preset period (1d/7d/30d/1y; paid plan) |
 | `officialRates(bank, options?)` | Latest official table (or one pair) published by a central bank / tax authority — **keyless** |
 | `officialSources(options?)` | Every covered official source with latest publication date and freshness — **keyless** |
 
@@ -533,7 +537,7 @@ The same rates are available to coding agents and LLM tools without a second int
 - **Claude Code plugin** (no key): `/plugin marketplace add AllRates-Today/claude-code-plugin` then `/plugin install allratestoday@allratestoday`
 - **Hosted MCP endpoint**: `https://allratestoday.com/api/mcp` — Streamable HTTP, keyless, nothing to install
 - **Local MCP servers**: `npx -y @allratestoday/mcp-server` (live mid-market rates) · `npx -y @allratestoday/central-bank-mcp` (official central-bank rates)
-- **Trial key for agents, no signup**: `POST https://allratestoday.com/api/agent/keys` (send `Content-Type: application/json`) returns a 100-call key valid 7 days, enough to try history and dated tables; both MCP servers expose it as `request_trial_key`
+- **Trial key for agents, no signup**: `POST https://allratestoday.com/api/agent/keys` (send `Content-Type: application/json`) returns a 100-call key valid 7 days for latest rates and latest central-bank tables (history and dated tables are paid-plan only); both MCP servers expose it as `request_trial_key`
 - **Daily Reference Rate** (first published 2026-10-12): one fixed USD table per business day, the 16:00 London median of minute samples, never revised — keyless at `https://allratestoday.com/api/open/reference-rate`, `get_reference_rate` in the MCP server
 - Machine-readable site guide: [llms.txt](https://allratestoday.com/llms.txt)
 

package/dist/index.d.mts

@@ -188,7 +188,8 @@ declare class AllRatesToday {
      */
     latest(options?: LatestOptions): Promise<LatestResponse>;
     /**
-     * Get exchange rates for a specific historical date.
+     * Get exchange rates for a specific historical date. Paid plans only: free and trial keys
+     * get a 403 `historical_requires_paid_plan` error.
      *
      * ```ts
      * // Using a string
@@ -203,7 +204,8 @@ declare class AllRatesToday {
      */
     forDate(date: string | Date, options?: ForDateOptions): Promise<ForDateResponse>;
     /**
-     * Get exchange rate time series between two dates.
+     * Get exchange rate time series between two dates. Paid plans only: free and trial keys
+     * get a 403 `historical_requires_paid_plan` error.
      *
      * ```ts
      * const data = await client.timeSeries('2026-01-01', '2026-03-31', {
@@ -245,7 +247,7 @@ declare class AllRatesToday {
      * console.log(`ECB ${usd.rate_date}: 1 EUR = ${usd.rate} USD`);
      * ```
      *
-     * Dated tables and history need a free key: see `/api/v1/central-bank/{bank}/{date}`.
+     * Dated tables and history need a paid plan: see `/api/v1/central-bank/{bank}/{date}`.
      */
     officialRates(bank: string, options?: OfficialRateOptions): Promise<OfficialRatesResponse>;
     /**
@@ -281,7 +283,8 @@ declare class AllRatesToday {
      */
     getRates(source: string, target: string, options?: RequestOptions): Promise<AuthRateResponse[]>;
     /**
-     * Get historical rates by period.
+     * Get historical rates by period. Paid plans only: free and trial keys
+     * get a 403 `historical_requires_paid_plan` error.
      *
      * ```ts
      * const history = await client.getHistoricalRates('USD', 'EUR', '30d');
@@ -299,7 +302,7 @@ declare class AllRatesToday {
      * const result = await client.convert('USD', 'EUR', 1000);
      * console.log(`$1,000 = €${result.result}`);
      *
-     * // Historical conversion
+     * // Historical conversion (paid plans only)
      * const result = await client.convert('USD', 'EUR', 1000, { date: '2026-01-15' });
      * console.log(`Rate on Jan 15: ${result.rate}`);
      * ```

package/dist/index.d.ts

@@ -188,7 +188,8 @@ declare class AllRatesToday {
      */
     latest(options?: LatestOptions): Promise<LatestResponse>;
     /**
-     * Get exchange rates for a specific historical date.
+     * Get exchange rates for a specific historical date. Paid plans only: free and trial keys
+     * get a 403 `historical_requires_paid_plan` error.
      *
      * ```ts
      * // Using a string
@@ -203,7 +204,8 @@ declare class AllRatesToday {
      */
     forDate(date: string | Date, options?: ForDateOptions): Promise<ForDateResponse>;
     /**
-     * Get exchange rate time series between two dates.
+     * Get exchange rate time series between two dates. Paid plans only: free and trial keys
+     * get a 403 `historical_requires_paid_plan` error.
      *
      * ```ts
      * const data = await client.timeSeries('2026-01-01', '2026-03-31', {
@@ -245,7 +247,7 @@ declare class AllRatesToday {
      * console.log(`ECB ${usd.rate_date}: 1 EUR = ${usd.rate} USD`);
      * ```
      *
-     * Dated tables and history need a free key: see `/api/v1/central-bank/{bank}/{date}`.
+     * Dated tables and history need a paid plan: see `/api/v1/central-bank/{bank}/{date}`.
      */
     officialRates(bank: string, options?: OfficialRateOptions): Promise<OfficialRatesResponse>;
     /**
@@ -281,7 +283,8 @@ declare class AllRatesToday {
      */
     getRates(source: string, target: string, options?: RequestOptions): Promise<AuthRateResponse[]>;
     /**
-     * Get historical rates by period.
+     * Get historical rates by period. Paid plans only: free and trial keys
+     * get a 403 `historical_requires_paid_plan` error.
      *
      * ```ts
      * const history = await client.getHistoricalRates('USD', 'EUR', '30d');
@@ -299,7 +302,7 @@ declare class AllRatesToday {
      * const result = await client.convert('USD', 'EUR', 1000);
      * console.log(`$1,000 = €${result.result}`);
      *
-     * // Historical conversion
+     * // Historical conversion (paid plans only)
      * const result = await client.convert('USD', 'EUR', 1000, { date: '2026-01-15' });
      * console.log(`Rate on Jan 15: ${result.rate}`);
      * ```

package/dist/index.js

@@ -165,7 +165,8 @@ var AllRatesToday = class {
     return { base: params.source, date, rates };
   }
   /**
-   * Get exchange rates for a specific historical date.
+   * Get exchange rates for a specific historical date. Paid plans only: free and trial keys
+   * get a 403 `historical_requires_paid_plan` error.
    *
    * ```ts
    * // Using a string
@@ -190,7 +191,8 @@ var AllRatesToday = class {
     return { base: source, date: dateStr, rates };
   }
   /**
-   * Get exchange rate time series between two dates.
+   * Get exchange rate time series between two dates. Paid plans only: free and trial keys
+   * get a 403 `historical_requires_paid_plan` error.
    *
    * ```ts
    * const data = await client.timeSeries('2026-01-01', '2026-03-31', {
@@ -254,7 +256,7 @@ var AllRatesToday = class {
    * console.log(`ECB ${usd.rate_date}: 1 EUR = ${usd.rate} USD`);
    * ```
    *
-   * Dated tables and history need a free key: see `/api/v1/central-bank/{bank}/{date}`.
+   * Dated tables and history need a paid plan: see `/api/v1/central-bank/{bank}/{date}`.
    */
   async officialRates(bank, options = {}) {
     const code = bank.trim().toLowerCase();
@@ -311,7 +313,7 @@ var AllRatesToday = class {
         from: { currency: r.source, amount: 1 },
         to: { currency: r.target, amount: r.rate },
         rate: r.rate,
-        source: "interbank"
+        source: "mid-market"
       };
     }
     return raw;
@@ -329,7 +331,8 @@ var AllRatesToday = class {
     return this.request("/api/v1/rates", { source, target }, key);
   }
   /**
-   * Get historical rates by period.
+   * Get historical rates by period. Paid plans only: free and trial keys
+   * get a 403 `historical_requires_paid_plan` error.
    *
    * ```ts
    * const history = await client.getHistoricalRates('USD', 'EUR', '30d');
@@ -358,7 +361,7 @@ var AllRatesToday = class {
    * const result = await client.convert('USD', 'EUR', 1000);
    * console.log(`$1,000 = €${result.result}`);
    *
-   * // Historical conversion
+   * // Historical conversion (paid plans only)
    * const result = await client.convert('USD', 'EUR', 1000, { date: '2026-01-15' });
    * console.log(`Rate on Jan 15: ${result.rate}`);
    * ```

package/dist/index.mjs

@@ -139,7 +139,8 @@ var AllRatesToday = class {
     return { base: params.source, date, rates };
   }
   /**
-   * Get exchange rates for a specific historical date.
+   * Get exchange rates for a specific historical date. Paid plans only: free and trial keys
+   * get a 403 `historical_requires_paid_plan` error.
    *
    * ```ts
    * // Using a string
@@ -164,7 +165,8 @@ var AllRatesToday = class {
     return { base: source, date: dateStr, rates };
   }
   /**
-   * Get exchange rate time series between two dates.
+   * Get exchange rate time series between two dates. Paid plans only: free and trial keys
+   * get a 403 `historical_requires_paid_plan` error.
    *
    * ```ts
    * const data = await client.timeSeries('2026-01-01', '2026-03-31', {
@@ -228,7 +230,7 @@ var AllRatesToday = class {
    * console.log(`ECB ${usd.rate_date}: 1 EUR = ${usd.rate} USD`);
    * ```
    *
-   * Dated tables and history need a free key: see `/api/v1/central-bank/{bank}/{date}`.
+   * Dated tables and history need a paid plan: see `/api/v1/central-bank/{bank}/{date}`.
    */
   async officialRates(bank, options = {}) {
     const code = bank.trim().toLowerCase();
@@ -285,7 +287,7 @@ var AllRatesToday = class {
         from: { currency: r.source, amount: 1 },
         to: { currency: r.target, amount: r.rate },
         rate: r.rate,
-        source: "interbank"
+        source: "mid-market"
       };
     }
     return raw;
@@ -303,7 +305,8 @@ var AllRatesToday = class {
     return this.request("/api/v1/rates", { source, target }, key);
   }
   /**
-   * Get historical rates by period.
+   * Get historical rates by period. Paid plans only: free and trial keys
+   * get a 403 `historical_requires_paid_plan` error.
    *
    * ```ts
    * const history = await client.getHistoricalRates('USD', 'EUR', '30d');
@@ -332,7 +335,7 @@ var AllRatesToday = class {
    * const result = await client.convert('USD', 'EUR', 1000);
    * console.log(`$1,000 = €${result.result}`);
    *
-   * // Historical conversion
+   * // Historical conversion (paid plans only)
    * const result = await client.convert('USD', 'EUR', 1000, { date: '2026-01-15' });
    * console.log(`Rate on Jan 15: ${result.rate}`);
    * ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allratestoday/sdk",
-  "version": "1.4.7",
+  "version": "1.4.9",
   "description": "Exchange Rate API — Real-time mid-market currency exchange rates for Node.js and browsers. 160+ currencies, zero dependencies, free tier.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -33,6 +33,7 @@
     "fx",
     "exchangerate",
     "exchange rate",
+    "exchange rates",
     "currency-api",
     "currency-exchange-rates",
     "forex-api",