> ## Documentation Index
> Fetch the complete documentation index at: https://www.fastforex.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# WebSockets

> Realtime streaming bid/ask prices for ~2,300 FX trading pairs and 40+ metals instruments via a secure WebSocket connection.

If you need an API key, [sign up here](https://console.fastforex.io).

WebSockets are reliable, well established and easily accessible - natively supported both in-browser (JavaScript) and
server-side, with libraries and example code available in most programming languages.

![WebSockets](https://storage.googleapis.com/primeapi-static/PrimeAPI-WebSocket-Demo-1x-15fps.gif)

## Table of Contents

* [Fundamentals](#fundamentals)
* [Basic Flow - Connect, Auth, Subscribe](#basic-flow---connect-auth-subscribe)
* [Streams - FX and Metals](#streams---fx-and-metals)
* [JSON Message Format & Examples](#json-message-format--examples)
* [Limitations, Message Volumes](#limitations-message-volumes)
* [Examples, Demos, Code Snippets & Client Libraries](#examples-demos-code-snippets--client-libraries)
* [WebSocket Playground](#websocket-playground)
* [JSFiddle (JavaScript) Example](#jsfiddle-javascript-example)

## Fundamentals

### Basic Flow - Connect, Auth, Subscribe

1. Connect to `wss://fastforex.wsdx.io` (and receive a `connect` message from the server)
2. Send an `auth` message with your API key ([get a free API key here](https://console.fastforex.io))
3. Send a `subscribe` message naming the stream you want, plus the desired pairs or instruments

### Streams - FX and Metals

The same connection serves both FX trading pairs and metals instruments. You choose which by setting
`stream` on your `subscribe` message.

| Stream | Contents | Rate |
| :- | :- | :- |
| `fx` | \~2,300 FX trading pairs | Every tick |
| `fx1s` | \~2,300 FX trading pairs | At most one message per second, per pair |
| `metals` | 40+ metals instruments | Every tick |
| `metals1s` | 40+ metals instruments | At most one message per second, per instrument |

Everything else works identically across the four - the same `auth` flow, the same message shapes, and the
same `price` payload. Only the `stream` value and the symbols you subscribe to change.

Use the symbols from [`/metals/instruments`](/docs/api-reference/metals/instruments) for the metals streams, and
[`/fx/pairs`](/docs/api-reference/fx/pairs) for the FX streams.

You can subscribe to more than one stream on a single connection - send a `subscribe` message for each.

Access is granted per stream. If your plan does not include a stream, subscribing to it returns a `403`
with `No access to requested stream`.

### JSON Message Format & Examples

Messages are sent and received in JSON format. All messages have an `op` field, which indicates the operation type.

Messages from the server ("downstream") will usually contain

* a `status` field, which indicates the success or failure of the operation.
* We follow HTTP status codes for this. e.g. `200` = success, `401` = not authenticated, etc.
* a `tsp` field which indicates the timestamp of the message in milliseconds since epoch (Unix time).

#### Upstream (sent to the WebSocket server)

Auth

```json theme={null}
{
  "op":"auth",
  "key":"your-api-key-here"
}
```

Subscribe (FX)

```json theme={null}
{
  "op": "subscribe",
  "stream": "fx",
  "pairs": ["EURUSD", "GBPUSD"]
}
```

Subscribe (Metals)

```json theme={null}
{
  "op": "subscribe",
  "stream": "metals",
  "pairs": ["XAUUSD", "XAGUSD"]
}
```

#### Downstream

Connect (sent by server on connect)

```json theme={null}
{
  "op": "connect",
  "status": 200,
  "tsp": 1745877646598,
  "msg": "Connected to server"
}
```

Auth Response

```json theme={null}
{
  "op": "auth",
  "status": 200,
  "tsp": 1745877646598,
  "msg": "Authenticated OK"
}
```

Subscribe Response

```json theme={null}
{
  "op": "subscribe",
  "status": 200,
  "tsp": 1745877671164,
  "msg": "Subscribed to 2 streams"
}
```

Price

```json theme={null}
{
  "op": "price",
  "sym": "EURUSD",
  "bid": "1.14218",
  "ask": "1.14218"
}
```

Metals prices arrive in the same shape, with the instrument symbol in `sym`

```json theme={null}
{
  "op": "price",
  "sym": "XAUUSD",
  "bid": "4192.11658",
  "ask": "4192.13407"
}
```

### Limitations, Message Volumes

Depending on your subscription plan, you may be limited on the number of concurrent WebSocket connections you can make, and to the maximum number of pairs per connect.

Our standard offering allows for 2 connections and up to 5 pairs per connection. Contact us for higher limits.

The symbol allowance is shared across streams on a connection - FX pairs and metals instruments count towards
the same total. Subscribing to 5 FX pairs on a 5 symbol plan leaves no room for metals on that connection.
Use a second connection, or spread your symbols across both.

Subscribing beyond your allowance does not fail outright. The server subscribes you to as many symbols as it
can and replies `429` with `Capping concurrent symbols`, so check the status on your subscribe response.

> **Warning - High Message Volume**
>
> Popular pairs such as `EURUSD` can generate a **lot** of messages at peak times - up to **hundreds of messages per second**.
>
> Your application should be able to handle this. Connections may be closed if you cannot consume at the publish rate.
>
> Depending on your application needs, when sending your `subscribe` message, you can choose to use
> the `fx1s` or `metals1s` streams, which will produce *at most* one message per second, per subscribed symbol.

## Examples, Demos, Code Snippets & Client Libraries

### WebSocket Playground

[WebSocket King](https://websocketking.com/) is a great in-browser tool for testing WebSocket connections.

You'll need the following information and example payloads to get started:

| Field | Value |
| :- | :- |
| Server | `wss://fastforex.wsdx.io` |
| Auth | `{"op":"auth", "key":"YOUR-API-KEY-HERE"}` |
| Subscribe (FX) | `{"op":"subscribe", "stream":"fx", "pairs":["EURUSD", "GBPUSD"]}` |
| Subscribe (Metals) | `{"op":"subscribe", "stream":"metals", "pairs":["XAUUSD", "XAGUSD"]}` |

### JSFiddle (JavaScript) Example

A really simple in-browser, native JavaScript example of connecting to the WebSocket server, authenticating and subscribing to a stream.

[https://jsfiddle.net/ycquz7px/](https://jsfiddle.net/ycquz7px/)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.