Skip to content

Use a proxy ​

Configure REST and WebSocket connections separately. These examples are for Node.js; browser applications cannot configure Node socket agents. Keep proxy URLs and passwords on the server, outside source control and logs.

A proxy changes your network route, not the selected exchange environment, account permissions or rate limits.

If your API key uses an IP allowlist, add the proxy's egress IP.

HTTP or HTTPS proxy for REST ​

Axios accepts a proxy object in the REST client's second constructor argument:

ts
import { SpotClient } from '@siebly/kraken-api';

export const client = new SpotClient(
  {},
  {
    proxy: { protocol: 'http', host: '127.0.0.1', port: 8080 },
    timeout: 20_000,
  },
);

Set protocol, host and port to your proxy, not the exchange. Use protocol: 'https' for a TLS connection to the proxy. For proxy authentication, add auth: { username, password } using values loaded from your environment or secret store.

In Node.js, Axios can also read HTTP_PROXY, HTTPS_PROXY and NO_PROXY when no explicit proxy is configured. Do not rely on those variables for WebSockets; configure their agent or constructor explicitly.

Proxy agents for REST and WebSockets ​

For an HTTP CONNECT proxy, install the agent in your project:

sh
npm install https-proxy-agent

Set PROXY_URL to a full HTTP or HTTPS proxy URL. If credentials are included in the URL, URL-encode the username and password components.

ts
import { HttpsProxyAgent } from 'https-proxy-agent';
import { SpotClient, WebsocketClient } from '@siebly/kraken-api';

const proxyUrl = process.env.PROXY_URL;
if (!proxyUrl) throw new Error('Set PROXY_URL to your HTTP or HTTPS proxy URL.');

const agent = new HttpsProxyAgent(proxyUrl);
const networkOptions = {
  proxy: false as const,
  httpsAgent: agent,
  timeout: 20_000,
};

export const client = new SpotClient({ keepAlive: false }, networkOptions);

export const ws = new WebsocketClient({
  restOptions: { keepAlive: false },
  requestOptions: networkOptions,
  wsOptions: { agent },
});

wsOptions.agent configures the WebSocket connection. REST settings alone do not route WebSocket traffic through a proxy. The WebSocket client's requestOptions also configures the REST call used to obtain a private Spot WebSocket token. The same REST constructor pattern applies to DerivativesClient.

proxy: false disables Axios's own proxy routing, including proxy environment variables, so the custom agent controls the REST route. Set keepAlive: false on the REST client and restOptions.keepAlive: false on the WebSocket client when using a custom agent. Enabling keep-alive replaces that agent with a standard HTTPS agent.

The wsOptions setting also applies to the WebSocket transport used by WebsocketAPIClient.

SOCKS5 ​

Install socks-proxy-agent, replace the HttpsProxyAgent import with SocksProxyAgent, and construct the agent from your SOCKS proxy URL:

sh
npm install socks-proxy-agent
ts
import { SocksProxyAgent } from 'socks-proxy-agent';

const agent = new SocksProxyAgent('socks5h://127.0.0.1:1080');

socks5h:// resolves destination hostnames through the proxy. Keep proxy: false for REST and pass the agent as httpsAgent; Axios's proxy object does not support SOCKS.

Use the same SOCKS agent in wsOptions.agent. Keep the internal REST requestOptions as well.

Verify the route ​

Start with a public REST request such as client.getTicker({ pair: 'XBTUSD' }) and a public subscription using the configured clients. No API credentials are needed for these checks. Confirm both connections in your proxy logs; a successful REST request alone does not prove WebSocket routing.

  • A 407 response usually means proxy authentication is missing or rejected.
  • Connection timeouts can indicate the proxy cannot reach the exchange or does not allow CONNECT/WebSocket traffic.
  • Keep TLS certificate verification enabled. For an approved corporate proxy, use its trusted CA rather than disabling verification.
  • Extra latency can affect signed-request timing. Keep the machine clock synchronized and distinguish the HTTP timeout from the exchange's acceptance window.
  • Do not log whole request configurations, proxy URLs with credentials or signed request data.

See configuration, production usage and the Siebly proxy guide.

Built by Siebly. Open source SDKs for exchange APIs.