Integrate a live, reliable price layer into your system through one API.

Start in three steps

Authentication and limits

Every request carries an access token in the Authorization header. Some endpoints require an additional permission scope.

The scopes

Headers and rate limit

Read these headers to pace your requests without overrunning, and build your retry logic with confidence.

Test mode

Try the response shape before your tokens are issued. Send the literal token test and the response arrives in its full shape with all numeric values zeroed, so you build your integration on the real structure without live data.

Endpoints

https://barqmetal.com/api/v1

Every request needs an access token. Endpoints marked with a scope require an additional permission.

Example response

A fixed shape for every response. Any change is coordinated with consuming systems in advance, so your integration never breaks suddenly.

This is a base response. With the instant_change scope an instant-change field is added to each metal, and with the daily_stats scope a today-statistics field. See the endpoint reference below for every field by type.

Per-gram prices arrive with four decimals, per-ounce and karat prices with two. The values in the example are illustrative, so read the precision from the field reference, not from the example.

When you request a single metal via symbol, the data field returns a single object, not an array. Without symbol it returns an array of every metal.

{
  "success": true,
  "currency": "SAR",
  "request_time": "2026-08-14T11:42:05.417+03:00",
  "system": { "is_running": true, "last_update": "2026-08-14T11:42:05.417+03:00", "server_time": "2026-08-14T11:42:05.417+03:00" },
  "data": [
    {
      "metal": { "id": 1, "symbol": "XAU", "name_ar": "الذهب", "name_en": "Gold" },
      "state": "live",
      "prices": {
        "buy_per_ounce": 12545.60,
        "sell_per_ounce": 12551.20,
        "buy_per_gram": 403.20,
        "sell_per_gram": 403.50,
        "fetched_at": "2026-08-14T11:42:05.417+03:00",
        "last_success_at": "2026-08-14T11:42:07.912+03:00",
        "price_changed_at": "2026-08-14T11:40:11.005+03:00"
      },
      "karats": {
        "24": { "sell_per_gram": 403.50 },
        "22": { "sell_per_gram": 369.88 },
        "21": { "sell_per_gram": 353.06 },
        "18": { "sell_per_gram": 302.63 }
      }
    }
  ]
}

Endpoint reference

Each endpoint with its params and response fields by type and meaning, so you integrate against this page alone, no conversation needed.

Errors and codes

Every error returns one fixed shape, a status code and an object explaining the cause, so your system builds its retry logic with confidence.

{
  "success": false,
  "error": "...",
  "status": 404,
  "request_time": "2026-08-14T11:42:05+03:00"
}

An errors field is attached with a 422 only, carrying the details of the invalid param. And with a 429 you may receive a Retry-After header telling you when to retry.

Live streaming

Instead of repeated polling, subscribe once and every update reaches you at the same instant. Two steps, authenticate the channel, then connect.

1. 01 Authenticate the channelSend a POST to /websocket/auth with a token carrying the live_stream scope, and you receive the temporary connection details.
2. 02 Connect and receiveOpen the connection using those details, and every price update reaches you the moment it happens, in the same shape with its state attached.

Code samples

Copy and start. Replace TOKEN with your access token.

curl -H "Authorization: Bearer TOKEN" \
  "https://barqmetal.com/api/v1/prices?currency=SAR"

const res = await fetch(
  "https://barqmetal.com/api/v1/prices?currency=SAR",
  { headers: { Authorization: "Bearer TOKEN" } }
);
const { data } = await res.json();
console.log(data[0].state, data[0].prices.sell_per_gram);

// npm install pusher-js
// GET /websocket/info returns host, port, key, scheme and the channel name
import Pusher from "pusher-js";

const pusher = new Pusher("YOUR_APP_KEY", {
  wsHost: "YOUR_HOST",
  wsPort: YOUR_PORT,
  forceTLS: false,
  enabledTransports: ["ws", "wss"],
  authEndpoint: "https://barqmetal.com/api/v1/websocket/auth",
  auth: { headers: { Authorization: "Bearer TOKEN" } }
});

// the client POSTs socket_id + channel_name to the auth endpoint for you
const channel = pusher.subscribe("private-prices");
channel.bind("price.updated", (p) => {
  console.log(p.metal.symbol, p.prices.sell_per_gram, p.state);
});

Try it

Choose an endpoint and press Run for a live response straight from the API, alongside a ready cURL command and JavaScript code to copy.

Developer FAQ