> ## 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 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)
* [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 with the desired FX pairs

### 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

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

#### 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"
}
```

### 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.

> **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` stream, which will produce *at most* one message per second, per subscribed pair.

## 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 | `{"op":"subscribe", "stream":"fx", "pairs":["EURUSD", "GBPUSD"]}` |

### 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/)