Gate.io Futures API TypeScript SDK: A Production Integration Guide

Gate publishes an official Node client, gate-api, generated from OpenAPI. It is not abandoned, but generated clients are awkward in real trading code. Method names follow the spec, types are noisy, and there is no first-class awaitable WebSocket API. Teams usually wrap them anyway, then end up maintaining that wrapper.

The gateio-api package is a hand-written TypeScript SDK for Gate.com / Gate.io. One RestClient covers spot, margin, perpetual futures, delivery futures, options, and the newer CrossEx, Alpha, and OTC APIs. WebsocketClient handles public and private streams. WebsocketAPIClient wraps the WebSocket API so you can await an order instead of correlating events yourself.

Signing, timestamps, reconnect, heartbeat, and resubscribe are inside the SDK. Rate-limiting is not. If you burst past Gate's order-entry limits, that is on you.

npm install gateio-api

Create API keys in Gate API Key Management. Use a trading key with no withdrawal permission, and lock it to IPs you control.

const { RestClient } = require("gateio-api");

const client = new RestClient({
  apiKey: process.env.GATE_API_KEY,
  apiSecret: process.env.GATE_API_SECRET,
});

Public market data works without keys. Private calls need both apiKey and apiSecret. More examples live in the gateio-api documentation and in the SDK examples folder.

Gate.io v4 does not use a nonce. It uses a timestamp in seconds plus HMAC-SHA512 over that method/path/query/body-hash/timestamp string. RestClient builds this for every private request. You should not assemble SIGN headers yourself.

Keep keys in environment variables. Least privilege means: trading if you place orders, read-only if you do not, withdrawals off unless you have a very good reason.

const { RestClient } = require("gateio-api");

const client = new RestClient({
  apiKey: process.env.GATE_API_KEY,
  apiSecret: process.env.GATE_API_SECRET,
  baseUrl: "https://api-testnet.gateapi.io/api/v4",
});

The SDK also has baseUrlKey: 'futuresTestnet'. Testnet keys are not live keys. Do not mix them.

WebSocket testnet is a flag, not a URL you paste in:

const { WebsocketClient } = require("gateio-api");

const ws = new WebsocketClient({
  apiKey: process.env.GATE_API_KEY,
  apiSecret: process.env.GATE_API_SECRET,
  useTestnet: true,
});

Spot WebSockets have no testnet URL in the SDK. Futures, delivery, and options do.

A USDT perpetual limit order needs settle, contract, size, and price. Size is in contracts, not coins. Positive size is long, negative is short.

const { RestClient } = require("gateio-api");

const client = new RestClient({
  apiKey: process.env.GATE_API_KEY,
  apiSecret: process.env.GATE_API_SECRET,
});

async function placeLimitOrder() {
  const order = await client.submitFuturesOrder({
settle: "usdt",
contract: "BTC_USDT",
size: 10,
price: "45000",
tif: "gtc",
  });

  // REST futures orders use `id`, not `order_id`
  console.log(order.id, order.fill_price, order.status);
}

placeLimitOrder().catch(console.error);

A market order is the same method with price: '0' and tif: 'ioc':

const order = await client.submitFuturesOrder({
  settle: "usdt",
  contract: "BTC_USDT",
  size: 20,
  price: "0",
  tif: "ioc",
});

Response fields are typed. For REST futures the order id is id. fill_price is on the same object. Some other Gate endpoints and the WebSocket API use order_id instead, so do not assume one name everywhere.

Gate's normal perpetual private limits are per UID: 100 requests per second for place and amend, 200 per second for cancel, and 200 per 10 seconds for other private futures endpoints. On top of that, Gate applies an abuse rule on a rolling 24-hour window. If you send more than 86,400 place, amend, and cancel requests in 24 hours with no fills, placement is cut to 10 requests per 10 seconds for the next hour. If the fill ratio is under 1%, it is cut to 20 requests per 10 seconds. The older 7,200-per-hour rule is gone.

gateio-api does not queue or throttle. Put a token bucket or a local queue in front of submitFuturesOrder if your strategy can burst.

Raw WebSockets are annoying for orders: you send on one channel, then wait for a matching event on another. WebsocketAPIClient hides that. You call a method and await the reply. Under the hood it still uses a persisted, authenticated WebSocket.

Futures WebSocket commands default to USDT perpetuals (perpFuturesUSDTV4). Pass a different wsKey if you are on BTC-margined or delivery contracts.

