How to use Proxies with Siebly SDKs

Using proxies

Short guide for routing REST and WebSocket traffic through HTTP or SOCKS proxies with Siebly Node SDKs (binance, bybit-api, okx-api, etc.).

Why bother

• Spread REST load across IPs (rate limits / IP bans)
• Reach region-gated endpoints from the right location
• Keep signing in-process - the proxy only forwards bytes

Extra latency can blow past recv_window. If private REST starts failing after you add a proxy, bump the window first, then debug the proxy.

Install

npm install https-proxy-agent socks-proxy-agent

How it wires in

Traffic	Where to put the proxy
REST	2nd constructor arg (axios config). Not inside key options.
WebSocket socket	wsOptions.agent
WS clients that also call REST (listen keys / tokens)	wsOptions.agent and requestOptions

SDKs that need both for private WS: binance (user-data / listen keys), kucoin-api, @siebly/kraken-api.

Everyone else for WS: wsOptions.agent is enough (bybit-api, okx-api, bitget-api, bitmart-api, gateio-api, coinbase-api).

---

1. REST - axios native HTTP proxy

Works for many providers. Try this first.

import { RestClientV5 } from "bybit-api";

const client = new RestClientV5(
  {
    key: process.env.API_KEY,
    secret: process.env.API_SECRET,
    // recv_window: 10000, // if proxy latency causes timestamp errors
  },
  {
    proxy: {
      protocol: "http",
      host: process.env.PROXY_HOST!,
      port: Number(process.env.PROXY_PORT),
      auth: {
        username: process.env.PROXY_USER!,
        password: process.env.PROXY_PASS!,
      },
    },
  },
);

// Prove routing before you touch private endpoints
console.log(await client.getServerTime());

Same 2nd-arg shape on the other REST clients (MainClient, RestClient, SpotClient, CBAdvancedTradeClient, …).

2. REST - HttpsProxyAgent (when native proxy fails)

Some providers ignore axios proxy. Use an agent instead:

import { HttpsProxyAgent } from "https-proxy-agent";
import { RestClientV5 } from "bybit-api";

const proxyUrl = `http://${process.env.PROXY_USER}:${process.env.PROXY_PASS}@${process.env.PROXY_HOST}:${process.env.PROXY_PORT}`;
const agent = new HttpsProxyAgent(proxyUrl);

const client = new RestClientV5(
  { key: process.env.API_KEY, secret: process.env.API_SECRET },
  { httpAgent: agent, httpsAgent: agent },
);

console.log(await client.getServerTime());

For SOCKS on REST, same pattern with SocksProxyAgent and a socks5://… URL.

3. WebSocket - SOCKS5 (public streams)

import { WebsocketClient } from "binance";
import { SocksProxyAgent } from "socks-proxy-agent";

const agent = new SocksProxyAgent(process.env.SOCKS_PROXY_URL!);

const ws = new WebsocketClient({
  wsOptions: { agent },
});

ws.on("open", ({ wsKey }) => console.log("open", wsKey));
ws.subscribeAll24hrTickers("usdm");

HTTP proxy on the socket: swap in HttpsProxyAgent the same way.

4. WebSocket + internal REST (listen key / token)

Binance private user-data, KuCoin, Kraken: socket and the REST the client fires for tokens/listen keys must go through the proxy.

import { WebsocketAPIClient } from "binance";
import { HttpsProxyAgent } from "https-proxy-agent";

const proxyUrl = `http://${process.env.PROXY_USER}:${process.env.PROXY_PASS}@${process.env.PROXY_HOST}:${process.env.PROXY_PORT}`;
const agent = new HttpsProxyAgent(proxyUrl);

const ws = new WebsocketAPIClient({
  api_key: process.env.API_KEY,
  api_secret: process.env.API_SECRET,
  wsOptions: { agent },
  requestOptions: {
    httpAgent: agent,
    httpsAgent: agent,
    // or: proxy: { protocol: 'http', host, port, auth: { username, password } }
  },
});

KuCoin / Kraken: same idea - wsOptions.agent + requestOptions with the agent (or axios proxy).

Bybit / Gate / OKX / Bitget / BitMart / Coinbase WS: only wsOptions.agent.

---

Sanity checklist while testing

1. Hit a public REST method (getServerTime / ticker) through the proxy.
2. Confirm the egress IP (provider dashboard or an IP-echo service via the same agent).
3. Then private REST / private WS.
4. Still getting timestamp / recv window errors? Raise recv_window / recvWindow.
5. Axios native proxy weird? Switch to HttpsProxyAgent / SocksProxyAgent.
6. Private WS connects but listen key / token fails? You forgot requestOptions.

No built-in rotation - rotate in your app or at the provider.

Further reading

• bybit-api examples: examples/Rest/rest-v5-proxies.ts, rest-v5-proxies2.ts
• binance example: examples/WebSockets/Misc/ws-proxy-socks.ts
• Agent libs: https-proxy-agent, socks-proxy-agent