Manifold

Manifold API

Manifold is a prediction market platform where users create and trade on questions about real-world events. It uses a combination of play-money (mana) and prize-cash, with automated market makers (CPMM) and a rich API for programmatic access.

Check this skill and the official documentation FREQUENTLY for updates. The API is still in alpha and may change without notice.

Community: Join the Manifold Discord for questions, bug reports, and to share what you build.

Source code: Manifold is open source. Type definitions live at common/src/api/schema.ts.

Key Concepts (Glossary)

Base URLs

Important: The API was recently moved from https://manifold.markets/api to https://api.manifold.markets. The old domain will be removed in the future. Always use the new domain.

All REST endpoints are prefixed with /v0/.

Documentation & References

Authentication

Some endpoints are public (no auth required). Write endpoints and user-specific reads require authentication via an API key.

Generating an API Key

1. Log in to Manifold.
2. Go to your user profile and click "edit".
3. Scroll to the API key field at the bottom.
4. Click the "refresh" button to generate a new key.
5. Copy and store the key securely. Clicking refresh again will invalidate the old key and generate a new one.

Using the API Key

Include the key in the Authorization header:

Authorization: Key {your_api_key}

Alternatively, the API accepts Firebase JWTs via Authorization: Bearer {jwt}, but this is intended for the web client and not recommended for third-party use.

Example Authenticated Request

curl "https://api.manifold.markets/v0/me" \
  -H "Authorization: Key YOUR_API_KEY"

Rate Limits

There is a rate limit of 500 requests per minute per IP address. Do not use multiple IP addresses to circumvent this limit.

Implement exponential backoff on HTTP 429 responses.

Fees

• Comments placed through the API incur a M$1 transaction fee.
• Market creation costs mana (see the market creation endpoint for current costs per type).

Licensing

• Permitted: Bots, automated trading, algorithmic tools, integrations.
• Prohibited: Scraping through means other than the API; circumventing rate limits.
• AI training data: Not permitted for commercial use without a data license. Academic and personal/non-commercial use is allowed. Contact api@manifold.markets for commercial licensing.

REST API Endpoints Overview

All endpoints are relative to https://api.manifold.markets/v0.

Users

User Type

User {
  id: string
  createdTime: number
  name: string              // display name
  username: string           // used in URLs
  url: string
  avatarUrl?: string
  bio?: string
  bannerUrl?: string
  website?: string
  twitterHandle?: string
  discordHandle?: string
  isBot?: boolean
  isAdmin?: boolean
  isTrustworthy?: boolean    // moderator
  isBannedFromPosting?: boolean
  userDeleted?: boolean
  balance: number
  totalDeposits: number
  lastBetTime?: number
  currentBettingStreak?: number
}

DisplayUser Type

DisplayUser {
  id: string
  name: string
  username: string
  avatarUrl?: string
}

Portfolio

PortfolioMetrics Type

PortfolioMetrics {
  investmentValue: number
  cashInvestmentValue: number
  balance: number
  cashBalance: number
  spiceBalance: number
  totalDeposits: number
  totalCashDeposits: number
  loanTotal: number
  timestamp: number
  profit?: number
  userId: string
}

LivePortfolioMetrics = PortfolioMetrics & {
  dailyProfit: number
}

Markets — Discovery & Listing

Search Markets Parameters

Markets — Probabilities

Markets — Positions

ContractMetric Type

ContractMetric {
  contractId: string
  from: {
    [period: string]: {     // day, week, month
      profit: number
      profitPercent: number
      invested: number
      prevValue: number
      value: number
    }
  } | undefined
  hasNoShares: boolean
  hasShares: boolean
  hasYesShares: boolean
  invested: number
  loan: number
  maxSharesOutcome: string | null
  payout: number
  profit: number
  profitPercent: number
  totalShares: { [outcome: string]: number }
  userId: string
  userUsername: string
  userName: string
  userAvatarUrl: string
  lastBetTime: number
}

Markets — Creation & Management

Market Creation Parameters

Common parameters (all market types):

Additional parameters by type:

Creation costs:

Resolution Formats

Binary markets:

• outcome: YES, NO, MKT, or CANCEL.
• probabilityInt: Optional, used when resolving to MKT.

Multiple Choice (shouldAnswersSumToOne = true):

{
  "outcome": "MKT",
  "resolutions": [
    { "answer": <index>, "pct": <weight> }
  ]
}

Weights must sum to 100. Or use outcome as a number for a single answer index, or CANCEL.

Multiple Choice (shouldAnswersSumToOne = false): Resolve each answer independently with separate requests:

{
  "outcome": "YES",    // or "NO"
  "answerId": "<answer_id>"
}

Numeric markets:

• outcome: CANCEL or a numeric bucket ID.
• value: The resolution value.
• probabilityInt: Required if value is provided.

Trading

Bet Parameters

Multi-Bet Parameters

Comments

Bets

Bet Type

