SDK

The TypeScript client for Stacks contract monitoring (@secondlayer/sentinel): watches, alerts and signed webhook checks. Node 22 or newer.

npm i @secondlayer/sentinel

Create a client

createClient takes a token. resolveToken finds one the way the CLI does: SENTINEL_API_KEY, a saved key, then the saved login. It returns null when there is none.

import { createClient, resolveToken } from "@secondlayer/sentinel";

const credential = await resolveToken();
if (!credential) throw new Error("Not logged in. Run: sentinel login");
const sentinel = createClient({ token: credential.token });

In CI, pass the key from the environment:

const sentinel = createClient({ token: process.env.SENTINEL_API_KEY! });

baseUrl is optional and defaults to https://api.runsentinel.app.

The grammar's verbs

The client has the CLI's verbs as methods, named from them (destinations add → destinationsAdd): when, every, at, describe, list, show, logs, on, off, read, rename, remove, group, whoami, import, backtest. Each takes a target as the CLI does (a contract's id or its name on your account, or an id) and answers the CLI's shape: a write { done, willDo, effect, next }; a read its data and next. A free write happens at once and dryRun: true previews it; a cost (a check, a contract over your tier's count) or stopping coverage answers done: false until yes: true.

const preview = await sentinel.when("transfer example-vault sBTC --out --over 5", { dryRun: true });
preview.effect;   // the 90-day backtest and the cost
const added = await sentinel.when("transfer example-vault sBTC --out --over 5", { wait: true });
const { entries, nextCursor } = await sentinel.logs("example-vault");

when also takes a TriggerSpec. parseLine, specLine and resolveTarget are exported too. The verbs whose name a method below already has (contracts, alerts, testAlert, destinations, ask, redeliver, retryHistory, update, autoPlan, link, planLinked, connectSlack) keep that method in this release; their verb is verbsOf(sentinel).<name>.

List and read plans

const plans = await sentinel.plans();        // your contracts
const plan = await sentinel.plan(plans[0].planId);

Turn a watch on

The API methods below go straight through: they have no preview step. Read first, then call. The verbs above write at once unless they cost money or stop coverage.

const { watches } = await sentinel.list();
await sentinel.on(watches[0].id);                      // a watch is a w_… id; live once its contract's monitoring is on
await sentinel.on("example-vault");                    // a contract: resumes its monitoring, counts toward your tier once live

Every write answers monitoring, the contract's status: only live (or requested, setting up) means it is watched. Where alerts go is your account's destinations (destinations), not a setting on a contract.

createPlan starts a plan. Plans are free, and nothing is turned on by one. previewPlan writes nothing:

const preview = await sentinel.previewPlan("SP000000000000000000002Q6VF78.example-vault");
const { planId } = await sentinel.createPlan(preview.contractId);

show takes a contract too: it starts the plan and reads back what its code has: its functions, its tokens, the @admin, @value and @control functions and the events it prints. It turns nothing on.

const r = await sentinel.show("SP000000000000000000002Q6VF78.example-vault");
if (r.kind === "contract") r.contract.groups.control;   // the functions that change who controls the contract

A whole Clarinet repo goes the same way: previewImport lists its contracts at a pinned commit, and importRepo plans the ones you pick at exactly that commit and adds them to your account (hold: true keeps their watches off after the deploy):

const repo = await sentinel.previewImport("https://github.com/acme/protocol");
const picked = repo.contracts.filter((c) => c.suggested).map((c) => c.name);
const { plans } = await sentinel.importRepo({
  url: "https://github.com/acme/protocol",
  commit: repo.commit,
  contracts: picked,
});

Errors

A failed call throws SentinelError with the HTTP status and the API's message.

import { SentinelError } from "@secondlayer/sentinel";

try {
  await sentinel.on("w_example");
} catch (e) {
  if (e instanceof SentinelError && e.status === 403) console.error(e.message);
  else throw e;
}

Every method

Each capability has a method, named from its verb, or (this release) the API method its route had. Methods map to the API routes.

The verbs: when, every, at, describe, list, show, logs, on, off, read, rename, remove, group, whoami, upgrade, checkoutStatus, statusWatch, import, backtest, destinationsAdd, destinationsDefault, destinationsRemove. Each previews (done: false) until yes: true and answers next.

A remove takes the name the app asks you to type:

const contracts = await sentinel.contracts();
const vault = contracts.find((c) => c.name === "example-vault")!;
await sentinel.removeContract(vault.planId, vault.name);

Sign-in and choosing a tier stay on the account page (/account); keys need your own login.