const { WebsocketAPIClient, WS_KEY_MAP } = require("gateio-api");

async function start() {
  const wsClient = new WebsocketAPIClient({
apiKey: process.env.GATE_API_KEY,
apiSecret: process.env.GATE_API_SECRET,
reauthWSAPIOnReconnect: true,
  });

  const futuresWsKey = WS_KEY_MAP.perpFuturesUSDTV4;

  const newFuturesOrder = await wsClient.submitNewFuturesOrder(
{
contract: "BTC_USDT",
size: 10,
price: "31503.28",
tif: "gtc",
text: "t-my-custom-id",
},
futuresWsKey,
  );

  console.log("Futures order result:", newFuturesOrder.data);

  const cancelFuturesOrder = await wsClient.cancelFuturesOrder(
{ order_id: String(newFuturesOrder.data.id) },
futuresWsKey,
  );

  console.log("Cancel result:", cancelFuturesOrder.data);
}

start().catch(console.error);

You can still drop down to WebsocketClient.sendWSAPIRequest if you want the event-driven style. For most order-intent code, the promise client is the one you want. Same request shape, less callback bookkeeping. See order intent workflows if you are building a chaser on top of this.

const { RestClient } = require("gateio-api");

const client = new RestClient({
  apiKey: process.env.GATE_API_KEY,
  apiSecret: process.env.GATE_API_SECRET,
});

async function accountSnapshot() {
  const account = await client.getFuturesAccount({ settle: "usdt" });
  console.log(account.available, account.unrealised_pnl, account.currency);

  const positions = await client.getFuturesPositions({ settle: "usdt" });
  for (const position of positions) {
console.log(
position.contract,
position.size,
position.leverage,
position.unrealised_pnl,
);
  }
}

accountSnapshot().catch(console.error);

Leverage is per contract. Isolated 10x sets leverage to '10'. Cross 10x sets leverage to '0' and cross_leverage_limit to '10'. If you pass both a non-zero leverage and cross_leverage_limit, Gate treats it as isolated and ignores the cross field.

// Isolated 10x
await client.updateFuturesLeverage({
  settle: "usdt",
  contract: "BTC_USDT",
  leverage: "10",
});

// Cross 10x
await client.updateFuturesLeverage({
  settle: "usdt",
  contract: "BTC_USDT",
  leverage: "0",
  cross_leverage_limit: "10",
});

BTC perpetuals commonly go up to 125x. Altcoin caps are lower and move with the risk-limit table. Check leverage_max on the position if you need the live cap.

Funding is an 8-hour transfer between longs and shorts, not an exchange trading fee. Many contracts fund around 00:00, 08:00, and 16:00 UTC, but the actual next time is on the contract (funding_next_apply / funding_interval). Read it from the ticker or contract endpoint instead of hard-coding the clock.

VIP tiers run from VIP 0 to VIP 16. USDT perpetual fees start at 0.02% maker and 0.05% taker at VIP 0. Higher VIP cuts those rates. VIP also affects how generous fill-ratio rate limits get for large accounts.

Private futures topics need your Gate user id in the payload. Subscribe on the matching wsKey. For USDT perps that is perpFuturesUSDTV4.

const { WebsocketClient } = require("gateio-api");

const ws = new WebsocketClient({
  apiKey: process.env.GATE_API_KEY,
  apiSecret: process.env.GATE_API_SECRET,
});

ws.on("update", (data) => {
  console.log("data", data);
});

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

ws.on("reconnect", (data) => {
  console.log("reconnect", data);
});

ws.on("reconnected", (data) => {
  console.log("reconnected", data);
});

ws.on("exception", (data) => {
  console.error("exception", data);
});

const myUserID = process.env.GATE_USER_ID;

ws.subscribe(
  [
{ topic: "futures.balances", payload: [myUserID] },
{ topic: "futures.usertrades", payload: [myUserID, "!all"] },
{ topic: "futures.positions", payload: [myUserID, "!all"] },
{ topic: "futures.orders", payload: [myUserID, "!all"] },
  ],
  "perpFuturesUSDTV4",
);

Use those pushes to update a local ledger. That is how you avoid allocating the same margin twice. For a fuller state-machine writeup, see Managing Order and Account State. The gateio-api documentation has more subscribe examples, and you can get started with the Gate.io SDK from there.

