@sdk.markets/sdk

@sdk.markets/sdk is currently a preview package.

The full SDK is not public yet. For now, this package is intentionally minimal while access is gated.

Join the waitlist at sdk.markets.

Status

• Preview only
• Minimal hosted API client for the first platform market-creation slice
• Direct on-chain helpers for local-wallet demos
• Full SDK coming later

Install

bun add @sdk.markets/sdk

npm install @sdk.markets/sdk

pnpm add @sdk.markets/sdk

Current Exports

The SDK currently supports two integration modes:

• Hosted API mode for clients that use the sdk.markets platform session and hosted execution flow.
• Server-to-server direct execution for backends that already own user auth and wallet execution.

The root export includes preview metadata, hosted client helpers, direct market helpers, and shared input helpers:

import {
  PREVIEW_MESSAGE,
  PREVIEW_STATUS,
  WAITLIST_URL,
  createHostedClient,
  getPreviewInfo,
  toHostedCreateMarketInput,
  preview,
} from "@sdk.markets/sdk";

preview() throws an error with the preview message so usage fails clearly instead of pretending the SDK is ready.

For React Native Expo apps, prefer the hosted-only and input subpaths:

import { createHostedClient } from "@sdk.markets/sdk/hosted";
import { toHostedCreateMarketInput } from "@sdk.markets/sdk/inputs";

@sdk.markets/sdk/hosted

Exports only the platform-hosted API client and related hosted types. Use this in Expo/mobile apps when you want the same hosted capabilities the CLI uses:

• browser/device login request creation and polling
• actor session checks
• hosted wallet and balance reads
• hosted market creation jobs
• hosted close-time inference

@sdk.markets/sdk/inputs

Exports the shared market input validation and normalization helpers used by the CLI. Use this in apps before calling hosted creation so CLI and mobile payloads behave the same way:

• validates question/options
• parses ISO, unix, and simple natural close times
• validates admins, quorum, creator fees, and AI oracle sources
• converts app-friendly input into HostedCreateMarketInput

Backend Direct Execution

This is the server-to-server integration path. Backends that already own user auth and wallet execution can use the direct Markets client without passing a viem WalletClient.

In this mode the mobile app calls your backend. Your backend authenticates the user, chooses the wallet, builds the market transaction with the SDK, sends it with its wallet provider, and parses the receipt with the SDK. The mobile app does not hold an sdk.markets actorToken.

import { Markets, toCreateMarketInput } from "@sdk.markets/sdk";
import { createPublicClient, http } from "viem";
import { baseSepolia } from "viem/chains";

const markets = new Markets({
  chain: baseSepolia,
  publicClient: createPublicClient({
    chain: baseSepolia,
    transport: http(process.env.BASE_SEPOLIA_RPC_URL),
  }),
});

const createInput = toCreateMarketInput(payload, userWalletAddress);
const request = markets.prepareCreateTransaction(createInput, userWalletAddress);

// Send `request.to`, `request.data`, and `request.value` with your backend
// wallet provider, then wait for the transaction receipt.
const hash = await sendWithBackendWallet(request);
const receipt = await marketsPublicClient.waitForTransactionReceipt({ hash });
const marketAddress = markets.parseCreateReceipt(receipt);

If your backend can provide a generic transaction sender, createWithExecutor wraps the send, wait, and receipt parsing steps:

const result = await markets.createWithExecutor(createInput, {
  account: userWalletAddress,
  sendTransaction: async (request) => {
    return sendWithBackendWallet(request);
  },
});

This server-to-server shape is intended to sit alongside future first-class wallet-client support. Over time the SDK should support hosted platform sessions, browser/mobile wallet clients, backend wallet providers, and direct server-to-server integrations through the same market domain types.

Hosted Client

The hosted client wraps the current platforms-markets routes:

import { createHostedClient } from "@sdk.markets/sdk";

const client = createHostedClient({
  baseUrl: "https://platforms.markets",
  projectKey: process.env.MARKETS_PROJECT_KEY!,
  actorToken: process.env.MARKETS_ACTOR_TOKEN!,
});

const identity = await client.auth.whoami();
const wallet = await client.account.wallet();
const balance = await client.account.balance();
const job = await client.markets.create({
  question: "Will the CLI create a market?",
  options: ["Yes", "No"],
  closeTime: "2026-06-01T00:00:00Z",
  resolutionMode: "SingleAdmin",
});

const current = await client.jobs.get(job.job.id);
const market = await client.markets.createAndWait({
  question: "Will the SDK wait for a market?",
  options: ["Yes", "No"],
  closeTime: "2026-06-01T00:00:00Z",
  resolutionMode: "SingleAdmin",
});

For Expo/mobile apps, use the hosted subpath:

import { createHostedClient } from "@sdk.markets/sdk/hosted";
import { toHostedCreateMarketInput } from "@sdk.markets/sdk/inputs";

const client = createHostedClient({
  baseUrl: "https://platform.markets",
  projectKey,
  actorToken,
});

const input = toHostedCreateMarketInput({
  question: "Will our Expo app create a market?",
  options: ["Yes", "No"],
  closeTime: "tomorrow 8 pm",
  resolutionMode: "AiOracle",
  resolutionSources: ["https://example.com/source"],
});

const market = await client.markets.createAndWait(input);

The same market payload normalization used by the CLI is available to app clients:

const input = toHostedCreateMarketInput({
  question: "Will our Expo app create a market?",
  options: ["Yes", "No"],
  closeTime: "tomorrow 8 pm",
  resolutionMode: "AiOracle",
  resolutionSources: ["https://example.com/source"],
});

const created = await client.markets.createAndWait(input);

Hosted close-time inference is also exposed through the SDK:

const parsed = await client.markets.parseCloseTime({
  question: "Will Base hit 1M daily transactions by Friday?",
});

Browser handoff login is available for CLI/user sessions:

const login = await client.auth.startLogin();
console.log(login.login.url, login.login.code);

const claimed = await client.auth.pollLogin(login.login.requestId);
if (claimed.login.session) {
  client.setActorToken(claimed.login.session.actorToken);
}

Temporary bootstrap auth is available for local/dev demos while the real browser/device login flow is being hardened:

const client = createHostedClient({
  baseUrl: "http://localhost:3000",
  projectKey: process.env.MARKETS_PROJECT_KEY!,
  bootstrapKey: process.env.MARKETS_BOOTSTRAP_KEY!,
});

const session = await client.auth.bootstrap({ actorName: "local-operator" });
console.log(session.actorToken);