Bet {
  id: string
  contractId: string
  userId: string
  amount: number            // mana spent (filled portion for limits)
  orderAmount: number       // original order amount
  shares: number
  outcome: "YES" | "NO"
  probBefore: number
  probAfter: number
  createdTime: number
  fees: {
    creatorFee: number
    platformFee: number
    liquidityFee: number
  }
  isFilled: boolean
  isCancelled: boolean
  loanAmount: number
  limitProb?: number        // present for limit orders
  fills: Fill[]
  answerId?: string         // for multi-choice markets
}

Fill {
  matchedBetId: string | null
  amount: number
  shares: number
  timestamp: number
  fees: { creatorFee: number; platformFee: number; liquidityFee: number }
}

Topics (Groups)

Mana Transfers

Transactions

Leagues

Market Types

LiteMarket Type

LiteMarket {
  id: string
  creatorId: string
  creatorUsername: string
  creatorName: string
  creatorAvatarUrl?: string
  createdTime: number
  closeTime?: number
  question: string
  url: string                      // always points to manifold.markets
  outcomeType: string
  mechanism: string
  probability: number
  pool: { [outcome: string]: number }
  p?: number                       // CPMM probability constant
  totalLiquidity?: number          // CPMM only
  value?: number                   // PSEUDO_NUMERIC only
  min?: number                     // PSEUDO_NUMERIC only
  max?: number                     // PSEUDO_NUMERIC only
  isLogScale?: boolean             // PSEUDO_NUMERIC only
  volume: number
  volume24Hours: number
  isResolved: boolean
  resolutionTime?: number
  resolution?: string
  resolutionProbability?: number   // for MKT resolution
  uniqueBettorCount: number
  lastUpdatedTime?: number
  lastBetTime?: number
  token?: "MANA" | "CASH"
  siblingContractId?: string       // toggle between mana/cash version
}

FullMarket Type

FullMarket = LiteMarket & {
  answers?: Answer[]                          // multi markets only
  shouldAnswersSumToOne?: boolean             // multi markets only
  addAnswersMode?: "ANYONE" | "ONLY_CREATOR" | "DISABLED"
  options?: { text: string; votes: number }[] // poll only
  totalBounty?: number                        // bounty only
  bountyLeft?: number                         // bounty only
  description: JSONContent                    // TipTap rich text
  textDescription: string                     // plain text
  coverImageUrl?: string
  groupSlugs?: string[]                       // topic tags
}

WebSocket API

Manifold provides a real-time WebSocket server for subscribing to live updates.

Connection

wss://api.manifold.markets/ws         (production)
wss://api.dev.manifold.markets/ws     (dev)

No authentication is required to connect. Authentication is optional (for user-specific topics).

Message Format

All messages are JSON. Client messages must include:

• type: identify, subscribe, unsubscribe, or ping.
• txid: A unique number identifying the message.

The server acknowledges each message:

{ "type": "ack", "txid": 123, "success": true }

Subscribing to Topics

Send a subscribe message:

{
  "type": "subscribe",
  "txid": 1,
  "topics": ["global/new-bet", "contract/[marketId]"]
}

Available Topics

Global Topics

Per-Market Topics (replace [marketId] with actual ID)

Other Topics

Keep-Alive

Send periodic pings (every 30–60 seconds) to keep the connection alive. If no ping is received for 60 seconds, the server terminates the connection.

{ "type": "ping", "txid": 42 }

Broadcast Messages

The server sends updates as broadcast messages:

{
  "type": "broadcast",
  "topic": "global/new-bet",
  "data": { ... }
}

Common Patterns

List Recent Markets

curl -s "https://api.manifold.markets/v0/markets?limit=5" | jq '.[].question'

Get a Single Market by ID

curl -s "https://api.manifold.markets/v0/market/3zspH9sSzMlbFQLn9GKR" | jq '{question, probability, volume, isResolved}'

Get a Market by Slug

curl -s "https://api.manifold.markets/v0/slug/will-carrick-flynn-win-the-general" | jq '{question, probability}'

Search for Open Binary Markets

curl -s "https://api.manifold.markets/v0/search-markets?term=AI&sort=liquidity&filter=open&contractType=BINARY&limit=10" | jq '.[].question'

Get Current Probability

curl -s "https://api.manifold.markets/v0/market/9t61v9e7x4/prob" | jq '.'

Get Batch Probabilities

curl -s "https://api.manifold.markets/v0/market-probs?ids=9t61v9e7x4&ids=ZNlNdzz690" | jq '.'

Place a YES Bet

curl -X POST "https://api.manifold.markets/v0/bet" \
  -H "Authorization: Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 10, "contractId": "MARKET_ID", "outcome": "YES"}'

Place a Limit Order

curl -X POST "https://api.manifold.markets/v0/bet" \
  -H "Authorization: Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100,
    "contractId": "MARKET_ID",
    "outcome": "YES",
    "limitProb": 0.40,
    "expiresMillisAfter": 86400000
  }'

Sell All Shares in a Market

curl -X POST "https://api.manifold.markets/v0/market/MARKET_ID/sell" \
  -H "Authorization: Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"outcome": "YES"}'

