SDK & API keys

@ignitra/sdk is the TypeScript client for the API: flows, runs and their traces, connections, templates, and verification of the webhooks IGNITRA sends you. It has no dependencies and runs in Node 20+, Deno, Bun, browsers and edge runtimes.

API keys

• Create one under Settings → API keys (Team plan). It looks like igk_… and is shown once: IGNITRA stores only its hash.
• Send it as Authorization: Bearer igk_…. A key acts as your account, except for what needs your wallet: creating keys, and creating or verifying onchain grants. Revoking a grant works with a key (stopping things should be easy).
• Revoke a key in Settings: anything using it stops at once. Keep keys on servers, never in a browser or a repository.
• On any plan, a wallet session token (igs_…, from POST /v1/auth/verify with return_token: true) works the same way.

Set up

npm install @ignitra/sdk

import { Ignitra } from "@ignitra/sdk";

const ignitra = new Ignitra({
  apiKey: process.env.IGNITRA_API_KEY, // igk_… (or set IGNITRA_API_KEY)
  baseUrl: "https://ignitra.run/api",           // or set IGNITRA_API_URL
});

Flows and runs

Steps without a step_id are named for you (webhook, webhook_2, …). iterateRuns pages through every run as you go.

const flow = await ignitra.flows.create({
  name: "Big buys → my server",
  trigger: { type: "TOKEN_TRANSFER", params: { token: "0x5fc5360d0400a0fd4f2af552add042d716f1d168" } },
  conditions: { all: [{ field: "percent_of_supply", op: ">=", value: 1 }] },
  actions: [{ type: "WEBHOOK", params: { url: "https://myapp.com/hook" } }], // step_id: "webhook"
  activate: true,
});

for await (const run of ignitra.flows.iterateRuns(flow.id)) {
  if (run.status === "failed") console.log(run.id, (await ignitra.runs.get(run.id)).steps);
}

Errors and retries

IgnitraApiError carries status, code, issues (on 422), details and retryAfter. IgnitraNetworkError means no answer arrived. A 429 is retried after Retry-After; 502, 503, 504 and network errors are retried only for requests that are safe to repeat.

import { IgnitraApiError, IgnitraNetworkError } from "@ignitra/sdk";

try {
  await ignitra.flows.create(input);
} catch (err) {
  if (err instanceof IgnitraApiError && err.status === 422) {
    for (const issue of err.issues) console.log(issue.path, issue.message);
  }
  throw err;
}

Verify webhooks

Verify over the raw body, before parsing JSON. On edge runtimes, pass the Request's headers and await request.text(). See Webhooks for the format.

import { parseWebhook, IgnitraSignatureError } from "@ignitra/sdk";

// Express: app.post("/ignitra", express.text({ type: "application/json" }), handler)
async function handler(req, res) {
  let event;
  try {
    event = await parseWebhook(req.body, req.headers, process.env.IGNITRA_WEBHOOK_SECRET);
  } catch (err) {
    if (err instanceof IgnitraSignatureError) return res.sendStatus(401);
    throw err;
  }
  // At-least-once: ignore an X-Ignitra-Idempotency-Key you have handled before.
  res.sendStatus(200);
}

Rate limits

Answers carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; a 429 adds Retry-After (seconds).