Markets API

Markets are the core entity of the prediction platform. Each market represents a question with two or more possible outcomes that can be traded.

Authentication: All market routes require X-Api-Key header unless noted otherwise.

Create Market

Create a new prediction market.

POST /api/v1/markets

Request Body:

Field	Type	Required	Description
title	string	Yes	Market question/title
description	string	No	Detailed description
categoryId	string	No	Category UUID
imageUrl	string	No	Market image URL
currency	string	No	Currency code (default: USD). Must be one of the operator's supportedCurrencies.
tradingStartsAt	string (ISO 8601)	No	When trading opens
tradingEndsAt	string (ISO 8601)	No	When trading closes
outcomes	array	No	Array of outcome objects
metadata	object	No	Arbitrary JSON metadata

Outcome Object:

Field	Type	Required	Description
name	string	Yes	Outcome name (e.g., "Yes", "No")
description	string	No	Outcome description

Example:

curl -X POST https://polymarket.sandbox.playbatman.com/api/v1/markets \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Will Bitcoin exceed $100K by March 2026?",
    "description": "Resolves YES if BTC/USD exceeds $100,000 at any point before March 31, 2026",
    "categoryId": "uuid-of-crypto-category",
    "currency": "KES",
    "tradingStartsAt": "2026-02-20T00:00:00Z",
    "tradingEndsAt": "2026-03-31T23:59:59Z",
    "outcomes": [
      { "name": "Yes", "description": "Bitcoin exceeds $100K" },
      { "name": "No", "description": "Bitcoin does not exceed $100K" }
    ]
  }'

Response (201 Created):

{
  "success": true,
  "data": {
    "id": "market-uuid",
    "operatorId": "operator-uuid",
    "categoryId": "category-uuid",
    "title": "Will Bitcoin exceed $100K by March 2026?",
    "description": "Resolves YES if BTC/USD exceeds $100,000...",
    "imageUrl": null,
    "status": "DRAFT",
    "currency": "KES",
    "tradingStartsAt": "2026-02-20T00:00:00.000Z",
    "tradingEndsAt": "2026-03-31T23:59:59.000Z",
    "resolvedAt": null,
    "winningOutcomeId": null,
    "resolutionSource": null,
    "resolutionNotes": null,
    "totalVolume": "0",
    "totalTrades": 0,
    "metadata": null,
    "createdAt": "2026-02-18T22:00:00.000Z",
    "updatedAt": "2026-02-18T22:00:00.000Z",
    "outcomes": [
      {
        "id": "outcome-uuid-1",
        "name": "Yes",
        "description": "Bitcoin exceeds $100K",
        "index": 0,
        "createdAt": "2026-02-18T22:00:00.000Z",
        "updatedAt": "2026-02-18T22:00:00.000Z"
      },
      {
        "id": "outcome-uuid-2",
        "name": "No",
        "description": "Bitcoin does not exceed $100K",
        "index": 1,
        "createdAt": "2026-02-18T22:00:00.000Z",
        "updatedAt": "2026-02-18T22:00:00.000Z"
      }
    ],
    "category": {
      "id": "category-uuid",
      "name": "Crypto",
      "slug": "crypto"
    }
  }
}

Currency Validation

The currency field must match one of the currencies configured in the operator's supportedCurrencies list. If the operator's account is set up with ["KES", "USD"], only those currencies are allowed. Submitting an unsupported currency returns a 400 error:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Currency 'EUR' is not allowed. Supported currencies: KES, USD"
  }
}

Get Market

Retrieve a single market by ID.

GET /api/v1/markets/{id}

Response: Same shape as Create Market response.

List Markets

List markets for your operator account.

GET /api/v1/markets

Query Parameters:

Parameter	Type	Description
categoryId	string	Filter by category
status	string	Comma-separated statuses (e.g., OPEN,CLOSED)
search	string	Search by title
cursor	string	Pagination cursor
limit	number	Page size (default: 20)

Example:

curl "https://polymarket.sandbox.playbatman.com/api/v1/markets?status=OPEN,UPCOMING&limit=10" \
  -H "X-Api-Key: your-api-key"

Response:

{
  "success": true,
  "data": {
    "markets": [ ... ],
    "total": 42,
    "hasMore": true,
    "nextCursor": "cursor-value"
  }
}

Update Market

Update a market's details. Only markets in DRAFT or UPCOMING status can have their title, description, and trading times updated.

PATCH /api/v1/markets/{id}

Request Body:

Field	Type	Description
title	string	Updated title
description	string	Updated description
imageUrl	string	Updated image URL
categoryId	string	Updated category
tradingStartsAt	string (ISO 8601)	Updated start time
tradingEndsAt	string (ISO 8601)	Updated end time
metadata	object	Updated metadata

Market Lifecycle Actions

Open Market

Transition a market from DRAFT to OPEN (or UPCOMING if tradingStartsAt is in the future).

POST /api/v1/markets/{id}/open

Suspend Market

Temporarily pause trading on an open market.

POST /api/v1/markets/{id}/suspend

Request Body:

Field	Type	Required	Description
reason	string	Yes	Reason for suspension

Resume Market

Resume trading on a suspended market.

POST /api/v1/markets/{id}/resume

Close Market

Close a market to stop all trading. Typically done when the underlying event has occurred.

POST /api/v1/markets/{id}/close

Resolve Market

Declare the winning outcome for a closed market.

POST /api/v1/markets/{id}/resolve

Request Body:

Field	Type	Required	Description
winningOutcomeId	string	Yes	UUID of the winning outcome
resolutionSource	string	Yes	Source of truth (e.g., "Official FIFA results")
resolutionNotes	string	No	Additional context

Example:

curl -X POST https://polymarket.sandbox.playbatman.com/api/v1/markets/{marketId}/resolve \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "winningOutcomeId": "outcome-uuid-1",
    "resolutionSource": "CoinGecko BTC/USD price feed",
    "resolutionNotes": "BTC hit $105,432 on March 15, 2026"
  }'

Cancel Market

Cancel a market. All open orders are cancelled.

POST /api/v1/markets/{id}/cancel

Request Body:

Field	Type	Required	Description
reason	string	Yes	Reason for cancellation

Valid Status Transitions

From	To
DRAFT	OPEN, UPCOMING, CANCELLED
UPCOMING	OPEN, CANCELLED
OPEN	SUSPENDED, CLOSED, CANCELLED
SUSPENDED	OPEN, CLOSED, CANCELLED
CLOSED	RESOLVED, CANCELLED
RESOLVED	SETTLED