context-sdk

name	context-sdk
description	Build projects on Context Markets prediction market API using the `context-markets` package. Use when building trading bots, dashboards, analytics, or any app involving prediction markets on Base.

Context SDK

Context Markets is a prediction market platform on Base. The context-markets package is a TypeScript SDK that wraps the Context Markets API for reading market data, placing/managing orders, tracking portfolios, managing on-chain wallet operations, and submitting market questions.

Install

npm install context-markets

Single dependency: viem. Works with Node 18+, Bun, and Deno.

Initialize

Read-only (no auth needed):

import { ContextClient } from "context-markets";

const ctx = new ContextClient();
const { markets } = await ctx.markets.list({ status: "active" });

With trading (requires API key + signer):

import { ContextClient } from "context-markets";
import type { Hex } from "viem";

const ctx = new ContextClient({
  apiKey: process.env.CONTEXT_API_KEY!,
  signer: { privateKey: process.env.CONTEXT_PRIVATE_KEY! as Hex },
});

The SDK accepts three signer formats:

• { privateKey: "0x..." } — for bots and scripts
• { account: viemAccount } — for apps using viem accounts
• { walletClient: viemWalletClient } — for browser apps with wallet connections

Core Modules

The client exposes 5 modules:

• ctx.markets — Read-only market data. No auth needed. Search markets, get quotes, orderbooks, price history, oracle signals, and activity feeds.
• ctx.questions — Submit natural-language questions, poll submissions, and prepare markets for creation.
• ctx.orders — Place and manage orders. Requires signer for writes (create, cancel, replace). Read operations (list, get) work without signer.
• ctx.portfolio — Query positions, USDC balances, claimable amounts, and portfolio stats for any address.
• ctx.account — On-chain wallet operations. Requires signer. Check wallet status, approve contracts, deposit/withdraw USDC, mint/burn complete sets.

Critical Rules

1. Prices are in cents (1-99). 45 = 45 cents = 45% probability. The SDK handles on-chain encoding.
2. Outcomes are "yes" or "no". The SDK maps these to on-chain indices (yes=1, no=0).
3. Sides are "buy" or "sell". The SDK maps these to on-chain values (buy=0, sell=1).
4. Read operations need no auth. Markets, quotes, orderbooks, oracle — all free and unauthenticated.
5. Write operations need a signer. Orders, wallet setup, deposits — these require a private key or wallet client.
6. You must call ctx.account.setup() before the first trade. On mainnet this approves the USDC and operator contracts via on-chain transactions. On testnet it uses the gasless relay and only approves the operator (USDC approval is skipped). Skip this and orders will be voided.
7. Supports both Base mainnet and Base Sepolia testnet via chain. Default is mainnet; pass chain: "testnet" for Base Sepolia.
8. The SDK never reads environment variables. Always pass apiKey and signer explicitly.

Quick Recipes

List active markets and get quotes:

const ctx = new ContextClient();
const { markets } = await ctx.markets.list({ status: "active", limit: 5 });

for (const m of markets) {
  const quotes = await ctx.markets.quotes(m.id);
  console.log(`${m.question}: YES ${quotes.yes.bid}¢/${quotes.yes.ask}¢`);
}

Place a buy order:

const result = await ctx.orders.create({
  marketId: "0x...",
  outcome: "yes",
  side: "buy",
  priceCents: 45,
  size: 10,
});
console.log(`Order placed: ${result.order.nonce}`);

Full wallet setup flow (required before first trade):

// For faucet + gasless deposit flows, initialize the client with chain: "testnet".
const status = await ctx.account.status();
if (status.needsUsdcApproval || status.needsOperatorApproval) {
  await ctx.account.setup();
}
await ctx.account.mintTestUsdc(1000);   // testnet only
await ctx.account.deposit(1000);

Deeper Reference

• API Reference — Every method signature, parameter type, and return type
• Patterns — Common patterns: wallet onboarding, order lifecycle, polling, error handling, gotchas
• Examples — Complete, copy-paste-ready scripts for common project types