TypeScript SDK — @zeq-os/sdk

Local physics computation, HulyaPulse timing, 42-domain operator catalogue, and API client — in one package.

Package status: PLANNED (not yet published)

@zeq-os/sdk is the planned package name — it exists in the repo (app/packages/sdk/) but is private and not published to npm (publishing is pending the self-hosted package-registry decision). Today, use the terminal CLI (/cli/), raw HTTP / fetch() (JavaScript, HTTP / curl), or zeq.py (Python). The surface documented below is the real in-repo client — usable now if you build from the repo, and the contract the published package will keep.

Package @zeq-os/sdk (planned; in-repo, unpublished) Runtime Node 18+, modern browsers Source app/packages/sdk/ License see package LICENSE Precision ≤0.1%

Get the CLI (recommended first install)

Every node serves the terminal CLI with a sha256-pinned installer — the fastest way onto the framework:

curl -fsSL https://zeqstate.com/install.sh | sh   # any node works as the origin
zeq tutorial   # guided: account → machine → first compute → verify

Full install notes + the complete command reference: /cli/.

Install

There is no npm install yet. To use the client today, build it from the repo:

git clone https://github.com/hulyasmath/zeq-framework
cd zeq-framework/app/packages/sdk
pnpm install && pnpm build    # then "file:"-link or workspace-import @zeq-os/sdk

No repo access, or just want a compute now? The same wire calls work with plain fetch() — see JavaScript — or the terminal CLI.

Surface

Export	Purpose
ZeqClient	API client — .compute(), .operators(), .pulse(), .verify()
pulse()	Current HulyaPulse snapshot — { zeqond, phase, R_t }
modulate(s, t)	Universal proper-time modulation R(t) = S(t)[1 + α sin(2πft + φ₀)]
unixToZeqond(u) / zeqondToUnix(z)	Timebase bridge (ZTB1)
computeByDomain(domain, inputs)	Local (no-API) solve by domain
NIST, PULSE_HZ, ZEQOND_SEC, ALPHA_K	Constants (1.287 Hz, 0.777 s, 1.29×10⁻³)
getOperators(), getOperatorsByDomain(), DOMAINS	Operator catalogue
bindConstants(obj)	Lazy-bind kernel constants into a user object

Quickstart

import { ZeqClient, pulse } from "@zeq-os/sdk";

// HulyaPulse snapshot — local, no API key
const p = pulse();
console.log(`Zeqond ${p.zeqond} · phase ${p.phase.toFixed(3)} · R(t) ${p.R_t}`);

// Local compute
const zeq = new ZeqClient();
const result = await zeq.compute({
  domain: "quantum_mechanics",
  inputs: { frequency: 5e14 },
});
console.log(`${result.value} ${result.unit}`);

// Production compute (wraps POST /api/zeq/compute)
const prod = new ZeqClient({ apiKey: process.env.ZEQ_KEY });
const gr = await prod.compute({
  domain: "general_relativity",
  inputs: { M: 2e30, r: 3000 },
});
console.log(gr.value, gr.unit);
console.log(gr.signed.claim.registry_version); // Ed25519-signed claim
console.log(gr.zeqProof, gr.explorer_url);

