> ## Documentation Index > Fetch the complete documentation index at: https://docs.splashsports.com/llms.txt > Use this file to discover all available pages before exploring further. # Place an order > Places a fill-or-kill order on one market. Use it to buy YES or NO contracts at your limit `price` or better. A `200` means the order was **accepted**, not filled: the order is queued. Poll [`GET /orders?request_id=`](/predictions/reference/orders/list-orders) (or [`GET /orders/{id}`](/predictions/reference/orders/get-an-order) with the `order_id` this call returns) until `status` is `executed` or `cancelled`. Send the raw order only. There is no fee field: Splash computes the fee from your account's fee settings, adds it to a buy's debit and takes it from a close's proceeds. To check before sending that you have enough cash, compute the order's cost from `fee` on [Get account](/predictions/reference/account/get-account) and compare it with `cash_available` on [Get balance](/predictions/reference/account/get-balance); see [Fees and order cost](/predictions/fees). A buy without enough cash is accepted and then cancelled without filling. Sign the request with your API key; see [Authentication](/predictions/authentication). A request without the `SPLASH-ACCESS-KEY` header is not treated as an API request and is a `401`. `request_id` is your idempotency key: one `request_id` never places more than one order. What to do after each answer: - **`200` with `order_status: "pending"`**: the order is queued. Poll until `executed` or `cancelled`. - **No response** (your client timed out, the connection dropped) or a **`504`** from the gateway: the outcome is unknown, and the order may have gone through. Check `GET /orders?request_id=`. If it returns the order, follow it. If it returns nothing, send the request again with the same `request_id`; it can never place the order twice. - **Refused before the order was accepted**: `401`, `415`, `429`, `400 Invalid request parameters`, `400 IOC orders are not yet supported` and `503 TRADING_API_UNAVAILABLE`. Nothing was recorded; fix the cause (after a `429`, wait the `Retry-After` seconds when that header is present, otherwise about a second) and retry with the same `request_id`. - **Any other error**: a `400` order-check message (`Invalid price`, `Market is not active` and the rest), `403`, `404`, `409`, `503 EXCHANGE_UNAVAILABLE` or `SERVICE_UNAVAILABLE`, and `500`. The order was not placed and that `request_id` is spent: polling it reads `cancelled` with the reason in `error`, and sending it again returns `200` with `order_status: "cancelled"` without placing anything. Send a new `request_id` to try again. See [Order outcomes and retries](/predictions/trading#order-outcomes-and-retries). Only `time_in_force: "FOK"` is accepted today; `IOC` is coming and is a `400` until then. The `market_id` is a market's `id` from the market endpoints. The order fills completely at your price or better, or is cancelled; it never partially fills. ## OpenAPI ````yaml /predictions/openapi.json post /trading/orders openapi: 3.1.0 info: title: Splash Predictions API version: 1.0.0 description: >- Splash prediction markets: leagues, games, game lines, futures and player props, and the signed routes to place orders, read your orders, positions and transactions, and read your account's fee settings and cash balance. The market endpoints need no authentication; the order, position, account and balance endpoints are [signed with an API key](/predictions/authentication). servers: - url: https://api.splashsports.com/predictions-service/api description: Production security: [] tags: - name: Discover description: The home feed. - name: Sub-categories description: Leagues, their availability and their tabs. - name: Markets description: Market group listings and single groups. - name: Events description: One game's markets, shaped for the game page. - name: Orders description: Place orders and read them. Signed requests. - name: Positions description: Read your positions. Signed requests. - name: Activity description: 'Your transaction history: fills and settlement payouts. Signed requests.' - name: Account description: Your fee settings, maximum trade and cash balance. Signed requests. paths: /trading/orders: post: tags: - Orders summary: Place an order description: >- Places a fill-or-kill order on one market. Use it to buy YES or NO contracts at your limit `price` or better. A `200` means the order was **accepted**, not filled: the order is queued. Poll [`GET /orders?request_id=`](/predictions/reference/orders/list-orders) (or [`GET /orders/{id}`](/predictions/reference/orders/get-an-order) with the `order_id` this call returns) until `status` is `executed` or `cancelled`. Send the raw order only. There is no fee field: Splash computes the fee from your account's fee settings, adds it to a buy's debit and takes it from a close's proceeds. To check before sending that you have enough cash, compute the order's cost from `fee` on [Get account](/predictions/reference/account/get-account) and compare it with `cash_available` on [Get balance](/predictions/reference/account/get-balance); see [Fees and order cost](/predictions/fees). A buy without enough cash is accepted and then cancelled without filling. Sign the request with your API key; see [Authentication](/predictions/authentication). A request without the `SPLASH-ACCESS-KEY` header is not treated as an API request and is a `401`. `request_id` is your idempotency key: one `request_id` never places more than one order. What to do after each answer: - **`200` with `order_status: "pending"`**: the order is queued. Poll until `executed` or `cancelled`. - **No response** (your client timed out, the connection dropped) or a **`504`** from the gateway: the outcome is unknown, and the order may have gone through. Check `GET /orders?request_id=`. If it returns the order, follow it. If it returns nothing, send the request again with the same `request_id`; it can never place the order twice. - **Refused before the order was accepted**: `401`, `415`, `429`, `400 Invalid request parameters`, `400 IOC orders are not yet supported` and `503 TRADING_API_UNAVAILABLE`. Nothing was recorded; fix the cause (after a `429`, wait the `Retry-After` seconds when that header is present, otherwise about a second) and retry with the same `request_id`. - **Any other error**: a `400` order-check message (`Invalid price`, `Market is not active` and the rest), `403`, `404`, `409`, `503 EXCHANGE_UNAVAILABLE` or `SERVICE_UNAVAILABLE`, and `500`. The order was not placed and that `request_id` is spent: polling it reads `cancelled` with the reason in `error`, and sending it again returns `200` with `order_status: "cancelled"` without placing anything. Send a new `request_id` to try again. See [Order outcomes and retries](/predictions/trading#order-outcomes-and-retries). Only `time_in_force: "FOK"` is accepted today; `IOC` is coming and is a `400` until then. The `market_id` is a market's `id` from the market endpoints. The order fills completely at your price or better, or is cancelled; it never partially fills. operationId: placeOrder requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PlaceOrderRequest' examples: 'Buy YES: 10 Chiefs to win at up to $0.59': summary: 'Buy YES: 10 Chiefs to win at up to $0.59' value: market_id: pm_6ae1e3c09e1d4c7a2b5f80e3d6a9c412 side: 'yes' quantity: 10 price: 0.59 time_in_force: FOK request_id: 3f1c2a9e-5b7d-4e0a-9c1d-8a6b2e4f7d10 'Buy NO: 20 of the under 47.5 at up to $0.47': summary: 'Buy NO: 20 of the under 47.5 at up to $0.47' value: market_id: pm_6ae1e3c08d5c2a7e3f9b41e6d2c8a604 side: 'no' quantity: 20 price: 0.47 time_in_force: FOK request_id: 8d2e6f40-1c3b-4a7e-b5d9-2f0a7c6e1b84 description: NO on a total is the under. `price` is the NO price. Sell 10 YES at $0.66 or better: summary: Sell 10 YES at $0.66 or better value: market_id: pm_6ae1e3c09e1d4c7a2b5f80e3d6a9c412 side: 'no' quantity: 10 price: 0.34 time_in_force: FOK request_id: c47b19e2-0f6d-4b8a-a3e5-71d9f2c08a56 description: >- Holding 10 YES, an order for `no` sells them. `price` is in NO terms: 0.34 NO is 0.66 YES. The quantity must be every contract you hold. responses: '200': description: >- Accepted. `order_status` is `pending` on a new order. A `request_id` you already used returns that order and its current status instead of placing another: `cancelled` when the first request was refused. content: application/json: schema: $ref: '#/components/schemas/PlaceOrderResponse' examples: Accepted: summary: Accepted value: status: success order_id: ord_6aedec658f3a61c2d94e07b5a1c6e2d9 request_id: 3f1c2a9e-5b7d-4e0a-9c1d-8a6b2e4f7d10 order_status: pending description: >- Accepted, not filled. Poll `GET /orders?request_id=` for the outcome. Replayed request_id: summary: Replayed request_id value: status: success order_id: ord_6aedec658f3a61c2d94e07b5a1c6e2d9 request_id: 3f1c2a9e-5b7d-4e0a-9c1d-8a6b2e4f7d10 order_status: executed description: >- The same `request_id` sent again after the order filled: the original order, its current status, and no second order. Replayed request_id of a refused order: summary: Replayed request_id of a refused order value: status: success order_id: ord_6aededb87e1c4b9f2d6a03e8b5c1d7f2 request_id: a6d0e3b7-92c4-4f1e-8b5a-d3c7f0e9a214 order_status: cancelled description: >- The first request with this `request_id` was refused (here `400 Market is not active`), which spent the `request_id`. Sending it again reports `cancelled` and places nothing. Send a new `request_id` to try again. '400': description: >- The body failed validation or an order check failed; `message` says which. `Invalid request parameters` and `IOC orders are not yet supported` are refused before the order is accepted, so nothing is recorded and the same `request_id` can be sent again once the body is fixed. Every other message comes from an order check after the `request_id` was taken: the order was not placed, the `request_id` is spent, and a retry needs a new one. Those messages are `Invalid price`, `Invalid quantity`, `Market is not active`, `Not eligible to trade this market`, `Order exceeds the maximum trade of $` (where `` is the account's configured maximum), `You already own the other side of this market. Please sell your open position for this market first.` and `Trading is temporarily disabled for scheduled maintenance. Please try again later.` See [Order outcomes and retries](/predictions/trading#order-outcomes-and-retries). content: application/json: schema: $ref: '#/components/schemas/TradingError' examples: Body failed validation: summary: Body failed validation value: status: error error: BAD_REQUEST message: Invalid request parameters description: >- A missing field, a wrong type, `side` other than `yes` or `no`, or a bad `request_id`. Nothing was recorded: fix the body and send it again with the same `request_id`. IOC not supported: summary: IOC not supported value: status: error error: BAD_REQUEST message: IOC orders are not yet supported description: >- `time_in_force` was `IOC`. Nothing was recorded: send it again as `FOK` with the same `request_id`. Price out of range: summary: Price out of range value: status: error error: BAD_REQUEST message: Invalid price description: >- `price` outside 0.01 to 0.99. The `request_id` is spent; send the corrected order with a new one. Invalid quantity: summary: Invalid quantity value: status: error error: BAD_REQUEST message: Invalid quantity description: >- `quantity` below 1. The `request_id` is spent; send the corrected order with a new one. Market not active: summary: Market not active value: status: error error: BAD_REQUEST message: Market is not active description: >- The market has stopped trading (it expired or settled). The `request_id` is spent. Not eligible to trade this market: summary: Not eligible to trade this market value: status: error error: BAD_REQUEST message: Not eligible to trade this market description: >- Your account may not buy in this market's league. Closing a position you already hold is not refused this way. The `request_id` is spent. Order exceeds the maximum trade: summary: Order exceeds the maximum trade value: status: error error: BAD_REQUEST message: Order exceeds the maximum trade of $100000 description: >- The cost of the contracts a buy opens is above the account's configured per-order maximum, which the message states in dollars as `$`. The $100000 shown here is illustrative; your message carries your own limit. A close is never refused for size. The `request_id` is spent; send a smaller order with a new one. Opposite side held, or a partial close: summary: Opposite side held, or a partial close value: status: error error: BAD_REQUEST message: >- You already own the other side of this market. Please sell your open position for this market first. description: >- Also the answer to a close for fewer or more contracts than you hold. The `request_id` is spent. Trading paused: summary: Trading paused value: status: error error: BAD_REQUEST message: >- Trading is temporarily disabled for scheduled maintenance. Please try again later. description: >- Splash has paused trading for scheduled maintenance. The `request_id` is spent; after the pause, send the order with a new one. '401': description: >- The signature check failed, or the request had no `SPLASH-ACCESS-KEY` header. A failed check's `message` is one of `Unknown API key`, `API key revoked`, `Timestamp outside the allowed window` or `Invalid signature`. `API key revoked` is reported only when the signature is correct, so a wrong secret always reads `Invalid signature`. A request without the `SPLASH-ACCESS-KEY` header is not an API request and is refused with `You are not authorized to perform the requested action.` See [Authentication errors](/predictions/authentication#authentication-errors). On `POST /trading/orders` a `401` is refused before the order is accepted, so the same `request_id` can be sent again once the signature is fixed. content: application/json: schema: $ref: '#/components/schemas/TradingError' examples: Invalid signature: summary: Invalid signature value: status: error error: NOT_AUTHORIZED message: Invalid signature description: >- The signature does not match what Splash computed. Check that you signed the exact body bytes and the full path including `/predictions-service/api` and the query string. Timestamp outside the allowed window: summary: Timestamp outside the allowed window value: status: error error: NOT_AUTHORIZED message: Timestamp outside the allowed window description: >- `SPLASH-ACCESS-TIMESTAMP` is more than 30 seconds from server time. Check your clock. Unknown API key: summary: Unknown API key value: status: error error: NOT_AUTHORIZED message: Unknown API key API key revoked: summary: API key revoked value: status: error error: NOT_AUTHORIZED message: API key revoked Missing or misspelled key header: summary: Missing or misspelled key header value: status: error error: NOT_AUTHORIZED message: You are not authorized to perform the requested action. description: >- The request carried no `SPLASH-ACCESS-KEY` header, because it was not signed or the header name is misspelled. A request without the `SPLASH-ACCESS-KEY` header is not an API request and is refused. Send all three `SPLASH-ACCESS-*` headers. '403': description: >- `FOBIDDEN` (spelled that way on the wire): `Not authorized to trade`, the account is not approved to trade or is blocked. The order was not placed and the `request_id` is spent. content: application/json: schema: $ref: '#/components/schemas/TradingError' examples: Account may not trade: summary: Account may not trade value: status: error error: FOBIDDEN message: Not authorized to trade description: >- `FOBIDDEN` is the literal code the API returns; match it exactly. '404': description: >- `market_id` names no market. The order was not placed and the `request_id` is spent; send the corrected order with a new one. content: application/json: schema: $ref: '#/components/schemas/TradingError' examples: Unknown market: summary: Unknown market value: status: error error: NOT_FOUND message: Market not found '409': description: >- `request_id` is already in use by another account's order. Nothing was placed for you, and polling that `request_id` returns nothing. Send the order again with a new `request_id`. content: application/json: schema: $ref: '#/components/schemas/TradingError' examples: request_id used by another account: summary: request_id used by another account value: status: error error: DUPLICATE_REQUEST_ID message: request_id is already in use description: Generate a fresh random `request_id`. '415': $ref: '#/components/responses/UnsupportedMediaType' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' '503': description: >- The order could not be taken right now. `TRADING_API_UNAVAILABLE` means the Trading API is not taking signed requests: it is refused before the order is accepted, so retry later with the same `request_id`. `EXCHANGE_UNAVAILABLE` (the exchange is unavailable) and `SERVICE_UNAVAILABLE` (an eligibility check could not run) come after the `request_id` was taken: the order was not placed, the `request_id` is spent, and a retry later needs a new one. See [Order outcomes and retries](/predictions/trading#order-outcomes-and-retries). content: application/json: schema: $ref: '#/components/schemas/TradingError' examples: Exchange unavailable: summary: Exchange unavailable value: status: error error: EXCHANGE_UNAVAILABLE message: Exchange unavailable description: >- The exchange cannot take orders right now. The `request_id` is spent: polling it reads `cancelled`. Retry later with a new `request_id`. Order checks could not run: summary: Order checks could not run value: status: error error: SERVICE_UNAVAILABLE message: Unable to place this order right now. Please try again. description: >- An eligibility check Splash runs on every buy could not complete, so the order was refused rather than let through. The `request_id` is spent; retry later with a new one. Trading API unavailable: summary: Trading API unavailable value: status: error error: TRADING_API_UNAVAILABLE message: The trading API is not available. description: >- Refused before the order was accepted; nothing was recorded. Retry later with the same `request_id`. security: - SplashAccessKey: [] SplashAccessTimestamp: [] SplashAccessSignature: [] x-codeSamples: - lang: bash label: cURL source: >- KEY="your-key-id" SECRET="your-secret" METHOD="POST" URLPATH="/predictions-service/api/trading/orders" BODY='{"market_id":"pm_6ae1e3c09e1d4c7a2b5f80e3d6a9c412","side":"yes","quantity":10,"price":0.59,"time_in_force":"FOK","request_id":"3f1c2a9e-5b7d-4e0a-9c1d-8a6b2e4f7d10"}' TS=$(( $(date +%s) * 1000 )) SIG=$(printf '%s' "$TS$METHOD$URLPATH$BODY" | openssl dgst -sha256 -hmac "$SECRET" -binary | base64) curl -X "$METHOD" "https://api.splashsports.com$URLPATH" \ -H "Content-Type: application/json" \ -H "SPLASH-ACCESS-KEY: $KEY" \ -H "SPLASH-ACCESS-TIMESTAMP: $TS" \ -H "SPLASH-ACCESS-SIGNATURE: $SIG" \ --data-binary "$BODY" - lang: python label: Python source: |- import base64, hashlib, hmac, json, time import requests KEY = "your-key-id" SECRET = "your-secret" HOST = "https://api.splashsports.com" def sign(secret, timestamp, method, path, body): message = (timestamp + method + path + body).encode("utf-8") digest = hmac.new(secret.encode("utf-8"), message, hashlib.sha256).digest() return base64.b64encode(digest).decode("ascii") def request(method, path, payload=None): body = json.dumps(payload, separators=(",", ":")) if payload is not None else "" timestamp = str(int(time.time() * 1000)) headers = { "Content-Type": "application/json", "SPLASH-ACCESS-KEY": KEY, "SPLASH-ACCESS-TIMESTAMP": timestamp, "SPLASH-ACCESS-SIGNATURE": sign(SECRET, timestamp, method, path, body), } return requests.request(method, HOST + path, headers=headers, data=body.encode("utf-8")) response = request( "POST", "/predictions-service/api/trading/orders", { "market_id": "pm_6ae1e3c09e1d4c7a2b5f80e3d6a9c412", "side": "yes", "quantity": 10, "price": 0.59, "time_in_force": "FOK", "request_id": "3f1c2a9e-5b7d-4e0a-9c1d-8a6b2e4f7d10", }, ) print(response.status_code, response.json()) - lang: typescript label: TypeScript source: >- import { createHmac } from "node:crypto"; const KEY = "your-key-id"; const SECRET = "your-secret"; const HOST = "https://api.splashsports.com"; function sign(secret: string, timestamp: string, method: string, path: string, body: string): string { return createHmac("sha256", secret).update(timestamp + method + path + body, "utf8").digest("base64"); } const method = "POST"; const path = "/predictions-service/api/trading/orders"; // Serialize once, sign that exact string, and send that exact string. const body = JSON.stringify({ market_id: "pm_6ae1e3c09e1d4c7a2b5f80e3d6a9c412", side: "yes", quantity: 10, price: 0.59, time_in_force: "FOK", request_id: "3f1c2a9e-5b7d-4e0a-9c1d-8a6b2e4f7d10", }); const timestamp = Date.now().toString(); const response = await fetch(HOST + path, { method, headers: { "Content-Type": "application/json", "SPLASH-ACCESS-KEY": KEY, "SPLASH-ACCESS-TIMESTAMP": timestamp, "SPLASH-ACCESS-SIGNATURE": sign(SECRET, timestamp, method, path, body), }, body, }); console.log(response.status, await response.json()); - lang: go label: Go source: "package main\n\nimport (\n\t\"bytes\"\n\t\"crypto/hmac\"\n\t\"crypto/sha256\"\n\t\"encoding/base64\"\n\t\"encoding/json\"\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"strconv\"\n\t\"time\"\n)\n\nconst (\n\tkey = \"your-key-id\"\n\tsecret = \"your-secret\"\n\thost = \"https://api.splashsports.com\"\n)\n\nfunc sign(secret, timestamp, method, path string, body []byte) string {\n\tmac := hmac.New(sha256.New, []byte(secret))\n\tmac.Write([]byte(timestamp + method + path))\n\tmac.Write(body)\n\treturn base64.StdEncoding.EncodeToString(mac.Sum(nil))\n}\n\nfunc main() {\n\tmethod := \"POST\"\n\tpath := \"/predictions-service/api/trading/orders\"\n\n\t// Marshal once, sign those exact bytes, and send those exact bytes.\n\tbody, err := json.Marshal(map[string]any{\n\t\t\"market_id\": \"pm_6ae1e3c09e1d4c7a2b5f80e3d6a9c412\",\n\t\t\"side\": \"yes\",\n\t\t\"quantity\": 10,\n\t\t\"price\": 0.59,\n\t\t\"time_in_force\": \"FOK\",\n\t\t\"request_id\": \"3f1c2a9e-5b7d-4e0a-9c1d-8a6b2e4f7d10\",\n\t})\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\ttimestamp := strconv.FormatInt(time.Now().UnixMilli(), 10)\n\n\treq, err := http.NewRequest(method, host+path, bytes.NewReader(body))\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\treq.Header.Set(\"SPLASH-ACCESS-KEY\", key)\n\treq.Header.Set(\"SPLASH-ACCESS-TIMESTAMP\", timestamp)\n\treq.Header.Set(\"SPLASH-ACCESS-SIGNATURE\", sign(secret, timestamp, method, path, body))\n\n\tresp, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer resp.Body.Close()\n\tout, _ := io.ReadAll(resp.Body)\n\tfmt.Println(resp.StatusCode, string(out))\n}" components: schemas: PlaceOrderRequest: type: object title: PlaceOrderRequest required: - market_id - side - quantity - price - time_in_force - request_id properties: market_id: type: string description: >- The market to trade: a market `id` from the market endpoints, including an `alternate_lines[].id`. An unknown id is `404 Market not found`; a market that is not `active` is `400 Market is not active`. example: pm_6ae1e3c09e1d4c7a2b5f80e3d6a9c412 side: $ref: '#/components/schemas/OrderSide' description: >- `yes` buys YES contracts and `no` buys NO contracts. The same field closes a position: holding YES, an order for `no` sells your YES contracts, and holding NO, an order for `yes` sells your NO contracts. A close must be for exactly the contracts you hold; a partial close or a flip to the other side is a `400`. See [Order sides](/predictions/enums#order-sides-splash_side-and-side). example: 'yes' quantity: type: integer minimum: 1 description: >- Whole contracts, at least 1. A contract pays $1 if its side wins. Opening more than the maximum trade in dollars is a `400`; closing is never limited. example: 10 price: type: number minimum: 0.01 maximum: 0.99 description: >- Your limit in dollars per contract for the side named in `side`, 0.01 to 0.99. A `no` order is priced in NO terms, so to sell 10 YES contracts at $0.66 you send `side: "no"`, `price: 0.34`. The order fills completely at this price or better, or not at all. Fees are added on top of a buy and taken from a sale, not included in the price; see [Fees and order cost](/predictions/fees). A sub-cent price is rounded to the cent in your favour before it reaches the exchange. example: 0.59 time_in_force: type: string enum: - FOK description: >- Only `FOK` (fill or kill) is accepted. `IOC` is refused with `400 IOC orders are not yet supported`. See [Time in force](/predictions/enums#time-in-force-time_in_force). example: FOK request_id: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z0-9_-]+$ description: >- Your idempotency key: 1 to 64 characters from `A-Z a-z 0-9 _ -`; a UUID is ideal. One `request_id` never places more than one order: sending it again returns the order it already names, with its current status. After no response, poll it before sending it again; after an order-check refusal it is spent and you need a new one. A value another account used is `409 DUPLICATE_REQUEST_ID`. See [Order outcomes and retries](/predictions/trading#order-outcomes-and-retries). example: 3f1c2a9e-5b7d-4e0a-9c1d-8a6b2e4f7d10 description: >- A fill-or-kill order on one market. See [Placing an order](/predictions/trading#placing-an-order-and-following-it). example: market_id: pm_6ae1e3c09e1d4c7a2b5f80e3d6a9c412 side: 'yes' quantity: 10 price: 0.59 time_in_force: FOK request_id: 3f1c2a9e-5b7d-4e0a-9c1d-8a6b2e4f7d10 PlaceOrderResponse: type: object title: PlaceOrderResponse required: - status - order_id - request_id - order_status properties: status: type: string const: success description: Always `success` on a 200. example: success order_id: type: string description: >- The order id (prefix `ord_`). Read the order with `GET /orders/{id}` or poll `GET /orders?request_id=`. A replay returns the original order's id. example: ord_6aedec658f3a61c2d94e07b5a1c6e2d9 request_id: type: string description: The `request_id` you sent. example: 3f1c2a9e-5b7d-4e0a-9c1d-8a6b2e4f7d10 order_status: type: string enum: - pending - executed - cancelled description: >- `pending` on a new order: accepted, not filled. A `request_id` you already used reports that order's current status, and `cancelled` when the original request was refused (that `request_id` is spent). See [Order statuses](/predictions/enums#order-statuses-status-on-an-order). example: pending description: >- The order was accepted. Poll it until `status` is `executed` or `cancelled`. example: status: success order_id: ord_6aedec658f3a61c2d94e07b5a1c6e2d9 request_id: 3f1c2a9e-5b7d-4e0a-9c1d-8a6b2e4f7d10 order_status: pending TradingError: type: object title: TradingError description: >- The error body of the signed order and position routes. Same shape as the public `Error`, with the codes those routes can return. Branch on `error`; `message` is for people. See [Errors](/predictions/trading#errors). required: - status - error - message properties: status: type: string const: error description: Always `error` on an error response. example: error error: type: string description: >- Machine-readable code; branch on this. A string: the values below are the ones these routes return today, and a code not listed here should be handled by its HTTP status. See [Trading error codes](/predictions/enums#trading-error-codes-error). - `BAD_REQUEST` (400): invalid body or query, or an order check failed. - `NOT_AUTHORIZED` (401): the signature check failed, the request had no `SPLASH-ACCESS-KEY` header, or `user_id` was passed to `GET /orders`, `GET /orders/{id}`, `GET /positions`, `GET /positions/{id}` or `GET /transactions`. - `FOBIDDEN` (403): `Not authorized to trade`, the account may not trade. `FOBIDDEN` is the literal value the API returns (not `FORBIDDEN`); match it exactly. - `NOT_FOUND` (404): no such order, position or market on your account. - `DUPLICATE_REQUEST_ID` (409): another account used this `request_id`. - `UNSUPPORTED_MEDIA_TYPE` (415): a signed body that is not JSON. - `INTERNAL_ERROR` (500): the request could not be handled. On `POST /trading/orders` the order was not placed; poll the `request_id`, then try again with a new one. - `TRADING_API_UNAVAILABLE` (503): the Trading API is not taking signed requests; retry later. - `EXCHANGE_UNAVAILABLE`, `SERVICE_UNAVAILABLE` (503): the order could not be placed right now; retry later with a new `request_id`. On `GET /balance`, `SERVICE_UNAVAILABLE` means your balance could not be read; retry shortly. A `429 Too Many Requests` is the rate limit, not one of these codes; see [Rate limits](/predictions/rate-limits). Whether an order's `request_id` can be reused after an error: see [Order outcomes and retries](/predictions/trading#order-outcomes-and-retries). example: FOBIDDEN message: type: string description: >- Human-readable detail. For `BAD_REQUEST` and `NOT_AUTHORIZED` it names the cause, e.g. `Invalid price` or `Invalid signature`. Do not branch on it. example: Not authorized to trade example: status: error error: FOBIDDEN message: Not authorized to trade OrderSide: type: string enum: - 'yes' - 'no' title: OrderSide description: >- Which side of a market's question. See [Order sides](/predictions/enums#order-sides-splash_side-and-side). example: 'yes' TooManyRequestsError: type: object title: TooManyRequestsError description: >- The body of a `429 Too Many Requests`: more than 10 requests per second from your IP address. It is not a `TradingError`; branch on the `429` status. See [Rate limits](/predictions/rate-limits). required: - status - error - message properties: status: type: string const: error description: Always `error`. example: error error: type: string const: TOO_MANY_REQUESTS description: Always `TOO_MANY_REQUESTS` on a rate-limited request. example: TOO_MANY_REQUESTS message: type: string description: Human-readable detail. Do not branch on it. example: Too many requests, try again later example: status: error error: TOO_MANY_REQUESTS message: Too many requests, try again later Error: type: object required: - status - error - message properties: status: type: string const: error description: Always `error` on an error response. example: error error: type: string enum: - BAD_REQUEST - NOT_FOUND - INTERNAL_ERROR description: >- Machine-readable code; branch on this. `BAD_REQUEST` (400), `NOT_FOUND` (404) or `INTERNAL_ERROR` (500). See [Error codes](/predictions/enums#error-codes-error). example: BAD_REQUEST message: type: string description: >- Human-readable detail for logs and people. Wording can change; do not branch on it. example: Invalid request parameters title: Error example: status: error error: BAD_REQUEST message: Invalid request parameters responses: UnsupportedMediaType: description: >- A signed request carried a body that is not JSON. Send `Content-Type: application/json`. content: application/json: schema: $ref: '#/components/schemas/TradingError' examples: Body is not JSON: summary: Body is not JSON value: status: error error: UNSUPPORTED_MEDIA_TYPE message: Signed requests must send a JSON body description: >- Send the body as `application/json`. A form-encoded body is refused because the signature could not cover it. RateLimited: description: >- Too Many Requests: more than 10 requests per second from your IP address. The request was not handled and nothing was recorded. If the response has a `Retry-After` header, wait that many seconds; otherwise back off (about 1 second, with jitter). Then send the same request again; on `POST /trading/orders` reuse the same `request_id`. See [Rate limits](/predictions/rate-limits). headers: Retry-After: description: >- Optional, and may be absent. When present, the number of seconds to wait before retrying; when absent, back off about 1 second with jitter. required: false schema: type: integer example: 1 content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsError' examples: Over the limit: summary: Over the limit value: status: error error: TOO_MANY_REQUESTS message: Too many requests, try again later description: >- More than 10 requests per second from your IP address. Nothing was recorded; wait about a second (or the `Retry-After` seconds when that header is present) and send the same request again. InternalError: description: >- The request could not be handled. On `POST /trading/orders` the order was not placed: poll `GET /orders?request_id=` before trying again. If the poll returns the order, follow it; otherwise send the order again with a new `request_id`, because this one now reads `cancelled`. See [Order outcomes and retries](/predictions/trading#order-outcomes-and-retries). content: application/json: schema: $ref: '#/components/schemas/Error' examples: The request could not be handled: summary: The request could not be handled value: status: error error: INTERNAL_ERROR message: >- An internal error has occured and the request could not be handled. description: >- The message is spelled `occured` on the wire. On `POST /trading/orders`, poll the `request_id` before trying again, then send the order with a new `request_id`. securitySchemes: SplashAccessKey: type: apiKey in: header name: SPLASH-ACCESS-KEY description: >- Your API key id. Keys are issued by Splash on request, never expire, and stay valid until Splash revokes them, which it does on request. See [Authentication](/predictions/authentication). SplashAccessTimestamp: type: apiKey in: header name: SPLASH-ACCESS-TIMESTAMP description: Unix milliseconds, within 30 seconds of server time. SplashAccessSignature: type: apiKey in: header name: SPLASH-ACCESS-SIGNATURE description: >- `base64(HMAC-SHA256(secret, timestamp + METHOD + path + body))`. See [Authentication](/predictions/authentication). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.