TypeScript client

@0xinsider/sdk is the TypeScript client for the 0xinsider API. It gives you a typed call for every public operation, an error class per API error, cursor pagination, the resumable SSE stream, and webhook signature checks. Use it when a Node service needs those instead of hand-written fetch calls. The client takes the same Pro key as the CLI and the MCP server. Its source is public at 0xinsider/0xinsider-node, which is also where npm will publish it from.

The first npm release is pending: npm install @0xinsider/sdk answers 404 until it lands. Build it from source for now, or use the Python or Go client, which are published.

Build from source

The client needs Node.js 18 or later, because it uses the built-in fetch, ReadableStream, and node:crypto. It has no runtime dependencies of its own, and it is ESM only.

git clone https://github.com/0xinsider/0xinsider-node
cd 0xinsider-node && npm ci && npm run build

Then install the build from your project with npm install ../0xinsider-node. Once the package is on npm, npm install @0xinsider/sdk replaces both steps.

What the client handles

Concern	Behavior
Auth	It sends `Authorization: Bearer` on every operation that needs a key. Without a key it throws before the request, except in sandbox mode, where no operation needs one.
Base URL	The default is `https://api.0xinsider.com`. `OxinsiderApiClient.sandbox()` uses `https://0xinsider.com/sandbox` instead. A path you put on `baseUrl` is kept, and `http:` is accepted only for a loopback host.
Timeout	Each call gets 15 seconds, which `timeoutMs` changes and `null` turns off. A call that runs out of time rejects with `RequestTimeoutError`.
Retries	`maxRetries` defaults to 2. The client retries on `408`, `429`, `502`, `503`, `504`, and network errors. It honors a `Retry-After` header, in seconds or as an HTTP-date, up to 60 seconds.
What it retries	Any `GET`, the two read-only batch posts (`batchGetTraders` and `batchGetMarketIntel`), and the 8 keyed writes listed below when you pass an `idempotencyKey`.
`304`	It copies a response `ETag` to `meta.etag`. On a `304` it returns `{ object: "not_modified", data: null, meta }` instead of throwing.
Types	Each method is typed from its own operation in the OpenAPI document: the path parameters it takes, the query keys it documents, the body it requires, and the envelope it answers with. No method takes a type argument.
Drift	The operation table and the generated types are checked against the OpenAPI document on the merge path. A spec change fails there instead of shipping stale types.

Start in the sandbox, without a key

OxinsiderApiClient.sandbox() calls https://0xinsider.com/sandbox/api/v1. Every documented operation answers with example data, nothing is stored, and no credential is needed. Every response carries meta.sandbox: true. Add sandbox_status to a query to get one of the operation’s documented errors, thrown as the class production would throw. A live key is refused in sandbox mode, and a sandbox key from POST /api/v1/agents/register is optional. Streams and file downloads answer 400 there.

import { OxinsiderApiClient, RateLimitedError, type Trader } from "@0xinsider/sdk";

const sandbox = OxinsiderApiClient.sandbox();
const board = await sandbox.listLeaderboard({ limit: 5 });
console.log(board.data, board.meta.sandbox); // LeaderboardEntry[], true

// sandbox_status is not part of the route's documented query, so this call
// takes the loose form: an explicit type argument in place of the typed one.
try {
  await sandbox.call<Trader>("getTrader", {
    path: { address: "swisstony" },
    query: { sandbox_status: 429 },
  });
} catch (err) {
  if (err instanceof RateLimitedError) console.log(err.retryAfterSeconds);
}

Read a trader and search markets

import { OxinsiderApiClient } from "@0xinsider/sdk";

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

// A wallet address, a username, or a trd_ ID
const trader = await client.getTrader("swisstony", {
  query: { expand: ["strategy", "categories"] },
});
console.log(trader.data);

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

// Any operation by id, typed by the id: path, query, body and the envelope
const usage = await client.call("getUsage");
const holders = await client.call("getMarketHolders", {
  path: { condition_id: "0x..." },
  query: { outcome: "yes", limit: 25 },
});

