npm package: @metals-api/sdk
Description: Official Node.js client for the Metals-API.
Author: Zyla Labs
Latest version: 0.1.0

## Metals-API Node.js SDK

Official Node.js SDK for Metals-API – a powerful API for accessing comprehensive and accurate real-time and historical rates on precious metals and related instruments.

Metals-API supports a wide set of metals symbols with updates as fast as every 60 seconds (depending on your plan). Start a 7‑day free trial and cancel anytime.

### Key Features

- **Built for developers**: Simple, typed API designed for Node.js and TypeScript.
- **Robust JSON API**: Thin, predictable wrapper over the Metals-API JSON endpoints.
- **Top-tier security**: Your API key is sent over HTTPS to trusted, enterprise-grade infrastructure.
- **Reliable data sources**: Data aggregated from reputable financial and metals providers.
- **Flexible integration**: Works in any Node.js app (CommonJS or ESM) and with TypeScript.
- **Historical data access**: Query historical and time-series data for deeper analysis.
- **Exceptional accuracy**: Real-time and historical data with high precision.
- **User-friendly documentation**: See the full API docs at `https://metals-api.com/documentation`.
- **Specialized support**: Dedicated support team to help with integration and use-cases.

### Supported Metals

Metals-API covers a wide range of instruments, including:

- **Precious metals**: Gold (XAU), Silver (XAG), Platinum (XPT), Palladium (XPD), and more.
- **Metal-related pairs**: FX pairs and metal-quoted symbols depending on your plan.

You can find the full, always up-to-date list of supported symbols in the Supported Metals section of the official documentation.

## Installation

Install the SDK from npm:

```bash
npm install @metals-api/sdk
```

This package is written in TypeScript and ships with type definitions out of the box.

## Getting Started

First, sign up at Metals-API to get your API key and some free credits.

### Basic Usage (TypeScript / ESM)

```ts
import { MetalsClient } from "@metals-api/sdk";

const client = new MetalsClient("REPLACE-WITH-YOUR-ACCESS-KEY");

async function main() {
  const latest = await client.latest({
    base: "USD",
    symbols: "XAU,XAG"
  });

  console.log(latest);
}

main().catch(err => {
  console.error(err);
  process.exit(1);
});
```

### Basic Usage (CommonJS)

```ts
// If your project uses CommonJS, you can import via dynamic import:
(async () => {
  const { MetalsClient } = await import("@metals-api/sdk");

  const client = new MetalsClient("REPLACE-WITH-YOUR-ACCESS-KEY");
  const latest = await client.latest({
    base: "USD",
    symbols: "XAU,XAG"
  });

  console.log(latest);
})();
```

## Example Response

Example response for a successful latest request:

```json
{
  "data": {
    "success": true,
    "timestamp": 1715796300,
    "date": "2024-05-15",
    "base": "USD",
    "rates": {
      "XAU": 0.000444,
      "XAG": 0.0321,
      "USD": 1,
      "USDXAU": 2250.5,
      "USDXAG": 31.15
    },
    "unit": {
      "XAU": "per troy ounce",
      "XAG": "per troy ounce"
    }
  }
}
```

The exact structure of the `data` object depends on the endpoint and your plan. Refer to the official documentation for the complete schema.

## Available Methods

All methods live on the `MetalsClient` class.

### `latest(params?: LatestParams)`

Fetches the most recent rates for the requested symbols.

```ts
await client.latest({
  base: "USD",
  symbols: "XAU,XAG"
});
```

### `historical(params: HistoricalParams)`

Get historical rates for a given date (YYYY-MM-DD).

```ts
await client.historical({
  date: "2024-05-15",
  base: "USD",
  symbols: "XAU,XAG"
});
```

### `timeSeries(params: TimeSeriesParams)`

Retrieve time-series data between two dates.

```ts
await client.timeSeries({
  start_date: "2024-05-01",
  end_date: "2024-05-15",
  base: "USD",
  symbols: "XAU,XAG"
});
```

### `fluctuation(params: FluctuationParams)`

Get day-to-day or period fluctuation data.

```ts
await client.fluctuation({
  start_date: "2024-05-01",
  end_date: "2024-05-15",
  base: "USD",
  symbols: "XAU,XAG"
});
```

### `convert(params: ConvertParams)`

Convert an amount between two symbols.

```ts
await client.convert({
  from: "USD",
  to: "XAU",
  amount: 100
});
```

### `symbols()`

List available symbols and their metadata (depends on plan).

```ts
await client.symbols();
```

### `seasonality(params: SeasonalityParams)`

Retrieve seasonality metrics for a given symbol.

```ts
await client.seasonality({
  symbol: "XAU",
  group_by: "month",
  base: "USD",
  years: 5
});
```

Types like `LatestParams`, `HistoricalParams`, `TimeSeriesParams`, etc. are exported from the SDK for strong typing in TypeScript projects.

## Error Handling

All requests may throw a `MetalsApiError` when:

- **The API returns an error payload**, or
- **The network fails**, or
- **The response is not valid JSON**.

```ts
import { MetalsClient, MetalsApiError } from "@metals-api/sdk";

const client = new MetalsClient("REPLACE-WITH-YOUR-ACCESS-KEY");

async function main() {
  try {
    const latest = await client.latest({ base: "USD", symbols: "XAU,XAG" });
    console.log(latest);
  } catch (err) {
    if (err instanceof MetalsApiError) {
      console.error("Status code:", err.statusCode);
      console.error("Error code:", err.errorCode);
      console.error("Message:", err.message);
    } else {
      console.error("Unexpected error:", err);
    }
  }
}

main().catch(console.error);
```

## Documentation & Support

- **API documentation**: `https://metals-api.com/documentation`
- **Website**: `https://metals-api.com`

If you have questions or need help with integration, please reach out through the official support channels listed in the Metals-API dashboard.