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:

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)

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)

// 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:

{
  "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.

await client.latest({
  base: "USD",
  symbols: "XAU,XAG"
});

historical(params: HistoricalParams)

Get historical rates for a given date (YYYY-MM-DD).

await client.historical({
  date: "2024-05-15",
  base: "USD",
  symbols: "XAU,XAG"
});

timeSeries(params: TimeSeriesParams)

Retrieve time-series data between two dates.

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.

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.

await client.convert({
  from: "USD",
  to: "XAU",
  amount: 100
});

symbols()

List available symbols and their metadata (depends on plan).

await client.symbols();

seasonality(params: SeasonalityParams)

Retrieve seasonality metrics for a given symbol.

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.

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.