Every production result carries an Ed25519-signed claim (signed — verifiable offline by anyone, or via any node's public POST /api/attest), the HMAC zeqProof receipt, equations[] + master_sum, the compliance envelope, and explorer_url. Pipe the JSON envelope to the CLI to check it: … | zeq verify -.

Subpath exports

Tree-shakable — import only what you need:

import { computeByDomain } from "@zeq-os/sdk/solvers";
import { getOperators, DOMAINS } from "@zeq-os/sdk/operators";
import { NIST, PULSE_HZ } from "@zeq-os/sdk/constants";

CLI

The package declares a zeq bin (dist/cli.js) — available once you've built it from the repo (not via npx from npm, since nothing is published). For the supported, sha256-pinned terminal CLI that every node serves today, use /cli/ instead:

zeq pulse
zeq compute NM19 mass=5 acceleration=2
zeq operators

Master-equation solve — client.solve() + client.multibody()

ZeqClient.compute() wraps the textbook-dispatch path (/api/zeq/compute). To run the master equation itself and get the full trajectory + register dump + functional energy, use the dedicated client methods. They're typed end-to-end.

import {
  ZeqClient,
  // Types — re-exported from the SDK
  type SolveRequest, type SolveResponse,
  type MultibodyRequest, type MultibodyResponse,
  type RegisterDump,
} from "@zeq-os/sdk";

const zeq = new ZeqClient({ apiKey: process.env.ZEQ_KEY });

// Single-body — feather drop on Earth
const r = await zeq.solve({
  prompt: "feather drop",
  mass: 1e-4,
  location: "earth",
  medium: "air",
  koSettings: { KO42: 1.0 },
});
console.log("errorPct:        ", r.errorPct, "%");
console.log("energy (K+U mean):", r.energy);
console.log("functionalEnergy:", r.functionalEnergy);
console.log("φ_final:         ", r.registerDump.phi_final);
console.log("zero crossings:  ", r.registerDump.zeroCrossings);
console.log("period_s:        ", r.registerDump.period_s);
console.log("frequency_Hz:    ", r.registerDump.frequency_Hz);
console.log("freq / 1.287 Hz: ", r.registerDump.freq_ratio_fH);
console.log("K_mean / U_mean: ", r.registerDump.energy_K_mean, "/", r.registerDump.energy_U_mean);
console.log("momentum_final:  ", r.registerDump.momentum_final);
console.log("angular_proxy:   ", r.registerDump.angular_proxy_mean);

// Strict autotune (≤ 0.1 % error)
const tuned = await zeq.solveStrict({
  prompt: "free-fall calibration",
  mass: 1.0,
  koSettings: { NM19: 1.0, NM24: 0.3 },
  tMax: 0.4, dt: 0.001,
  maxIterations: 40,
  referenceMode: "free-fall",
});
console.log(tuned.tuneStatus, tuned.tuneIterations, tuned.betaFinal);

// Multi-body — Sun-Earth-Moon
const mb = await zeq.multibody({
  prompt: "sun-earth-moon",
  bodies: [
    { mass: 1.989e30, location: "sun",   object: "sun"   },
    { mass: 5.972e24, location: "earth", object: "earth" },
    { mass: 7.342e22, location: "moon",  object: "moon"  },
  ],
  koSettings: { KO42: 1.0, NM21: 0.5, GR35: 0.3 },
});
for (const body of mb.bodies) {
  console.log(`${body.object} (m = ${body.mass}):`, body.registerDump);
}
for (const ix of mb.interactions) {
  console.log(`pair (${ix.bodyA},${ix.bodyB}):  F_avg=${ix.F_avg}, sep_mean=${ix.separation_mean}`);
}

Note: solve(), solveStrict(), and multibody() are server-only — the full master equation runs on the API. They require an API key. Use compute() for local-mode textbook formulas without a key.

Optional request fields (every one is numerical / categorical, never a parsed string):

Field	Type	Use
mass, location, medium, object	number / categorical	Explicit physics inputs. No string parsing.
useOperatorModules	boolean	Use operator-specific physics values (SDK formula path) instead of legacy Σ w·φ.
normalizeOperators	boolean	Default true; commensurate-scale the operator values.
coreOnly	boolean	Restrict to the 8 Core Operator Families (QM/NM/GR/CS/Awareness/HF/AGO/HRO/KO42).
referenceMode	"free-fall" | "shm" | "model"	Analytic comparison target for errorPct.
pairwiseCoupling, pairwiseSoftening	number	(multibody only) γ and ε² in the pairwise interaction.

See /api/framework/ for the full reference.

ZeqWalletClient · v0.2 (2026-05-10)

The wallet client is the read surface for the framework's ZEQ economy. No auth required — pure SUM/COUNT reads against chain-rooted columns.

import { ZeqWalletClient } from "@zeq-os/sdk";

const w = new ZeqWalletClient({ origin: "https://YOUR-FRAMEWORK" });

// Wallet status — balance, tier, daily limit, burn rate
const status = await w.walletStatus("ZEQ07090490306");

// Transparency Oracle — network supply state
const now    = await w.transparencyNow();
const recent = await w.transparencyHistory(60);

// Two-channel revenue ledger (subscriptions + swap pot)
const revenue = await w.revenue();

// Spot crypto swap quote
const quote = await w.swapQuote({ chain: "btc", usd: 50 });

// Foundation pot status
const pot = await w.foundationPot();

// Per-action ZEQ prices (mirror of server-side OPERATION_COSTS)
import {
  OPERATION_COSTS,    // { agent_spawn: 75, llm_html_generation: 100, ... }
  TIER_BURN_RATES,    // { free: 0.998713, starter: 0.995504, ... }
  TIER_DAILY_LIMITS,  // { free: 143, starter: 500, builder: 2500, ... }
  TIER_PRICES,        // { starter: 29, builder: 79, advanced: 199, architect: 499 }
  PRICE_PER_TOKEN_USD // 0.01
} from "@zeq-os/sdk";

tally_charge on every compute call

ZeqClient.compute() responses (v0.2+) include the per-call wallet receipt:

const r = await z.compute({ operators: ["KO42","NM19"], inputs: { m: 2, v: 3 } });

console.log("Charged:",        r.tally_charge.charged,        "ZEQ");
console.log("Burned:",         r.tally_charge.burned);
console.log("To foundation:",  r.tally_charge.toFoundation);
console.log("Wallet now:",     r.tally_charge.remainingAfter);

When the wallet is short the SDK throws ZeqApiError with code: "INSUFFICIENT_BALANCE" — catch and route the user to /tally/ for a top-up.

See also

• API reference — every endpoint ZeqClient and ZeqWalletClient wrap
• ZEQ economy — what the wallet client reads
• BYOK — bring your own LLM key
• Python SDK · MCP SDK
• Operators · Protocols
• Papers: Zeq Paper · Zeq Framework

---

Middleware active. Kernel on the 1.287 Hz HulyaPulse. Awaiting next Zeqond.