Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developer.alterscope.org/llms.txt

Use this file to discover all available pages before exploring further.

This walks a Node 20+ developer through the things you actually need on day one: install, init, one REST call with the agentic envelope, a real-time stream, a webhook receiver, and how the SDK behaves on errors. Expect about five minutes end-to-end.
The TypeScript SDK is @alterscope/sdk@2.0.0-beta.2 — currently in beta, GA targeted for late Q2 2026. Surface area shown here is stable.

​
1. Install

yarn add @alterscope/sdk@2.0.0-beta.2
Node 18+ is required. ESM and CJS bundles are both shipped.

​
2. Initialize the client

import { AlterscopeClient } from "@alterscope/sdk";

const client = new AlterscopeClient({
  apiKey: process.env.ALTERSCOPE_API_KEY!,
  // baseUrl defaults to https://dev.alterscope.org/api.
  // Override for prod: ALTERSCOPE_BASE_URL=https://api.alterscope.org
  baseUrl: process.env.ALTERSCOPE_BASE_URL,
});
Get a key from the Developer Portal → API Keys. Keys start with sk_live_…. The constructor throws if apiKey is missing.

​
3. Your first call

The cheapest “is it working?” call is an oracle classification — it always returns a shape that includes the agentic envelope (freshness, confidence, quality verdict) so you can confirm the SDK is wired correctly in one call. 
import {
  AlterscopeClient,
  freshnessStatusOf,
  extractAgenticMeta,
} from "@alterscope/sdk";

const client = new AlterscopeClient({
  apiKey: process.env.ALTERSCOPE_API_KEY!,
});

const marketId =
  "0x3a85e619b69e7a0c4dd158d61eb41e95b6f25cf3aa3c0f1e5f6e7d8c9b0a1d2f";

const oracle = await client.oracles.classify({ marketId });

// The agentic envelope lives at response.meta._agentic.
const meta = extractAgenticMeta(oracle);
console.log("freshness:", freshnessStatusOf(oracle));
console.log("confidence:", meta?.confidence);
console.log("quality:", meta?.quality_gate?.verdict);
Expected first-call output (real shape — values vary per market and run): 
freshness: fresh
confidence: 0.94
quality: pass
freshnessStatusOf() returns one of "realtime" | "fresh" | "stale" | "unknown". Treat stale as a soft-error in your agent loop — re-fetch before acting on the data.

​
4. Stream events

Risk events are pushed over a WebSocket. The SDK does not yet ship a typed client.riskEvents wrapper — connect with ws directly and send the channel-subscribe message. 
import WebSocket from "ws"; // npm install ws

const ws = new WebSocket(
  `wss://dev.alterscope.org/ws?token=${process.env.ALTERSCOPE_API_KEY}`,
);

ws.on("open", () => {
  ws.send(
    JSON.stringify({
      type: "subscribe",
      channel: "events",
      event_types: ["oracle_failure", "exploit"],
    }),
  );
});

ws.on("message", (raw) => {
  const msg = JSON.parse(raw.toString());
  if (msg.type === "market_event" && msg.event_type === "oracle_failure") {
    console.warn(`oracle failure on ${msg.protocol}: ${msg.title}`);
  }
});
Event types you can subscribe to: factor_update (channel factors), alert_triggered (alerts), position_update (positions), apy_update (apy), market_event (events — subtypes include oracle_failure, exploit, upgrade, governance, liquidity_crunch). Full protocol reference: WebSockets API.
A typed client.riskEvents.subscribe(...) wrapper is on the SDK roadmap — track via the changelog.

​
5. Receive a webhook

Create the webhook subscription via the SDK, then mount a handler that parses the body: 
// One-time: register the endpoint.
await client.webhooks.create({
  url: "https://your.app/alterscope-webhook",
  events: ["alert.triggered", "health_factor.low"],
});

// Receiver (Express).
import express from "express";
const app = express();

app.post(
  "/alterscope-webhook",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const event = JSON.parse(req.body.toString("utf8"));
    console.log(event.type, event.data);
    res.sendStatus(204);
  },
);
Signature verification ships with the GA SDK release (Q2 2026). Until then, restrict the webhook URL to source IPs you control and rotate the secret if it leaks. Track via the changelog.

​
Errors and retries

The SDK retries 429 and 5xx responses up to maxRetries times with exponential backoff (capped at 60s) and honors Retry-After on 429. Defaults: maxRetries = 3, timeout = 30_000 ms. 
import {
  AlterscopeClient,
  AuthenticationError,
  RateLimitError,
  NotFoundError,
} from "@alterscope/sdk";

const client = new AlterscopeClient({
  apiKey: process.env.ALTERSCOPE_API_KEY!,
  maxRetries: 5,
  timeout: 60_000,
});

try {
  await client.oracles.classify({ marketId: "0x…" });
} catch (err) {
  if (err instanceof AuthenticationError) throw err; // don't retry bad keys
  if (err instanceof NotFoundError) return null; // unknown market is not fatal
  if (err instanceof RateLimitError) console.warn("backed off:", err.message);
  throw err;
}
Other typed errors: ForbiddenError, ValidationError, ServerError, plus the base AlterscopeError.

​
Reference

​
Next steps

Pricing & quotas

Free, Pro, Pro+, and Enterprise tiers — what each gets you.

Changelog

What changed in the API and SDKs, week by week.

API Reference

Every operation with try-it-out.

Recipes

End-to-end flows: depeg detection, scoring, treasury automation.