JavaScript Client Guide

Use the built-in fetch API available in modern browsers and Node.js 18+ to call the Shorted API. No additional dependencies required.

Prerequisites

Node.js 18+ (for server-side) or any modern browser
No additional packages needed

Authentication

Include your API key in the Authorization header as a Bearer token. Public endpoints work without authentication but have lower rate limits.

const response = await fetch(
  "https://shorts-uiekqxovma-km.a.run.app/shorts.v1alpha1.ShortedStocksService/GetTopShorts",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer YOUR_API_KEY",
    },
    body: JSON.stringify({ limit: 10 }),
  }
);

const data = await response.json();

Example: Get Top Shorted Stocks

Retrieve the most heavily shorted stocks on the ASX, sorted by short interest percentage.

const response = await fetch(
  "https://shorts-uiekqxovma-km.a.run.app/shorts.v1alpha1.ShortedStocksService/GetTopShorts",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ limit: 10, offset: 0 }),
  }
);

const { stocks, totalCount } = await response.json();
console.log(`Top ${stocks.length} of ${totalCount} shorted stocks:`);
stocks.forEach((stock) => {
  console.log(`${stock.productCode}: ${stock.currentPercent}%`);
});

Example: Get Stock Details

Fetch detailed information about a specific stock by its ASX code.

const response = await fetch(
  "https://shorts-uiekqxovma-km.a.run.app/shorts.v1alpha1.ShortedStocksService/GetStock",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ productCode: "BHP" }),
  }
);

const { stock } = await response.json();
console.log(stock.companyName, stock.currentPercent + "%");

Error Handling

The API returns standard HTTP status codes. Rate limited requests return 429 with a Retry-After header. Always check the response status before parsing the body.

async function apiCall(path, body) {
  const response = await fetch(`https://shorts-uiekqxovma-km.a.run.app${path}`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer YOUR_API_KEY",
    },
    body: JSON.stringify(body),
  });

  if (response.status === 429) {
    const retryAfter = response.headers.get("Retry-After");
    throw new Error(`Rate limited. Retry after ${retryAfter}s`);
  }

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`API error ${response.status}: ${error.message}`);
  }

  return response.json();
}

All Endpoints

See the full API reference for all available endpoints, request/response schemas, and the interactive "Try It" panel.