TypeScript Client

A typed TypeScript client lives in the app repo at web/src/lib/api-client. It’s drift-tested against the checked-in OpenAPI spec: when the spec moves, the client moves with it or the test suite fails. It’s not on npm yet. Use it as source or as a reference implementation.

Want a package release? That needs decisions on package name, semver policy, changelog ownership, and npm access. Open an issue if you depend on it.

What it handles

Authorization: Bearer header injection.
Path parameter interpolation (/trader/{address}, /market/{condition_id}/intel).
Repeated query parameters like expand=strategy&expand=categories. The API also accepts the legacy expand[] form.
JSON request bodies for batch and webhook endpoints.
V1 error envelopes as typed exceptions with the HTTP status, parsed error, and raw response body.
Conditional reads: successful response ETag headers are copied to meta.etag, and 304 responses return a typed not_modified envelope instead of attempting to parse an empty body.

Example

import { OxinsiderApiClient } from "./api-client";

const client = new OxinsiderApiClient({
  baseUrl: "https://api.0xinsider.com",
  apiKey: process.env.OXINSIDER_API_KEY,
});

// Wallet address or username — both work.
const trader = await client.getTrader("swisstony", {
  query: { expand: ["strategy", "categories"] },
});

const markets = await client.searchMarkets("NBA", {
  query: { limit: 5, status: "active" },
});

Conditional reads

import {
  OxinsiderApiClient,
  isApiNotModifiedResponse,
} from "./api-client";

const client = new OxinsiderApiClient({
  baseUrl: "https://api.0xinsider.com",
  apiKey: process.env.OXINSIDER_API_KEY,
});

const first = await client.call("listSportsEdgeObservations", {
  query: { cohort: "wider_holder", category: "Tennis", limit: 20 },
});

if (!isApiNotModifiedResponse(first) && first.meta?.etag) {
  const next = await client.call("listSportsEdgeObservations", {
    query: { cohort: "wider_holder", category: "Tennis", limit: 20 },
    headers: { "If-None-Match": first.meta.etag },
  });

  if (isApiNotModifiedResponse(next)) {
    console.log("snapshot unchanged");
  }
}

The 304 envelope has object: "not_modified", data: null, and metadata copied from response headers. The packaged SDK also exposes a route-specific conditional Sports Edge method; see its README for that API.

Handling errors

The client throws typed exceptions instead of a generic error object. Match on the parsed error field:

import { OxinsiderApiClient, OxinsiderApiError } from "./api-client";

const client = new OxinsiderApiClient({
  baseUrl: "https://api.0xinsider.com",
  apiKey: process.env.OXINSIDER_API_KEY,
});

try {
  const trader = await client.getTrader("not-a-real-trader");
} catch (err) {
  if (err instanceof OxinsiderApiError) {
    const code = err.error?.code;
    if (code === "not_found") {
      // expected: unknown trader
    } else if (code === "subscription_required") {
      throw new Error("Pro subscription required");
    } else {
      throw err;
    }
  } else {
    throw err;
  }
}

Keep OpenAPI as the source of truth

The client operation table regenerates from api-reference/openapi.json. Change the spec and the client follows. Don’t hand-edit the client to add operations without updating the spec.

Getting Started

Guides

Concepts

What it handles

Example

Conditional reads

Handling errors

Keep OpenAPI as the source of truth

​What it handles

​Example

​Conditional reads

​Handling errors

​Keep OpenAPI as the source of truth

What it handles

Example

Conditional reads

Handling errors

Keep OpenAPI as the source of truth