SDK documentation

Quickstart

The SDK ships as the workspace package @txguardian/sdk in this monorepo. Clone and link to use it from any project in the workspace:

git clone https://github.com/Omar-Elhorbity/TxGuardian
cd TxGuardian
pnpm install
# The SDK is now resolvable from any workspace package via "@txguardian/sdk"

Five-line integration in any TypeScript project:

import { analyze } from "@txguardian/sdk";
import { Connection } from "@solana/web3.js";

const connection = new Connection(process.env.RPC_URL!);

const result = await analyze({
  transaction: base64Tx,    // string from your wallet's signing prompt
  connection,
  mode: "full",             // "fast" = rules only; "full" = + simulation + AI + on-chain feed
});

if (result.riskLevel === "danger") {
  // Block the user from signing, surface result.flags + result.explanation
}

For Full mode, set GOOGLE_GENERATIVE_AI_API_KEY server-side (free key at aistudio.google.com/apikey). Fast mode works without it.

API reference

analyze(options)

type AnalyzeOptions = {
  transaction: string | VersionedTransaction | Transaction;
  connection: Connection;
  publicKey?: PublicKey;
  mode?: "fast" | "full";
  model?: string; // override LLM model (default: gemini-2.5-flash)
};

TxRiskResult

type TxRiskResult = {
  riskLevel: "safe" | "caution" | "danger";
  score: number;                 // 0–100
  flags: TxRiskFlag[];
  explanation: string;           // Empty in fast mode
  recommendation: "Safe to sign" | "Proceed with caution" | "Do not sign";
  whatThisDoes: string[];        // Empty in fast mode
  decodedInstructions: DecodedInstruction[];
  simulation?: SimulationDelta;
  analyzedAt: string;            // ISO
  mode: "fast" | "full";
};

Invariant: the deterministic verdict (riskLevel, score, flags, recommendation) is always valid. AI failures and on-chain RPC failures degrade to empty fields, never to a wrong verdict.

Registry helpers (on-chain feed)

// Read the live on-chain attestation feed.
import {
  fetchConfirmedAttestations,
  fetchAllAttestations,
  fetchRegistry,
  TXGUARDIAN_REGISTRY_PROGRAM_ID,
} from "@txguardian/sdk";

const attestations = await fetchConfirmedAttestations(connection);
const summary = await fetchRegistry(connection); // admin + counters

Risk flags

Every detected risk is reported as a TxRiskFlag with a stable id, severity, label, description, and structured evidence (including evidence.source for drainer matches: "hardcoded" or "onchain").

On-chain registry

The drainer blocklist isn't hardcoded — it lives on-chain as an Anchor program deployed on Solana devnet. Anyone can submit a flag; an admin keypair confirms or revokes; the SDK reads confirmed entries via getProgramAccounts with memcmp filters.

The SDK's drainer rule consults both the hardcoded list AND the on-chain feed. Each flag's evidence.source field tags the origin so the UI can show provenance.

Visit the live registry view to see current entries.

Integration patterns

Wallet adapter (pre-sign hook)

// In your wallet's sign-transaction handler
async function onBeforeSign(tx: VersionedTransaction): Promise<boolean> {
  const result = await analyze({ transaction: tx, connection, mode: "full" });

  if (result.riskLevel === "danger") {
    // Show TxGuardian's verdict + flags in your wallet UI
    return await showWarningSheet(result); // returns user's decision
  }
  return true; // proceed to native signing
}

Next.js API route

// app/api/check/route.ts
import { analyze } from "@txguardian/sdk";
import { Connection } from "@solana/web3.js";

const connection = new Connection(process.env.RPC_URL!);

export async function POST(req: Request) {
  const { transaction } = await req.json();
  const result = await analyze({ transaction, connection, mode: "full" });
  return Response.json(result);
}