PrimeAPI.io WebSocket Documentation

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.

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.

Table of Contents

• Fundamentals
  • Basic Flow - Connect, Auth, Subscribe
  • JSON Message Format & Examples
  • Limitations, Message Volumes
• Examples, Demos, Code Snippets & Client Libraries
  • WebSocket Playground
  • JSFiddle (JavaScript) Example
  • Client Libraries
  • Docker Image

Fundamentals

Basic Flow - Connect, Auth, Subscribe

1. Connect to wss://euc2.primeapi.io (and receive a connect message from the server)
2. Send an auth message with your API key (get a free API key here)
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

{
  "op":"auth",
  "key":"you-api-key-here"
}

Subscribe

JSON

{
  "op": "subscribe",
  "stream": "fx",
  "pairs": ["EURUSD", "GBPUSD"]
}

Downstream

Connect (sent by server on connect)

JSON

{
  "op": "connect",
  "status": 200,
  "tsp": 1745877646598,
  "msg": "Connected to serverID"
}

Auth Response

JSON

{
  "op": "auth",
  "status": 200,
  "tsp": 1745877646598,
  "msg": "Authenticated OK"
}

Subscribe Response

JSON

{
  "op": "subscribe",
  "status": 200,
  "tsp": 1745877671164,
  "msg": "Subscribed to 2 streams"
}

Price

JSON

{
  "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 Premium Package allows for 2 connections and up to 20 pairs per connection.

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 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://euc2.primeapi.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/ufyjkswg/

Client Libraries

PHP Client & Reference Implementation

https://github.com/PrimeAPI-io/primeapi-websocket-client-php

Bash

composer install primeapi/php-websocket-client

Docker Image

We've wrapped up the PHP client in a Docker image for easy access.

Bash

docker run --rm primeimg/php-websocket-client:latest php /app/bin/demo.php --key=YOUR-API-KEY --pairs=EURUSD,GBPUSD