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.

Allow the proxy's egress IP when your API key uses an IP allowlist. Do not log proxy credentials.

HTTP or HTTPS proxy for REST ​

Pass Axios proxy options in the REST client's second constructor argument:

ts
import { RestClient } from 'okx-api';

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

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 { RestClient, WebsocketClient } from 'okx-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);

export const client = new RestClient({ keepAlive: false }, {
  httpsAgent: agent,
  proxy: false,
  timeout: 20_000,
});
export const ws = new WebsocketClient({ wsOptions: { agent } });

proxy: false disables Axios proxy handling, including environment-variable proxy routing, so the custom agent controls the route. Keep keepAlive: false; enabling it replaces the custom HTTPS agent.

REST configuration does not route WebSocket traffic. Set wsOptions.agent separately, including on WebsocketAPIClient when using WebSocket commands. Unlike token-based exchange SDKs, OKX private WebSockets authenticate with signed login messages rather than fetching a REST token.

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 SOCKS agent for both httpsAgent and wsOptions.agent, retaining proxy: false and keepAlive: false for REST.

Verify both transports ​

Make a public getTicker({ instId: 'BTC-USDT' }) request and a public ticker subscription using the configured clients. Confirm REST and WebSocket connections separately in proxy logs. A successful REST request alone does not verify the WebSocket path.

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