Quickstart

This docs section reflects the target public SDK surface we are standardizing around:

• @sdk.markets/sdk for TypeScript
• @sdk.markets/react for React hooks
• hosted creation flows for normal users
• self-custody flows for agents and bots
• direct onchain parimutuel actions where needed

The current contracts and low-level viem wrapper remain the foundation, but the docs now describe the surface we are building toward so apps, agents, and hosted flows share the same model.

Install

bun add @sdk.markets/sdk @sdk.markets/react @tanstack/react-query wagmi viem

If you only need the core TypeScript SDK:

bun add @sdk.markets/sdk viem

For React Native Expo apps using hosted mode, import the hosted and input subpaths:

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

TypeScript client

Use MarketsClient as the top-level entry point:

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

const client = new MarketsClient({
  environment: "sandbox",
  apiKey: process.env.NEXT_PUBLIC_MARKETS_API_KEY!,
});

The client is split into modules:

• client.markets for hosted creation, reads, and direct lifecycle actions
• client.drafts for validation and draft generation
• client.account for balances, approvals, and wallet-aware helpers
• client.jobs for async hosted execution

Expo hosted client

The current hosted SDK surface is available today and matches the CLI's hosted market-creation flow:

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 we ship the Expo app this week?",
  options: ["Yes", "No"],
  closeTime: "friday 5 pm",
  resolutionMode: "SingleAdmin",
});

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

Use @sdk.markets/sdk/hosted for hosted auth, account, market job, and close-time inference calls. Use @sdk.markets/sdk/inputs to validate and normalize form data before submitting a hosted market creation request.

For mobile apps that call their own backend first, use the server-to-server path and keep the SDK on the backend. A backend action can use @sdk.markets/sdk/inputs to normalize the form payload and Markets.prepareCreateTransaction to build calldata for a backend wallet provider. In that architecture the client app does not need to hold an SDK actor token.

The long-term SDK goal is to support all of these modes cleanly: hosted platform sessions, browser/mobile wallet clients, backend wallet providers, and server-to-server integrations.

Create a market

Use the hosted creation flow when you want the product-shaped path:

const market = await client.markets.createAndWait({
  question: "Will we ship v2 before July 1?",
  options: ["Yes", "No"],
  closeTime: "2026-07-01T00:00:00Z",
  resolutionMode: "SingleAdmin",
});

console.log(market.marketAddress);

Hosted draft generation is still planned. In the current SDK, client.drafts.* methods fail with explicit "not available" errors until those hosted endpoints are published.

Use direct creation when you want explicit contract parameters:

import { createPublicClient, createWalletClient, http } from "viem";
import { baseSepolia } from "viem/chains";

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

const walletClient = createWalletClient({
  chain: baseSepolia,
  transport: http(),
});

const directClient = new MarketsClient({
  environment: "sandbox",
  apiKey: process.env.NEXT_PUBLIC_MARKETS_API_KEY!,
  publicClient,
  walletClient,
});

const market = await directClient.markets.createDirect({
  question: "Will we ship v2 before July 1?",
  options: ["Yes", "No"],
  closeTime: new Date("2026-07-01T00:00:00Z"),
  challengeWindow: "48h",
  resolution: {
    mode: "multi",
    admins: [admin1, admin2, admin3],
    quorum: 2,
  },
});

React setup

The React package is designed to sit on top of wagmi and TanStack Query:

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { WagmiProvider } from "wagmi";
import { MarketsProvider } from "@sdk.markets/react";

const queryClient = new QueryClient();

export function AppProviders({ children }: { children: React.ReactNode }) {
  return (
    <WagmiProvider config={wagmiConfig}>
      <QueryClientProvider client={queryClient}>
        <MarketsProvider
          environment="sandbox"
          apiKey={process.env.NEXT_PUBLIC_MARKETS_API_KEY!}
        >
          {children}
        </MarketsProvider>
      </QueryClientProvider>
    </WagmiProvider>
  );
}

Privy embedded wallets

The target frontend path is Privy embedded wallets through a wagmi-compatible setup.

For normal hosted flows, the app should already have user auth in place. The SDK then combines:

• the project API key
• the app's authenticated user session
• managed wallet execution behind the scenes

The package split is intentional:

• @sdk.markets/sdk stays provider-agnostic
• @sdk.markets/react works with wagmi-compatible wallet clients
• Privy-specific setup stays in app/provider composition

Direct chain reads and writes can still attach viem clients when needed. They just should not be the default quickstart path for hosted creation.

That keeps the core SDK usable from scripts, backends, tests, and future non-Privy clients.

Agents and bots

The long-term SDK and CLI should support a second explicit lane for automation:

• hosted mode:
  • project API key
  • authenticated user session
  • managed Privy-backed execution
• local-wallet mode:
  • project API key
  • imported or generated wallet
  • direct signer-based execution

Hosted mode should be the default quickstart for product teams. Local-wallet mode should be the default for fully non-interactive bots and agent workflows.

Next