manifold

What this skill does

# Manifold API

[Manifold](https://manifold.markets) 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](https://docs.manifold.markets/api) _FREQUENTLY_ for updates. The API is still in alpha and may change without notice.

> **Community:** Join the [Manifold Discord](https://discord.com/invite/eHQBNBqXuh) 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](https://github.com/manifoldmarkets/manifold/tree/main/common/src/api/schema.ts).

---

## Key Concepts (Glossary)

| Term | Definition |
|---|---|
| **Market** (Contract) | A single tradeable question. Called "contract" in the codebase, "market" in the API. Has an outcome type (BINARY, MULTIPLE_CHOICE, PSEUDO_NUMERIC, BOUNTIED_QUESTION, POLL). |
| **Mana (M$)** | Play-money currency used for most markets. Cannot be withdrawn for real money. |
| **Prize Cash (CASH)** | Real-money currency available on select markets. Can be withdrawn. Identified by `token: "CASH"` on a market. |
| **Sibling Contract** | The mana or prize-cash counterpart of a market. Toggle between them via `siblingContractId`. |
| **Topic (Group)** | A tag applied to markets for categorization. Called "group" in the codebase and API. |
| **CPMM** | Constant Product Market Maker. The automated market maker used for binary (`cpmm-1`) and multi-answer (`cpmm-multi-1`) markets. |
| **DPM** | Dynamic Parimutuel Market — a legacy mechanism (`dpm-2`) used for older free-response markets. |
| **Probability** | A number between 0 and 1 representing the market's current implied probability of YES. |
| **Pool** | The liquidity pool of shares backing the market maker. For CPMM markets, shows YES and NO share counts. |
| **Liquidity** | Mana deposited into the AMM pool. More liquidity means less price impact per trade. |
| **Bet** | A trade on a market. Can be a market order or a limit order (when `limitProb` is specified). |
| **Limit Order** | A bet that only executes at a specified probability price or better. Remains open until filled, cancelled, or expired. |
| **Shares** | Units of a position. Winning YES shares pay out M$1 each; losing shares pay M$0. |
| **Resolution** | The final outcome of a market: YES, NO, MKT (probability), or CANCEL. |
| **Answer** | A possible outcome in a MULTIPLE_CHOICE or FREE_RESPONSE market. Each answer has its own probability. |
| **Bounty** | A BOUNTIED_QUESTION market where the creator distributes mana rewards to the best comments/answers. |
| **Poll** | A non-trading market type where users simply vote on options. |

---

## Base URLs

| Environment | REST API | WebSocket |
|---|---|---|
| **Production** | `https://api.manifold.markets` | `wss://api.manifold.markets/ws` |
| **Dev** | `https://api.dev.manifold.markets` | `wss://api.dev.manifold.markets/ws` |

> **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

| Resource | URL |
|---|---|
| API Documentation | <https://docs.manifold.markets/api> |
| Platform | <https://manifold.markets> |
| Source Code (GitHub) | <https://github.com/manifoldmarkets/manifold> |
| API Type Definitions | <https://github.com/manifoldmarkets/manifold/tree/main/common/src/api/schema.ts> |
| Discord Community | <https://discord.com/invite/eHQBNBqXuh> |
| Terms of Service | <https://docs.manifold.markets/terms> |
| Data Downloads & Licensing | <https://docs.manifold.markets/data> |

---

## 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](https://manifold.markets).
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

```bash
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 `[email protected]` for commercial licensing.

---

## REST API Endpoints Overview

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

### Users

| Endpoint | Method | Auth | Description |
|---|---|---|---|
| `/user/[username]` | GET | No | Get a user by username. Returns `User`. |
| `/user/[username]/lite` | GET | No | Get basic display info by username. Returns `DisplayUser`. |
| `/user/by-id/[id]` | GET | No | Get a user by unique ID. Returns `User`. |
| `/user/by-id/[id]/lite` | GET | No | Get display info by ID. Returns `DisplayUser`. |
| `/me` | GET | Yes | Get the authenticated user. Returns `User`. |
| `/users` | GET | No | List all users, ordered by creation date desc. Params: `limit` (max 1000, default 500), `before` (user ID for pagination). |

#### 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

| Endpoint | Method | Auth | Description |
|---|---|---|---|
| `/get-user-portfolio` | GET | No | Get a user's live portfolio metrics. Param: `userId`. |
| `/get-user-portfolio-history` | GET | No | Get portfolio history over a period. Params: `userId`, `period` (`daily`, `weekly`, `monthly`, `allTime`). |
| `/get-user-contract-metrics-with-contracts` | GET | No* | Get a user's positions and their contracts. Params: `userId` (required), `limit` (required), `offset`, `order` (`lastBetTime` or `profit`), `perAnswer`. *When authenticated, may include private market metrics visible to you. |

#### 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

| Endpoint | Method | Auth | Description |
|---|---|---|---|
| `/markets` | GET | N