Placing Orders

Submit orders to orderbook-type markets using the POST /api/v1/market/orders endpoint. This is the primary way to trade when the market uses peer-to-peer order matching.

Endpoint

POST /api/v1/market/orders
Authorization: Bearer <token>
Content-Type: application/json

Request Body

Field	Type	Required	Description
`market_id`	integer	Yes	The market to trade on.
`type`	string	Yes	`"buy"` or `"sell"`.
`kind`	string	Yes	`"limit"` or `"market"`.
`token_type`	string	Yes	`"YES"` or `"NO"`.
`price`	integer	Limit only	Price in cents, range 0--10000 (0%--100%). Required for limit orders, ignored for market orders.
`amount`	integer	Yes	For buy orders: budget in cents (how much you want to spend). For sell orders: number of shares in cents (how many shares to sell).
`use_bonus`	boolean	No	If `true`, deducts from the user's bonus balance instead of the main balance. Defaults to `false`.

Key Rules

Price range: Must be between 0 and 10000 (inclusive). A price of 5000 means 50%.
Buy amount = budget: When buying, amount is the total you are willing to spend (in cents). The number of shares received depends on the execution price.
Sell amount = shares: When selling, amount is the number of share-cents you want to sell.
Limit orders require price: The price field is mandatory for limit orders and determines the maximum price (for buys) or minimum price (for sells).
Market orders skip price: Market orders execute immediately at the best available price in the orderbook.

Example: Place a Limit Buy Order

Buy YES tokens on a market at a maximum price of 6500 (65%), spending up to 100000 cents (1000 units of currency):

curl -X POST https://api.intotes.com/api/v1/market/orders \
  -H "Authorization: Bearer eyJhbG..." \
  -H "Content-Type: application/json" \
  -d '{
    "market_id": 100,
    "type": "buy",
    "kind": "limit",
    "token_type": "YES",
    "price": 6500,
    "amount": 100000
  }'

Example: Place a Market Sell Order

Sell 5000 share-cents of NO tokens at the current best bid:

curl -X POST https://api.intotes.com/api/v1/market/orders \
  -H "Authorization: Bearer eyJhbG..." \
  -H "Content-Type: application/json" \
  -d '{
    "market_id": 100,
    "type": "sell",
    "kind": "market",
    "token_type": "NO",
    "amount": 5000
  }'

Response

A successful response returns the created order object with its id, current status, and timestamps. The order begins matching immediately if it is a market order, or enters the orderbook if it is a limit order.

Cancelling an Order

To cancel a pending or partially filled limit order:

DELETE /api/v1/market/orders/{order_id}
Authorization: Bearer <token>

Only orders with status pending or partial can be cancelled. Any unfilled portion is returned to your balance.

Error Cases

Scenario	Description
Insufficient balance	Your balance (or bonus balance if `use_bonus` is true) does not cover the order amount.
Invalid market	The `market_id` does not exist or the market is not active.
Invalid price range	Price is outside 0--10000 for a limit order.
Missing price for limit	A limit order was submitted without the `price` field.
Market closed	The market is no longer accepting orders (event resolved or suspended).

Endpoint​

Request Body​

Key Rules​

Example: Place a Limit Buy Order​

Example: Place a Market Sell Order​

Response​

Cancelling an Order​

Error Cases​

See Also​