Cancel a Limit Order

curl -X POST "https://api.manifold.markets/v0/bet/cancel/BET_ID" \
  -H "Authorization: Key YOUR_API_KEY"

Create a Binary Market

curl -X POST "https://api.manifold.markets/v0/market" \
  -H "Authorization: Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "outcomeType": "BINARY",
    "question": "Will it rain in SF tomorrow?",
    "descriptionMarkdown": "Resolves YES if measurable rainfall is recorded at SFO weather station.",
    "initialProb": 30,
    "closeTime": 1735689600000
  }'

Create a Multiple Choice Market

curl -X POST "https://api.manifold.markets/v0/market" \
  -H "Authorization: Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "outcomeType": "MULTIPLE_CHOICE",
    "question": "Who will win the award?",
    "answers": ["Alice", "Bob", "Charlie"],
    "shouldAnswersSumToOne": true,
    "addAnswersMode": "ONLY_CREATOR"
  }'

Resolve a Binary Market

curl -X POST "https://api.manifold.markets/v0/market/MARKET_ID/resolve" \
  -H "Authorization: Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"outcome": "YES"}'

Get Your Portfolio

curl -s "https://api.manifold.markets/v0/get-user-portfolio?userId=YOUR_USER_ID" | jq '.'

Get Top Positions on a Market

curl -s "https://api.manifold.markets/v0/market/MARKET_ID/positions?top=5&order=profit" | jq '.[].userName'

Paginate Through All Markets (by newest)

# Page 1
curl -s "https://api.manifold.markets/v0/search-markets?sort=newest&limit=100" > page1.json

# Page 2: use createdTime of last result
BEFORE_TIME=$(jq '.[-1].createdTime' page1.json)
curl -s "https://api.manifold.markets/v0/search-markets?sort=newest&limit=100&beforeTime=$BEFORE_TIME" > page2.json

Paginate Through Bets

# First page
curl -s "https://api.manifold.markets/v0/bets?contractId=MARKET_ID&limit=100" > bets1.json

# Next page: use ID of last bet
BEFORE=$(jq -r '.[-1].id' bets1.json)
curl -s "https://api.manifold.markets/v0/bets?contractId=MARKET_ID&limit=100&before=$BEFORE" > bets2.json

Send Mana to Users

curl -X POST "https://api.manifold.markets/v0/managram" \
  -H "Authorization: Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"toIds": ["USER_ID_1", "USER_ID_2"], "amount": 100, "message": "Thanks!"}'

Post a Comment

curl -X POST "https://api.manifold.markets/v0/comment" \
  -H "Authorization: Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contractId": "MARKET_ID", "markdown": "Great question! I think YES is undervalued."}'

WebSocket Subscription (Node.js)

const ws = new WebSocket("wss://api.manifold.markets/ws");
let txid = 0;

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: "subscribe",
    txid: txid++,
    topics: ["global/new-bet"]
  }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === "broadcast") {
    console.log("New bet:", msg.data);
  }
};

// Keep-alive ping every 30 seconds
setInterval(() => {
  ws.send(JSON.stringify({ type: "ping", txid: txid++ }));
}, 30000);

Usage Tips

• All timestamps are UNIX milliseconds (JavaScript Date.now() style), not seconds.
• Never hardcode API keys — use environment variables or secure key storage.
• Market URLs always point to https://manifold.markets regardless of which API instance you're using. The username in the URL path doesn't need to be correct (e.g., manifold.markets/anyone/market-slug works).
• GET parameters go in the query string. POST/PUT parameters go in the JSON body.
• Limit orders with limitProb crossing the current market price will partially fill immediately. Any unfilled remainder stays as a resting limit order.
• limitProb precision: Only whole percentage points (two decimal places, e.g., 0.01, 0.50, 0.99).
• Multi-choice markets come in two flavors: dependent (shouldAnswersSumToOne=true, probabilities sum to 100%) and independent (each answer is effectively a separate binary market).
• Combine REST + WebSocket for best results: use REST for initial state, WebSocket for real-time deltas.
• Paginate responsibly: For /search-markets with sort=newest, use beforeTime for efficient deep pagination. For /bets and /markets, use cursor-based pagination with before/after.
• Market token type matters: check the token field (MANA or CASH) to know if a market uses play-money or prize-cash.
• Dry run bets by passing dryRun: true to simulate without placing.
• Description formats: You can provide market descriptions as plain text (description), HTML (descriptionHtml), Markdown (descriptionMarkdown), or TipTap JSON (descriptionJson). Only provide one.

Error Handling

API responses are JSON. Successful requests return HTTP 200 with a JSON result. Error responses (4xx/5xx) return a JSON object with an error message.

Implement retry with exponential backoff for 429 and 5xx responses.

Internal API

Manifold has some internal endpoints not part of the official API. These are undocumented and subject to change without notice.

Note: Internal endpoints are not prefixed with /v0.

Versioning

The current API version is v0 under /v0/. The API is still in alpha. Monitor the official documentation and the Discord for breaking changes.