Getting started

Install

npm install coinrayjs

coinrayjs ships ES modules and TypeScript types. It works in the browser and in Node.

:::info Paid product Coinray API access is a paid product — you need an active Coinray plan to obtain a token. Real-time streaming and candle history are included; the trading order builders require an additional paid addon on top. Contact Coinray to get access. :::

Create a client

The Coinray client takes a Coinray JWT token. Point every endpoint at the Coinray gateway (gateway.coinray.eu) — it fronts the REST API, order placement, and the WebSocket stream.

import Coinray from "coinrayjs";

const coinray = new Coinray(token, {
  apiEndpoint: "https://gateway.coinray.eu",
  orderEndpoint: "https://gateway.coinray.eu",
  websocketEndpoint: "wss://gateway.coinray.eu/v1",
});

Get a token

Create an API key in the Coinray portal at app.coinray.eu/api_keys. The key gives you a client_id and client_secret. Exchange them for a JWT with the client-credentials endpoint:

curl -X POST https://app.coinray.eu/oauth/token \
  -d client_id=YOUR_KEY_ID \
  -d client_secret=YOUR_SECRET

{ "access_token": "eyJ...", "token_type": "Bearer", "expires_in": 2592000 }

Tokens are valid for 30 days on paid plans (trial keys expire 7 days after registration). There is no refresh token: call the endpoint again to get a fresh one. Keep the client_secret on your backend, never in the browser.

A minimal Node helper that does the exchange, e.g. on your backend:

async function fetchFreshCoinrayToken() {
  const res = await fetch("https://app.coinray.eu/oauth/token", {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      client_id: process.env.COINRAY_KEY_ID,
      client_secret: process.env.COINRAY_SECRET,
    }),
  });
  if (!res.ok) throw new Error(`coinray token request failed: ${res.status}`);
  const { access_token } = await res.json();
  return access_token;
}

Token expiry & refresh

Coinray tokens expire. Register a refresh callback and the client will call it when the token is close to expiring, then keep using the new token. Start the periodic check with checkToken().

coinray.onTokenExpired(async () => {
  const newToken = await myBackend.fetchFreshCoinrayToken(); // see "Get a token" above
  return newToken; // the client adopts it automatically
});

coinray.checkToken(); // begins the expiry watch loop

// You can also push a new token in at any time:
coinray.refreshToken(newToken);

Connection lifecycle

The WebSocket connection is opened lazily on the first subscription, but you can manage it explicitly. Subscriptions are automatically re-established on reconnect.

coinray.onOpen(() => console.log("connected"));
coinray.onError((e) => console.error("socket error", e));

await coinray.connect();   // open the socket
coinray.reconnect();       // drop and reopen
coinray.disconnect();      // close the socket, keep subscriptions
coinray.destroy();         // tear everything down (timers, listeners, socket)

:::tip Always clean up Call coinray.destroy() when your component unmounts or your process shuts down — it clears the token-check interval and the time-offset timer as well as the socket. :::

Using CoinrayCache for discovery

If you need the list of exchanges and their markets (and want them kept fresh), use CoinrayCache. It wraps a Coinray client and refreshes on an interval.

import {CoinrayCache} from "coinrayjs";

const cache = new CoinrayCache(token, {apiEndpoint: "https://gateway.coinray.eu"});
await cache.initialize();

const exchanges = cache.getExchanges();
const binanceMarkets = cache.getExchange("BINA").markets;
const market = cache.getMarket("BINA_BTC_USDT");

cache.destroy(); // stop refresh timers when done

Next: stream live market data →