📈 @tetrac/sdk

Multi-exchange trading & market-data SDK for Node, browsers, and edge runtimes — 30+ CEXs and DEXs behind one typed interface, a multi-timeframe technical scanner, market intelligence, and pluggable credential storage so the same trading code runs in a browser and in a local agent.

npm · Documentation · API reference · Examples · Changelog

| | | | --- | --- | | 🌐 Isomorphic core | No Node built-ins, no Solana, no runtime globals. Bundles for a browser, edge runtime, Node, Deno, or Bun with zero bundler configuration — enforced by a test, not by discipline. | | 🪶 5 KB gzipped | Core entry. 5 packages installed, 0 audit findings; everything runtime-specific is an opt-in subpath. | | 🔑 Pluggable credentials | .env on a server, AES-GCM encrypted-on-device in a browser, or memory-only. Same trading code, one line different. | | 🧮 Typed end to end | Tree-shakeable, with correct ESM + CommonJS types in all four resolution modes — verified against the published tarball in CI. | | 🪙 Optional x402 payments | Pay-per-call auth over Solana, behind a subpath, so you only carry the bundle cost if you use it. |

📦 Install

npm install @tetrac/sdk

Requires Node ≥ 20.19, or any browser / edge runtime with Web Crypto.

Nothing else is pulled in. For x402 micropayment auth, add its optional peers:

npm install @solana/web3.js @solana/spl-token

🚀 Quick start

1. Authenticate

With a Tetracsession — free, and the right choice if your users have accounts. Registration and login live in @tetrac/login-sdk; this SDK consumes the session it mints.

import { TtcClient } from "@tetrac/sdk";

const ttc = new TtcClient({
  authToken: process.env.TTC_TOKEN!,
  publicKey: process.env.TTC_PUBKEY!,
});

Or pay per call — no account, $0.05 USDC on Solana mainnet per paid request, from a wallet you fund.

import { X402Signer } from "@tetrac/sdk/x402";

const ttc = new TtcClient({
  x402: new X402Signer({ keypair: process.env.SOLANA_SECRET_KEY!, rpcUrl: process.env.SOLANA_RPC! }),
});

⚠️ Every paid call is a real on-chain transaction. The server enforces replay protection, so each request pays again. If both modes are configured, session auth wins.

Details, including how to pay through something other than a Solana keypair: docs/authentication.md.

2. Call something

const news = await ttc.intelligence.news();
const funding = await ttc.markets.fundingRates({ symbol: "BTCUSDT" });
const { data } = await ttc.scanner.run({ symbol: "BTCUSDT", timeframe: "1h" });

console.log(data.signal.direction, data.signal.confidence); // "LONG" "HIGH"

| Resource | What's there | | --- | --- | | ttc.markets | Tickers, funding rates, open interest, new listings, cross-exchange and DEX volume | | ttc.scanner | Multi-timeframe Quadrant scan → a trade signal with entry, stop, and targets | | ttc.intelligence | News, AI insights, economic calendar, market-quake events | | ttc.exchanges | One interface to 34 venues — normalized reads and order execution |

Full method list: docs/api-reference.md.

3. Trade (needs exchange API keys)

Keys are passed inline or resolved from a credential provider — the one line that differs between a server agent and a browser app:

import { EnvCredentials } from "@tetrac/sdk/node";     // keys from .env
import { EncryptedVault } from "@tetrac/sdk/browser";  // AES-GCM, on the user's device
import { MemoryCredentials } from "@tetrac/sdk";       // session-only

const ttc = new TtcClient({ authToken, publicKey, credentials: new EnvCredentials() });

// …identical from here, whichever provider you chose
const balances = await ttc.exchanges.getBalance("binance");
const positions = await ttc.exchanges.getPositions("hyperliquid");

// ⚠️ places a REAL order with REAL funds
await ttc.exchanges.execute({
  exchangeName: "binance",
  method: "placeMarketOrder",
  params: { symbol: "BTCUSDT", side: "buy", quantity: 0.01 },
});

🔐 Browser storage has limits. If you are putting EncryptedVault in front of end users, read what it does and does not protect against before you ship. It defends against storage theft, not against XSS.

4. Handle failures

Every error extends TtcError; API responses map to subclasses you can branch on. For anything shown to a user, prefer detail — it carries the venue's own complaint ("API-key format invalid") rather than the generic outer message.

import { TtcApiError, TtcAuthError } from "@tetrac/sdk";

try {
  await ttc.markets.openInterest();
} catch (e) {
  if (e instanceof TtcAuthError) refreshSession();          // 401
  else if (e instanceof TtcApiError) setError(e.detail ?? e.message);
}

The full hierarchy is in docs/errors.md.

🧪 Examples

Runnable, and typechecked in CI against src/, so a breaking change fails in the commit that introduces it rather than after publish.

| File | Shows | | --- | --- | | local-agent.ts | A trading agent on your own machine — EnvCredentials, typed reads | | browser-vault.ts | The same code in a browser — EncryptedVault, keys never leave the device | | session-auth.ts | Market data with a session token | | volume-snapshot.ts | Cross-exchange 24h volume league table, plus OI per venue | | swap-volume.ts | 30-day DEX swap-volume trend, charted in the terminal | | scanner-signal.ts | Scan → size against real balances → place an order | | x402-payment.ts | Pay-per-call auth, no account | | account-crypto.ts | Recover a wallet secret from a stored blob |

local-agent.ts and browser-vault.ts are deliberately the same program with one line different. That is the whole thesis of 0.2.

npx tsx examples/local-agent.ts

📚 Documentation

| Page | Covers | | --- | --- | | authentication.md | Session tokens, x402 micropayments, where accounts come from | | credentials.md | Exchange API keys — providers, browser storage, writing your own | | api-reference.md | Every resource and method, typed reads, raw dispatch | | configuration.md | Client and signer options, environment variables | | errors.md | The error hierarchy, and which message to show a user | | architecture.md | Subpaths, bundle budget, the import boundaries that keep it isomorphic | | crypto.md | @tetrac/sdk/crypto — key derivation and wallet-blob decryption | | migration-0.1-to-0.2.md | Upgrading from 0.1.x | | development.md | Building, testing, and publishing this package |

🔄 Upgrading from 0.1.x

X402Signer moved to @tetrac/sdk/x402 and is now constructed by you, ttc.auth was removed in favour of @tetrac/login-sdk, and the browser workarounds for fetch and crypto can be deleted. Everything else is source-compatible — full table in docs/migration-0.1-to-0.2.md.

📄 License

MIT — see LICENSE. Built against the TetracTrading API (OpenAPI spec, x402 details at /.well-known/x402.json).