TypeScript SDK Installation and First Call

Install, configure, and make your first call with the Magistery TypeScript SDK built on viem.

The Magistery TypeScript SDK provides a complete client for interacting with the protocol. Built on viem.

Install

npm install @magistery/sdk

Quick Start

import { createPublicClient, createWalletClient, http } from "viem";
import { polygon } from "viem/chains";
import { MagisteryClient, DEPLOYED_ADDRESSES } from "@magistery/sdk";

const publicClient = createPublicClient({
  chain: polygon,
  transport: http(),
});

const client = new MagisteryClient({
  publicClient,
  addresses: DEPLOYED_ADDRESSES,
});

// Read a market
const market = await client.getMarket("0x...");
console.log(market.resolved, market.deadline);

// Check if trading is open
const trading = await client.isTrading("0x...");

With a Wallet (for writes)

import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount("0x...");
const walletClient = createWalletClient({
  chain: polygon,
  transport: http(),
  account,
});

const client = new MagisteryClient({
  publicClient,
  walletClient,
  addresses: DEPLOYED_ADDRESSES,
});

// Create a market
const conditionId = await client.createMarket(
  "Will ETH hit $10k by Dec 2026?",
  2,         // binary (YES/NO)
  1767225600n, // deadline timestamp
  DEPLOYED_ADDRESSES.umaResolver!,
);

// Approve USDC for trading
await client.approveUsdc(DEPLOYED_ADDRESSES.orderBook);

// Place a buy order: YES at $0.65, 100 shares
const orderId = await client.placeBuyOrder(
  conditionId,
  0,         // outcome 0 = YES
  650_000n,  // $0.65 in USDC decimals
  100_000_000n, // 100 shares
);

Fee Estimation

// Estimate a BuyVsBuy fill
const estimate = client.estimateFillBuyVsBuy(
  650_000n, // order 0 price
  100_000_000n, // order 0 remaining
  400_000n, // order 1 price
  100_000_000n, // order 1 remaining
);
console.log(estimate.fillAmount, estimate.fee, estimate.surplus);

CLI

The SDK includes a command-line interface for direct interaction with the protocol. No code required.

npx @magistery/sdk market get <conditionId>
npx @magistery/sdk market list
npx @magistery/sdk order buy <conditionId> 0 0.55 100
npx @magistery/sdk order sell <conditionId> 0 0.6 50
npx @magistery/sdk order cancel <orderId>
npx @magistery/sdk position list

Environment variables:

POLYGON_RPC_URL — Required for all commands
MAGISTERY_PRIVATE_KEY — Required for trading and write commands

All commands output JSON (except --help which outputs plain text usage). Prices are 0-1 exclusive, amounts are in shares with max 6 decimal precision.

Safety Checks (for frontends)

// Check if resolver is trusted
const trusted = await client.isTrustedResolver(conditionId, [
  "0x...", // UMA resolver
  "0x...", // Kalshi resolver
]);

// Check if Kalshi market is linked
const linked = await client.isKalshiLinked(conditionId);

// Check if past deadline (danger zone)
const pastDeadline = await client.isPastDeadline(conditionId);