asterdex-api

Published on npm as asterdex-api.

A batteries-included Node.js client for the Aster trading platform. It implements the REST signing flow described in the official documentation and offers lightweight WebSocket helpers for market data streams.

Disclaimer: This package is not affiliated with Aster. Review the official API documentation before using it in production.

Features

• Secure HMAC-SHA256 request signing using your API secret.
• Configurable REST client with helpers for spot and margin/futures orders.
• Minimal WebSocket client for streaming market data such as ticker updates.
• ?? Example scripts that show end-to-end order flows.

Installation

npm install asterdex-api

TypeScript definitions ship with the package. The REST client relies on the built-in fetch API available in Node.js 18+. If you run on an older runtime, provide a compatible implementation through the fetcher option.

Getting started

import { AsterRestClient } from 'asterdex-api';

const client = new AsterRestClient({
  apiKey: process.env.ASTER_API_KEY!,
  apiSecret: process.env.ASTER_API_SECRET!,
  defaultRecvWindow: 50_000, // optional
});

async function main() {
  const order = await client.placeMarginOrder({
    symbol: 'BTCUSDT',
    side: 'BUY',
    type: 'MARKET',
    positionSide: 'LONG',
    quantity: '0.01',
  });

  console.log(order);
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Authentication

1. Create an API key on the Aster website.
2. Copy the credentials exactly as labelled in the dashboard:
   • API Key → store in the ASTER_API_KEY environment variable.
   • API Secret Key → store in ASTER_API_SECRET (keep this value private). Only the API key and secret are required for REST calls—the client handles all HMAC-SHA256 signing internally.

Spot trading helper

await client.placeSpotOrder({
  symbol: 'ETHUSDT',
  side: 'BUY',
  type: 'MARKET',
  quoteOrderQty: '100',
  newOrderRespType: 'FULL',
});

Command-line helpers provide the same parameters. For example:

node examples/spot-buy.js --symbol=ETHUSDT --type=limit --quantity=0.5 --price=1800 --time-in-force=GTC
node examples/spot-sell.js --symbol=ETHUSDT --type=market --quantity=0.25 --resp-type=FULL

You can override the default spot base URL (https://sapi.asterdex.com) or version (v1) by passing spotBaseUrl / spotVersion to the constructor.

Margin & futures helper

await client.placeMarginOrder({
  symbol: 'BTCUSDT',
  side: 'SELL',
  type: 'LIMIT',
  positionSide: 'SHORT',
  quantity: '0.01',
  price: '64000',
  timeInForce: 'GTC',
});

Pass custom fields such as stopPrice, reduceOnly, workingType, or newOrderRespType through the same object.

The perpetual helpers wrap this flow. Example commands:

node examples/perp-buy.js --symbol=BTCUSDT --quantity=0.01 --type=market --take-profit=75000 --stop-loss=68000
node examples/perp-sell.js --symbol=BTCUSDT --quantity=0.01 --type=limit --price=73000 --time-in-force=GTC --stop-loss=76000 --take-profit=69000
node examples/perp-update-tp-sl.js --symbol=BTCUSDT --take-profit=75000 --stop-loss=68000

Hedge-mode accounts can append --position-side=LONG|SHORT (and --side=BUY|SELL for the TP/SL helper). One-way accounts should omit these flags.

Custom REST calls

Access any other endpoint through signedRequest (for authenticated endpoints) or publicRequest (for public market data).

await client.signedRequest('GET', 'account', {}, { apiPrefix: 'fapi' });
await client.publicRequest('GET', 'premiumIndex', { symbol: 'BTCUSDT' });

Market data streaming

import { AsterWebsocketClient } from 'asterdex-api';

const ws = new AsterWebsocketClient();

ws.connect('btcusdt@ticker', {
  onOpen: () => console.log('Connected'),
  onMessage: (payload) => console.log('Latest ticker update:', payload),
  onError: (error) => console.error('Stream error', error),
});

The WebSocket helper uses the futures stream base URL (wss://fstream.asterdex.com) by default. Override it by passing { streamBaseUrl: 'wss://...' } to the constructor.

Examples

The examples/ directory contains runnable scripts that showcase common workflows. Copy .env.example (or create environment variables manually) with your credentials before running them.

Every example that touches the trading API accepts a simulated mode so you can rehearse the logic without sending live orders. Pass --mode=test (or simply --test) on the command line to enable this behaviour:

node examples/spot-buy.js --mode=test

Example catalog:

• websocket-latest-price.js: subscribe to a ticker stream and log the latest price.
• historical-candles.js: request historical OHLCV candles from the public API (for example, --symbol=BTCUSDT --interval=1h --hours=24 fetches one day of 1h bins).
• spot-account-balance.js: list spot balances (optionally filtered by --asset).
• spot-buy.js: place spot buy orders (--type=market|limit plus optional stop params, response types, etc.).
• spot-sell.js: place spot sell orders with the same extended flag support as the buy script.
• spot-trade-history.js: fetch executed spot trades for a symbol (--limit, --from-id, --start-time, --end-time supported).
• perp-account-info.js: dump futures balances and asset-level account information.
• perp-open-positions.js: show open perpetual positions (or include empty ones with --show-empty).
• perp-open-orders.js: list active perpetual orders, optionally filtered by symbol.
• perp-order-history.js: pull historical perpetual orders with --limit, --start-time, or --end-time.
• perp-buy.js: open a perpetual long with market/limit support and optional take-profit / stop-loss orders.
• perp-sell.js: open a perpetual short with optional TP/SL protection.
• perp-update-tp-sl.js: cancel and recreate take-profit / stop-loss orders for an existing perpetual position.
• margin-long-update-stop.js: open a long futures position, create a protective stop, then update that stop after a delay.
• margin-short-update-stop.js: open a short futures position, create a protective stop, then update that stop after a delay.

Each script is self-contained and can be executed with node once you compile the package or install it from npm.

Building from source

npm install
npm run build

The compiled files will be emitted to dist/.

License

MIT