Keep financial values exact

The trader and positions responses keep their display-safe numeric fields for charts and labels, and add exact decimal atoms when the source value is verified. Install a decimal library for arithmetic; do not pass an exact value through Number first.

npm install decimal.js

import Decimal from "decimal.js";

const profile = await client.getTrader("swisstony");
const realizedAtom = profile.data.pnl.exact?.realized;
if (realizedAtom) {
  const realizedUsd = new Decimal(realizedAtom.value);
  console.log(realizedUsd.plus("0.01").toFixed());
}

const positions = await client.listPositions({ wallet: "swisstony", min_size: 0 });
const currentAtom = positions.data[0]?.exact?.current_value_usd;
const currentUsd = currentAtom ? new Decimal(currentAtom.value) : null;

unit, scale, and basis travel with each atom. The exact block or member can be absent when the source is unavailable; an absent value is not zero.

Typed by the operation

Since 0.3.0 every method knows its own shape, so you do not declare it. trader.data is the route’s Trader, explore.data[0] is an ExploreEntry, explore.facets is typed, and radar.data[0] is a RadarFlag. A batch’s meta is the BatchResponseMeta that carries request_cost and rate_limit. That typing also catches mistakes at compile time. A query key the route does not document is an error: listInsiderRadar({ min_grade: "S" }) fails, because that route takes min_suspicion and severity. A missing path parameter is an error too. The next release adds the canonical spelling of these names: listSuspiciousTrades(), getSuspiciousTrade(), and the types SuspiciousTrade, SuspiciousTradesListParams, SuspiciousTradeFlaggedData and SuspiciousTradeFlaggedEvent. listInsiderRadar(), getInsiderRadarFlag(), InsiderRadarListParams, InsiderRadarFlagRaisedData, InsiderRadarFlagRaisedEvent and RadarFlag all stay as deprecated aliases, so no import breaks. InsiderRadarFlagRaisedEvent keeps its own "insider_radar_flag_raised" discriminant. No method takes a type argument any more. A client.getTrader<MyShape>(...) written against 0.2.x drops the argument. Every method forwards the same transport options after its own parameters: signal, timeoutMs, maxRetries, headers (for an If-None-Match on a conditional read) and, on the keyed writes, idempotencyKey.

const trades = await client.listWhaleTrades(
  { min_grade: "S", limit: 25 },
  { signal, timeoutMs: 5_000, maxRetries: 0 },
);
trades.data[0].trader.address; // WhaleTrade
trades.meta.request_id; // ResponseMeta, always present

call, list, paginate, paginatePages, and collect are typed the same way when you pass the operation id as a literal string. They fall back to a loose form when you pass an id chosen at runtime, or an explicit type argument. The loose form takes plain path, query, and body records, and returns the generic { object, data, meta? } envelope for a caller that asserts the shape itself.

Look up 1 to 25 traders in one request

batchGetTraders() posts { traders, expand } to POST /api/v1/traders/batch. data keeps your request order and returns one row per input, duplicates included. Each row is either status: "ok" with its data or status: "error" with that item’s own error, so one unknown wallet does not fail the request. meta.request_cost counts batch item units, not requests.

const batch = await client.batchGetTraders(["swisstony", "trd_123"], {
  expand: ["strategy", "trust"], // strategy, categories, quant_metrics, trust
});
for (const item of batch.data) {
  if (item.status === "ok") console.log(item.input, item.data?.grade);
  else console.log(item.input, item.error?.code);
}

Paginate a list

paginate() follows next_cursor and yields each item. paginatePages() yields whole envelopes, for when you need meta or total.

import { paginate, paginationResumePoint } from "@0xinsider/sdk";

try {
  for await (const trade of paginate(client, "listWhaleTrades", {
    query: { min_grade: "S", limit: 100 },
  })) {
    console.log(trade);
  }
} catch (err) {
  const resume = paginationResumePoint(err); // { cursor, pagesFetched } or undefined
  if (!resume) throw err;
}

