Skip to main content
POST
Python (SDK)
This endpoint is in closed beta. It is available only to accounts enrolled in the beta. Request and response shapes may change before general availability.

Overview

Placement is asynchronous. The endpoint returns 202 Accepted with the order as soon as it has been sent to the venue, normally in state pending_new. The venue’s answer (acknowledgement, rejection with its reason, or fills) arrives afterwards. Read it back with Get Prediction Order using the returned orderId. A 202 means the order was sent. It does not mean the order was accepted by the venue.

Request

  • symbol is a contract symbol from search or Get Event Contracts.
  • outcome is the binary outcome you trade, YES or NO. It is never inferred from side.
  • quantity, price, and stopPx are exact decimals sent as JSON strings.
  • orderType is limit or stop_limit. ForecastEx does not support stop or market_to_limit orders, and both are rejected with 400.
  • Unknown fields are rejected with 400 UNKNOWN_FIELD.
Which price fields are required depends on orderType and timeInForce:

Retry safely with Idempotency-Key

Send an Idempotency-Key header on every order, with a new unique value (such as a UUID) for each order. A retry that repeats the key returns the order that key already placed instead of placing a second one. Keys are scoped to you, the authenticated user.
  • Reusing a key with different order terms returns 400 INVALID_ORDER.
  • Sending the header more than once returns 400 INVALID_IDEMPOTENCY_KEY.
  • Without the header, every request places a new order, and you cannot safely retry after a 504.
clientOrderRef is your own reference for the order, unique per account. It is not a retry key: reusing one returns 409 CLIENT_ORDER_REF_IN_USE.

Handling 504 ORDER_OUTCOME_UNKNOWN

A 504 means the call was cut short and the order may have been placed. Do not treat it as a failure. Either: Never retry a 504 without an Idempotency-Key. Doing so can place the order twice.

Example

Errors

Authorizations

Authorization
string
header
required

OAuth2 Bearer token: obtain an access token from the token endpoint and send it in the Authorization header.

Headers

Idempotency-Key
string

Makes a retry safe. A placement repeating a key you already used returns the order that key placed and places nothing new. The same key with different order terms returns 400 INVALID_ORDER. Without it, every request is a new order. Send it at most once.

Body

application/json

Unknown fields are rejected with 400. The user is always the authenticated caller and cannot be named in the body.

accountId
string
required

The account to place the order on.

Example:

"ACCOUNT-0001"

orderType
enum<string>
required

ForecastEx does not support stop or market_to_limit orders.

Available options:
limit,
stop_limit
Example:

"limit"

outcome
enum<string>
required

The binary outcome the order trades. It is never inferred from side.

Available options:
YES,
NO
Example:

"YES"

quantity
string
required

Number of contracts as an exact decimal string. Must be greater than zero.

Example:

"10"

side
enum<string>
required
Available options:
buy,
sell
Example:

"buy"

symbol
string
required

Prediction-market contract symbol, as returned by search or Get Event Contracts.

Example:

"HORC_1126_Republican"

timeInForce
enum<string>
required
Available options:
day,
gtc,
ioc,
fok,
gtd
Example:

"day"

clientOrderRef
string

Your own reference for the order, unique per account. Reusing one returns 409 CLIENT_ORDER_REF_IN_USE; it is not a retry key. To retry safely, use the Idempotency-Key header.

Example:

"7d1c8e0a-4b8f-4e3a-9f43-2a6b1d0c9e11"

expireTime
string<date-time>

Required when timeInForce is gtd.

price
string

Limit price as an exact decimal string. Required for limit and stop_limit.

Example:

"0.54"

stopPx
string

Stop price as an exact decimal string. Required for stop_limit.

Example:

"0.50"

Response

Order accepted for sending. state is normally pending_new.

Standard success envelope used by all success responses. data is endpoint-specific.

success
boolean
required
Example:

true

data
object

An order as recorded by order entry. Submitted terms (quantity, price, …) never change; working terms (workingQuantity, workingPrice, …) are the venue's answer. Optional decimals and timestamps are omitted when absent, never zero.