The SDK already sends pings, waits for pongs, reconnects, and resubscribes. Defaults are pingInterval: 10000, pongTimeout: 1500, and reconnectTimeout: 500 (milliseconds). You can tighten them:

const { WebsocketClient } = require("gateio-api");

const ws = new WebsocketClient({
  apiKey: process.env.GATE_API_KEY,
  apiSecret: process.env.GATE_API_SECRET,
  pingInterval: 10000,
  pongTimeout: 1500,
  reconnectTimeout: 500,
});

Reconnect delay is a fixed timeout, not exponential backoff. If you run many processes and Gate blips, a stampede of reconnects is possible. Backoff belongs in your process supervisor, not as a hidden SDK setting.

Listen for reconnect and reconnected. After reconnected, private topics are resubscribed by the client. Your in-memory order state is not. Rebuild it from REST (getFuturesOrders, getFuturesPositions) before you resume sending.

Pause on repeated account-level errors instead of retrying forever. Test that path on testnet first. For the surrounding Node.js layout, see Algorithmic Trading System Architecture.

Log request, response, and WebSocket events with timestamps you can join later. When an order fails you want to know if it was your timeout, Gate rejecting the payload, or your own size math. The SDK moves bytes and signatures. Recovery is still yours.

WebsocketClient reconnects on its own. Tune pingInterval, pongTimeout, and reconnectTimeout. Watch reconnect and reconnected. After a drop, refresh positions and open orders over REST. The SDK does not implement exponential backoff. Add that around process startup if you have many workers.

Yes. For WebSockets, set useTestnet: true.

USDT-settled contracts (settle: 'usdt') margin in USDT. BTC-settled contracts (settle: 'btc') margin in BTC. USD-settled quanto contracts use settle: 'usd'. REST uses the same host and puts settle in the path: /futures/{settle}/.... WebSockets use different URLs. In the SDK that is perpFuturesUSDTV4 vs perpFuturesBTCV4. Pass that wsKey on subscribe and on WebsocketAPIClient futures calls.

RestClient signs private REST calls with HMAC-SHA512. The signed payload is method, path, query string, hashed body, and timestamp. WebSocket private channels and the WebSocket API are signed the same way inside WebsocketClient. There is no nonce. You do not need to hash anything yourself unless you pass customSignMessageFn.

The package can be webpack-bundled, and public market data is fine in a browser. Do not put an API secret in frontend code. Anyone who opens DevTools has your key. Run authenticated trading on a Node.js server, with env vars and a key that cannot withdraw.

No. You need your own limiter. Perpetual private trading is 100 requests per second for place and amend, 200 per second for cancel. If you send more than 86,400 place/amend/cancel requests in 24 hours with a fill ratio under 1%, Gate will clamp you. The SDK will not slow itself down to save you.

Create one RestClient and one WebsocketClient (or WebsocketAPIClient) per key. Each instance has its own auth and its own sockets. That is the intended pattern for sub-accounts and for splitting strategies.

The package ships TypeScript types and an llms.txt file that lists functions and parameters. That is enough for most coding agents to call the right methods. It does not make generated trading logic safe. You still review what the agent writes.

Disclaimer

*Technical and legal disclaimer: Siebly.io provides software development tools, SDKs, documentation, and educational engineering content for crypto exchange API integrations. This content is for software engineering education only and is not financial, investment, legal, tax, accounting, compliance, or trading advice.

Nothing in this article is a recommendation, invitation, or inducement to buy, sell, hold, trade, long, short, or allocate to any cryptoasset, exchange product, strategy, bot, or automated workflow. Examples, code patterns, simulations, backtests, and architecture diagrams are illustrative only and must not be treated as trading signals, investment recommendations, or evidence of future performance.

Cryptoasset markets are high risk and volatile. If you choose to build or operate exchange-connected software, you are responsible for your own legal, regulatory, tax, security, exchange-account, API-key, and risk-management obligations. Use public data, testnet, demo, dry-run, or paper-trading workflows before any live execution. Keep API keys server-side, use least-privilege permissions, and never enable withdrawals for automation keys unless you fully understand and accept the risks.

Siebly.io is not an exchange, custodian, investment adviser, trading-signal provider, or managed trading service. Official exchange documentation remains the source of truth for exchange-specific rules, API behavior, and terms of use. Use of Siebly.io content and software is also subject to the Siebly.io terms and conditions.*