The loop stops when has_more is false. A page that says has_more: true with no next_cursor, or that repeats a cursor already requested, throws PaginationError before it is yielded. Its reason is missing_cursor or repeated_cursor, and the page itself is attached to the error. Three options control the loop. maxPages caps how many pages it fetches and must be a positive integer, and signal cancels it. A progress object records whether the loop stopped at maxPages or at the end of the collection, and which cursor continues from there. A page that still fails after its own retries throws that page’s error. paginationResumePoint() then gives you the cursor to continue from.

Read conditionally

import { isApiNotModifiedResponse } from "@0xinsider/sdk";

const first = await client.call("getTrader", { path: { address: "swisstony" } });

if (!isApiNotModifiedResponse(first) && first.meta.etag) {
  const next = await client.call("getTrader", {
    path: { address: "swisstony" },
    headers: { "If-None-Match": first.meta.etag },
  });
  if (isApiNotModifiedResponse(next)) console.log("unchanged");
}

Handle errors

Every response outside 2xx throws a subclass of OxinsiderApiError. The client picks the subclass by the response’s error.reason first, then by its error.code.

`error.code` or `error.reason`	Class
`bad_request`	`BadRequestError`
`unknown_query_parameter`	`UnknownQueryParameterError`, itself a `BadRequestError`
`invalid_api_key`	`InvalidApiKeyError`
`sandbox_api_key`	`SandboxApiKeyError`
`api_key_in_query`	`ApiKeyInQueryError`
`subscription_required`	`SubscriptionRequiredError`
`forbidden`	`ForbiddenError`
`not_found`	`NotFoundError`
`account_locked`	`AccountLockedError`
`request_timeout`	`ServerTimeoutError`
`rate_limited`	`RateLimitedError`
`rate_limit_unavailable`	`RateLimitUnavailableError`
`internal_error`	`InternalServerError`
`invalid_response` (raised by the client, not the API)	`InvalidResponseError`
`pick_not_released`	`PickNotReleasedError`
`read_model_warming`	`ReadModelWarmingError`
`database_unavailable`	`DatabaseUnavailableError`
`request_accounting_unavailable`	`RequestAccountingUnavailableError`
`cursor_expired`	`CursorExpiredError`
`trader_not_tracked`	`TraderNotTrackedError`
`unknown_endpoint`	`UnknownEndpointError`
`idempotency_in_progress`	`IdempotencyInProgressError`
`webhook_delivery_in_progress`	`WebhookDeliveryInProgressError`

Every error exposes status, code, reason, retryAt, error, meta, requestId, and the raw body. RateLimitedError, RateLimitUnavailableError, ServerTimeoutError, and PickNotReleasedError add retryAfterSeconds. The client’s own retries run first, so what you catch is the final failure. Read the reason the API sent from err.error.reason, not from err.reason. The reason property is set only on the classes named for a reason in the table above, so a 429 whose body says monthly_quota_exceeded arrives as a RateLimitedError with err.reason still null.

import { OxinsiderApiError, RateLimitedError } from "@0xinsider/sdk";

try {
  await client.listWhaleTrades({ min_grade: "S" });
} catch (err) {
  if (err instanceof RateLimitedError) {
    await new Promise((r) => setTimeout(r, (err.retryAfterSeconds ?? 1) * 1000));
  } else if (err instanceof OxinsiderApiError && err.retryAt) {
    console.log("retry at", err.retryAt.toISOString()); // schedule; never sleep on it
  } else if (err instanceof OxinsiderApiError) {
    console.error(err.status, err.code, err.requestId);
  } else {
    throw err;
  }
}

Write with an idempotency key

