algierex (TypeScript)

TypeScript SDK for the Algierex market data API: the Algerian exchange's daily prices back to 1999, sessions, the Dzair index, the OAT yield curve, exchange rates, company events and news.

No dependencies. Uses fetch, so it runs on Node 18 or newer, Deno, Bun, and edge runtimes. Full types for every response.

Install

npm install algierex

Get a key

Create a key and choose a plan at developers.algierex.com/dashboard. Then set ALGIEREX_API_KEY, or pass apiKey.

Example

import { Algierex, PaymentRequiredError } from "algierex";

const client = new Algierex(); // reads ALGIEREX_API_KEY

try {
  await client.listTickers();
} catch (err) {
  // No active plan: choose one at developers.algierex.com/dashboard.
  if (err instanceof PaymentRequiredError) throw new Error(err.message);
  throw err;
}

// Every daily close of Saidal since 2025.
const prices = await client.getPrices("SAI", { from: "2025-01-01" });
console.log(prices.at(-1)?.close);

// The OAT yield curve on a past date.
const curve = await client.getYieldCurve({ date: "2026-09-30" });
console.log(curve.asOf, curve.fit?.rSquared ?? "not enough trades");

// Upcoming company events, in French.
for (const event of await client.getCalendar({ from: "2026-11-01", locale: "fr" })) {
  console.log(event.date, event.ticker, event.label);
}

Methods

| Method | Route | |---|---| | listTickers() | GET /tickers | | getPrices(ticker, { from, to }) | GET /prices/{ticker} | | listSessions({ market, from, to }) | GET /sessions | | getDzairIndex({ from, to }) | GET /index/dzair | | getYieldCurve({ date }) | GET /yield-curve | | listFx() | GET /fx | | getFxHistory(code, { source, from, to }) | GET /fx/{code} | | getCalendar({ from, to, ticker, locale }) | GET /calendar | | listNews({ ticker, source, from, to, locale, includeRoutine }) | GET /news | | getOrderBook({ ticker }) | GET /order-book |

Paging

Paging is automatic: list methods resolve to every row. For long histories, the iter* twin is an async iterator that yields rows as pages arrive:

for await (const day of client.iterPrices("SAI")) {
  // ...
}

pageSize (1 to 1000, default 1000) sets rows per request; the default keeps calls against your plan's limits low.

Errors

Every error is an AlgierexError with status and code:

| Class | When | |---|---| | BadRequestError | 400: a parameter is not valid | | AuthenticationError | 401: the key is missing, wrong, or revoked | | PaymentRequiredError | 402: no active plan, or the last payment failed | | PlanRequiredError | 403: the plan does not include this route (news and the order book need Business) | | NotFoundError | 404: no such security, currency, or date | | RateLimitError | 429: the plan's limit is used up; retryAfter in seconds |

On a 429 the client waits Retry-After and retries, up to maxRetries (default 3) and only for waits up to maxRetryWait seconds (default 60). new Algierex({ maxRetries: 0 }) throws at once. Server errors (5xx), timeouts (timeout: 30 seconds) and network failures throw AlgierexError and are not retried.

Webhooks

On the Business and Redistribution plans, add a webhook URL on the dashboard and we POST to it the minute a session or a pre-fixing book is published. Check each call with verifyWebhook. Pass the raw body, before any JSON parsing:

import { verifyWebhook, WebhookSignatureError } from "algierex";

// Express example: express.text({ type: "application/json" }) keeps the raw body
app.post("/hooks/algierex", express.text({ type: "application/json" }), async (req, res) => {
  try {
    const event = await verifyWebhook(req.body, req.get("Algierex-Signature") ?? "", WEBHOOK_SECRET);
    if (event.type === "session.published") {
      // fetch the new prices
    }
    res.sendStatus(200);
  } catch (err) {
    res.sendStatus(err instanceof WebhookSignatureError ? 400 : 500);
  }
});

Calls older than 5 minutes are refused (toleranceSeconds: 300).

Regenerating

This SDK is generated from the API's OpenAPI spec. From the repository root, after npm install: npm run sdk.