@ligandal/sdk

Official Node/TypeScript client for the LIGANDAI platform — de novo peptide/binder generation, Boltz-2 folding, DeltaForge thermodynamic scoring, receptor search, and transcriptomics-driven target discovery.

This is a faithful TypeScript port of the ligandai Python SDK. The HTTP surface, endpoints, auth, and semantics match the Python client; names are camelCased.

npm install @ligandal/sdk

Requires Node 18+ (uses the built-in fetch). No runtime dependencies.

Quickstart

import { LigandAI } from "@ligandal/sdk";

// Reads LIGANDAI_API_KEY from the environment by default.
const client = new LigandAI();

// Or pass the key explicitly (string shorthand or options object):
const client2 = new LigandAI("lgai_pro_...");
const client3 = new LigandAI({ apiKey: "lgai_pro_...", baseURL: "https://ligandai.com" });

// Discover targets: SI-ranked surface receptors enriched in a tissue.
const markers = await client.discovery.tissueMarkers({
  targetTissues: ["Liver"],
  receptorOnly: true,
  topN: 200,
});
const gene = (markers.top as any[])[0].gene;

// Generate peptides against the top target, auto-fold, and wait for results.
const job = await client.peptides.generate(gene, { numPeptides: 50, autoFold: true });
const result = await job.wait();
console.log(result);

CommonJS

const { LigandAI } = require("@ligandal/sdk");
const client = new LigandAI({ apiKey: "test" });

Configuration

new LigandAI(options) accepts:

| Option | Env fallback | Default | | --- | --- | --- | | apiKey | LIGANDAI_API_KEY | — | | baseURL | LIGANDAI_BASE_URL | https://ligandai.com | | timeout (ms) | — | 600000 | | maxRetries | — | 3 | | impersonateUser | LIGANDAI_IMPERSONATE_USER | — (superadmin only) | | clientSessionId | — | — | | fetch | — | global fetch (injectable for tests) |

Auth uses Authorization: Bearer <key>. Set LIGANDAI_DEBUG=1 to log every request URL.

Resource namespaces

All 22 namespaces are attached to the client as camelCase getters:

account, analysis, bivalent, charts, deltaforge, discovery, diseases, folds, goals, jobs, ligands, linkerModifications, memory, msa, peptides (alias peptide), programs, proteins, receptors, reports, structures, synthesis.

await client.account.credits();
await client.receptors.search("EGFR");
await client.deltaforge.scoreFold("fold_job_123");
const score = await client.ligands.scoreLigand({ pdbContent, ligandSmiles: "CCO" });

Jobs

Long-running work (generation, folding, scoring) returns a Job<T>:

const job = await client.peptides.fold(
  [receptorSeq, peptideSeq],
  { targetGene: "EGFR" },
);
const fold = await job.wait({ pollIntervalMs: 2000, timeoutMs: 1_800_000 });

// Or stream live progress events (SSE with polling fallback):
for await (const event of job.stream()) {
  console.log(event.eventType, event.progress);
}

Job.wait() for fold jobs is durable by default — it does not resolve until the structural payload (PDB/CIF) has landed. Pass { durable: false } to opt out.

Batch folds return a BatchFoldJob:

const batch = await client.peptides.foldBatch(peptides, {
  targetGene: "EGFR",
  diffusionSamples: 4,
});
const results = await batch.wait(); // Array<FoldResult | null>, aligned with input order

Errors

All errors extend LigandAIError. Status-specific subclasses (and OpenAI-style aliases) are exported:

import {
  LigandAIError,
  LigandAIAuthError,          // 401  (alias: AuthenticationError)
  LigandAICreditError,        // 402  (alias: InsufficientCreditsError)
  LigandAITierError,          // 403 tier gate
  LigandAIForbidden,          // 403  (alias: PermissionDeniedError)
  LigandAINotFoundError,      // 404  (alias: NotFoundError)
  LigandAIValidationError,    // 400/422 (alias: UnprocessableEntityError)
  LigandAIRateLimitError,     // 429  (alias: RateLimitError)
  LigandAIServerError,        // 5xx  (alias: InternalServerError)
} from "@ligandal/sdk";

try {
  await client.peptides.foldBatch(peptides, { targetGene: "EGFR" });
} catch (err) {
  if (err instanceof LigandAICreditError) {
    console.log(`Need ${err.shortfall} more credits (top up: ${err.recoveryUrl})`);
  }
}

CLI

The package installs a ligandai binary:

export LIGANDAI_API_KEY=lgai_pro_...

ligandai credits                    # billing widget
ligandai credits top-up --amount 50
ligandai credits auto-reload --enable --threshold 10000 --amount 200

ligandai keys mint --scope fold --target MKTAYIAKQR... --count 5
ligandai keys status
ligandai keys revoke

MCP server

A companion Model Context Protocol server (@ligandal/mcp) exposes the high-value capabilities as MCP tools for Claude Desktop / Claude Code. See mcp/README.md.

License

Copyright © 2026 Ligandal, Inc. All rights reserved. See LICENSE.