Eight operations accept an idempotencyKey: createWebhook, updateWebhook, deleteWebhook, rotateWebhookSecret, prepareWebhookSecret, activateWebhookSecret, retireWebhookSecret, and redeliverWebhookDelivery. The key makes the write safe to replay and eligible for retry, and every retry sends the same key and the same bytes. Only createWebhook, updateWebhook, deleteWebhook, and redeliverWebhookDelivery have a convenience method. Reach the four secret-rotation operations through client.call("rotateWebhookSecret", ...) and its siblings. See Webhooks for what staged rotation does. Reuse a key only with the same body. A key on any other operation throws before the request, because the API does not read it there. After a timeout or exhausted retries the outcome is unknown, so send the same key and body once more, or read the resource; a key gives you safe replay, not exactly-once delivery.

await client.call("createWebhook", {
  body: {
    name: "Large trades",
    url: "https://example.com/hooks/0xinsider",
    event_types: ["whale_trades_inserted"],
  },
  idempotencyKey: crypto.randomUUID(),
});

Stream events and check webhook signatures

streamFeed(client, options) reads one connection of Stream, with Last-Event-ID resume and the event, condition_id, and min_grade filters.
streamFeedResilient() reconnects for you. It gives up after maxReconnects consecutive connections that delivered nothing, which defaults to 10; any delivered frame resets the count.
A Retry-After longer than maxRetryAfterMs (60 seconds by default) throws StreamRetryDeferredError with retryAt and lastSeq for you to schedule. The client never reconnects early.
A malformed frame, a 2xx that is not SSE, or a frame past maxFrameBytes (1 MiB) throws StreamProtocolError with reason, lastSeq, and frameId. The cursor never moves past a bad frame, and the reconnect loop does not retry it.
consumeStreamCheckpointed(client, handlers, options) is the consumer for work you cannot afford to drop. It keeps two positions: options.cursor is the last frame that arrived, and options.checkpoint is the last frame you finished handling. The checkpoint advances only after your onEvent and your onCheckpoint write both resolve.
If either handler rejects, the checkpoint stays before that event, the connection closes, and the client reconnects from the checkpoint, so the event is replayed rather than skipped. onResync is awaited too, so an interrupted refresh commits nothing.
After maxHandlerRetries consecutive failures on one seq (3 by default), it throws StreamHandlerFailedError with seq, stage, attempts, checkpoint, and replayFrom. Delivery is at least once, so deduplicate on seq or make the side effect idempotent.
verifySignature(input) checks x-0xinsider-signature against the raw body, with the 300-second tolerance and a constant-time compare. It splits the header on commas and accepts any candidate, so a staged secret rotation verifies. It returns false for a bad signature or timestamp, and throws for an empty secret or a NaN, infinite, or negative toleranceSeconds.
parseWebhookEvent(body) returns a typed event. See Webhooks.

What it does not do

Place an order or hold a wallet key. It reads data and manages the webhooks on your own account.
Retry a 400, 401, 402, 403, 404, 409, 500, a write with no idempotency key, a write outside the 8 keyed operations, its own timeout, or your own abort.
Wait out a Retry-After over 60 seconds, on a request or on the stream. It throws instead, for you to schedule from retryAfterSeconds, retryAt, or StreamRetryDeferredError.retryAt.
Sleep until retryAt. On pick_not_released that can be 13 to 14 hours out.
Apply timeoutMs to the stream. A stream connection has no deadline.

Getting started

Integrations

Guides

Concepts

Build from source

What the client handles

Start in the sandbox, without a key

Read a trader and search markets

Keep financial values exact

Typed by the operation

Look up 1 to 25 traders in one request

Paginate a list

Read conditionally

Handle errors

Write with an idempotency key

Stream events and check webhook signatures

What it does not do

​Build from source

​What the client handles

​Start in the sandbox, without a key

​Read a trader and search markets

​Keep financial values exact

​Typed by the operation

​Look up 1 to 25 traders in one request

​Paginate a list

​Read conditionally

​Handle errors

​Write with an idempotency key

​Stream events and check webhook signatures

​What it does not do

Build from source

What the client handles

Start in the sandbox, without a key

Read a trader and search markets

Keep financial values exact

Typed by the operation

Look up 1 to 25 traders in one request

Paginate a list

Read conditionally

Handle errors

Write with an idempotency key

Stream events and check webhook signatures

What it does not do