> ## Documentation Index > Fetch the complete documentation index at: https://finance.dev/llms.txt > Use this file to discover all available pages before exploring further. # Place Prediction Order > Places a prediction-market order for the authenticated user and returns as soon as the order is on its way to the venue. **Use Case:** Buy or sell YES or NO contracts on a prediction-market event. This endpoint is in **closed beta**. It is available only to accounts enrolled in the beta, and only on staging (`https://api.tradearies.dev`). 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](/api-reference/predictions/get-order) using the returned `orderId`. A `202` means the order was sent. It does not mean the order was accepted by the venue. ## Request ```json theme={null} { "accountId": "ACCOUNT-0001", "clientOrderRef": "7d1c8e0a-4b8f-4e3a-9f43-2a6b1d0c9e11", "symbol": "HORC_1126_Republican", "outcome": "YES", "side": "buy", "orderType": "limit", "timeInForce": "day", "quantity": "10", "price": "0.54" } ``` * `symbol` is a contract symbol from [search](/api-reference/predictions/search) or [Get Event Contracts](/api-reference/predictions/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**. * Unknown fields are rejected with `400` `UNKNOWN_FIELD`. Which price fields are required depends on `orderType` and `timeInForce`: | Field | Required when | | - | - | | `price` | `orderType` is `limit` or `stop_limit` | | `stopPx` | `orderType` is `stop` or `stop_limit` | | `expireTime` | `timeInForce` is `gtd` | ## Retry safely with `clientOrderRef` `clientOrderRef` is an idempotency key scoped to the account. A retry with the same value returns the order already placed instead of placing a second one. Reusing a value for a *different* order on the same account returns `409` `CLIENT_ORDER_REF_IN_USE`. Send a `clientOrderRef` on every order. Without one, you cannot safely retry after a `504`. ### 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: * look for the order in [List Prediction Orders](/api-reference/predictions/list-orders), or * retry with the **same** `clientOrderRef`. Never retry a `504` without a `clientOrderRef`. Doing so can place the order twice. ## Example ```bash theme={null} curl -X POST "https://api.tradearies.dev/v1/predictions/orders" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"accountId":"ACCOUNT-0001","clientOrderRef":"7d1c8e0a-4b8f-4e3a-9f43-2a6b1d0c9e11","symbol":"HORC_1126_Republican","outcome":"YES","side":"buy","orderType":"limit","timeInForce":"day","quantity":"10","price":"0.54"}' ``` ## Errors | Status | `code` | Meaning | | - | - | - | | `400` | `INVALID_ORDER` | The order was refused. `message` carries the reason, including refusals from order entry or the venue such as price, tick size, or account setup. | | `400` | `EMPTY_BODY`, `INVALID_JSON`, `UNKNOWN_FIELD` | Missing body, malformed JSON, or a field the endpoint does not accept. | | `401` | — | Missing or invalid credentials. | | `409` | `CLIENT_ORDER_REF_IN_USE` | `clientOrderRef` is already used on this account by another order. | | `429` | `ORDER_ENTRY_AT_CAPACITY` | Order entry is at capacity. Nothing was placed; retry shortly. | | `503` | `ORDER_ENTRY_UNAVAILABLE` | Order entry is not accepting orders. Nothing was placed. | | `504` | `ORDER_OUTCOME_UNKNOWN` | The order may have been placed. See [above](#handling-504-order_outcome_unknown). | ## OpenAPI ````yaml openapi.json POST /v1/predictions/orders openapi: 3.0.3 info: contact: email: dev@aries.com name: Aries Financial description: >- OpenAPI Specification for the Aries trading platform API. # Authentication Learn how to authenticate with the Aries API using OAuth2 and manage access tokens in your SDK. ## Overview The Aries API uses **OAuth2 with Bearer tokens** (JWT format) for authentication. All API requests require a valid access token in the `Authorization` header: ``` Authorization: Bearer ``` ## Providing Client ID and Client Secret (SDK) When using the generated SDK, provide your **Client ID** and **Client Secret** when you create the API client (e.g. in the constructor or security options). The SDK will use these to obtain and refresh the access token internally; you do not need to manage tokens yourself. Obtain your OAuth2 credentials from the Aries platform (e.g. Client Center / Manage Account at https://app.aries.com): - **Client ID** – Your application identifier (pass to SDK client) - **Client Secret** – Your application secret key (pass to SDK client; use PKCE for public clients where secret cannot be stored) ## Authentication Flow ### 1. Authorization Code Flow For server-side or confidential clients: 1. **Redirect the user** to the authorization URL to sign in and consent: - **URL:** `https://app.aries.com/oauth2/authorize` - **Query params:** `response_type=code`, `client_id`, `redirect_uri`, `scope`, `state` 2. **Exchange the code for tokens** (after user is redirected back with `?code=.`): - **POST** `https://api.aries.com/v1/oauth2/token` - **Body:** `grant_type=authorization_code`, `code`, `redirect_uri`, `client_id`, `client_secret` - Response includes `access_token` and `refresh_token` 3. **Call the API** with the access token: `Authorization: Bearer ` ### 2. PKCE Flow For SPAs and mobile apps (public clients that cannot store `client_secret`): 1. Generate a **code_verifier** (random string) and **code_challenge** = BASE64URL(SHA256(code_verifier)). 2. **Redirect the user** to `https://app.aries.com/oauth2/authorize` with `code_challenge`, `code_challenge_method=S256`, plus `client_id`, `redirect_uri`, `scope`, `state`. 3. **Exchange the code** at POST `https://api.aries.com/v1/oauth2/token` with `grant_type=authorization_code`, `code`, `redirect_uri`, `client_id`, `code_verifier` (no client_secret). 4. Use the returned `access_token` as Bearer. ### 3. MFA Verification If the user has MFA enabled, the authorize step may return `is_mfa: true` and a `next_step_auth_id`. Call **POST** `https://api.aries.com/v1/oauth2/authorize/mfa` with `next_step_auth_id` and `verification_code` (6-digit code). Then continue with **POST** `/v1/oauth2/authorize/confirm` to get the authorization code, and exchange it at `/v1/oauth2/token`. ## Token Management - **Refresh when expired:** POST `https://api.aries.com/v1/oauth2/token` with `grant_type=refresh_token`, `client_id`, `client_secret`, `refresh_token`. - **Using a Bearer token directly:** If you already have an access token, set the header `Authorization: Bearer ` on every request. The SDK can accept a pre-obtained token and use it until it expires. ## OAuth2 Scopes Request only the scopes your application needs. Available scopes: | Scope | Description | |-------|-------------| | `user:information` | View user profile and personal details | | `watchlist:information` | View your watchlists and their symbols | | `watchlist:management` | Create, update, replace, and delete your watchlists | | `account:information` | View account balances, positions, and transaction history | | `order:execution` | Place, modify, and cancel orders | | `order:information` | View order history and status | | `position:information` | View current positions and holdings | | `market:information` | Access live and historical market data | | `calendar:information` | Access earnings, economic, and market schedule data | | `options:information` | Access options chains and expiration data | | `analytics:information` | View analytics, ratings, and market insights | | `market:supplemental` | News, company profiles, financials, filings, ETF data, technical analysis | Specify multiple scopes as a space-separated string, e.g. `account:information order:execution market:information`. ## Security Best Practices - **Store credentials securely** – Use environment variables or a secrets manager for `client_id` and `client_secret`. Never hardcode them. - **Handle token expiration** – Check for 401 responses and refresh the token using the refresh_token, then retry the request. - **Use HTTPS** – All authorization and token endpoints must be called over HTTPS. - **Validate state** – When using the authorization code flow, validate the `state` parameter on the callback to prevent CSRF. ## Error Handling - **400 Bad Request** – Invalid or missing parameters, validation failures, or malformed JSON. Response bodies follow the same patterns as other errors (flat `error` string, optional `codes`, nested `error` object, or rarely no body). - **401 Unauthorized** – Invalid or expired access token; refresh the token or re-authenticate. JSON bodies are not identical on every route: you may see a flat `error` string (sometimes with `codes`), a nested `error` object (`type`, `code`, `message`), or rarely an empty body - **403 Forbidden** – Insufficient scope or permissions for the requested resource. Error JSON may be flat or nested, like 400/401. - **404 Not Found** – Resource does not exist or is not visible. Error JSON may be flat or nested. - **500 / 5xx** – Server or upstream failure; retry with backoff. Do not depend on a single error JSON shape; some responses may have no body. --- Endpoints in this spec: health, OAuth2 (authorize, confirm, mfa, token), users, accounts, orders, market data, watchlist, chart, analytics, calendars, company, economy, financials, indices, options, news, and supplemental data. title: Aries API — OpenAPI Specification version: 1.0.0 servers: - description: Production url: https://api.aries.com - description: Staging url: https://api.tradearies.dev security: [] tags: - description: Account management endpoints for positions, orders, and balances name: Accounts - description: >- Analytics endpoints for market data analysis including top gainers, losers, volume leaders, sector analysis, analyst ratings, market breadth, and net inflow name: Analytics - description: Calendar and mergers/acquisitions endpoints name: Calendar - description: Chart endpoints for config, symbols, history, quotes, and server time name: Chart - name: Company - description: 'Corporate actions: spinoffs, tender offers, IPO calendar, dividends' name: Corporate Actions - name: ETF - description: 'Economy endpoints: inflation, inflation expectations, treasury yields' name: Economy - name: Filings - description: >- Financials: reported, statements, revenue breakdown, short volume, ratios, short interest name: Financials - description: >- Indices endpoints for groups, list, search, bar, bars, chart-bars, realtime values name: Indices - description: Logos search and sync endpoints name: Logos - name: Market - description: >- Market data endpoints for symbol search, real-time data access, and equity details name: Market Data - description: News and news sentiment endpoints name: News - description: >- Options endpoints: expiry dates, contracts, activity, trades, quotes, unusual activity name: Options - description: >- Order management endpoints for placing, updating, canceling, and previewing orders name: Orders - name: Ownership - description: Signals and bull-bear cases name: Signals - description: >- Transcripts, company presentation, social sentiment, investment themes, supply chain, and ESG data name: Stock Alternative - name: Stock Estimates - name: Stocks - name: Technical Analysis - description: >- Watchlist endpoints for listing, creating, updating, and deleting watchlists name: Watchlist - description: Historical YES/NO tick data for prediction-market contracts name: Prediction Historical Data - description: >- Prediction-market reference data and full-text search over base events, events, and contracts name: Prediction Market Data - description: >- Closed beta. Place prediction-market orders and read back the authenticated user's order history. name: Prediction Orders paths: /v1/predictions/orders: post: tags: - Prediction Orders summary: Place prediction order description: >- **Closed beta.** Available only to accounts enrolled in the prediction-market orders closed beta. Places a prediction-market order for the authenticated user. Returns `202` as soon as the order is on its way to the venue, normally in state `pending_new`. Read the venue's answer back with Get Prediction Order. operationId: placePredictionOrder requestBody: content: application/json: example: accountId: ACCOUNT-0001 clientOrderRef: 7d1c8e0a-4b8f-4e3a-9f43-2a6b1d0c9e11 orderType: limit outcome: 'YES' price: '0.54' quantity: '10' side: buy symbol: HORC_1126_Republican timeInForce: day schema: $ref: '#/components/schemas/PredOrdersPlaceOrderRequest' required: true responses: '202': content: application/json: schema: allOf: - $ref: '#/components/schemas/PredMdSuccessEnvelope' - properties: data: $ref: '#/components/schemas/PredOrdersOrder' type: object description: Order accepted for sending. `state` is normally `pending_new`. '400': $ref: '#/components/responses/PredOrdersBadRequest' '401': $ref: '#/components/responses/Unauthorized' '409': content: application/json: example: error: code: CLIENT_ORDER_REF_IN_USE message: clientOrderRef is already used on this account type: conflict success: false schema: $ref: '#/components/schemas/PredOrdersErrorEnvelope' description: >- `clientOrderRef` is already used on this account by a different order. '429': content: application/json: example: error: code: ORDER_ENTRY_AT_CAPACITY message: order entry is at capacity; retry shortly type: rate_limit success: false schema: $ref: '#/components/schemas/PredOrdersErrorEnvelope' description: Order entry is at capacity. Nothing was placed; retry shortly. '500': $ref: '#/components/responses/PredOrdersInternalServerError' '503': content: application/json: example: error: code: ORDER_ENTRY_UNAVAILABLE message: order entry is not accepting orders right now type: unavailable success: false schema: $ref: '#/components/schemas/PredOrdersErrorEnvelope' description: >- Order entry is not accepting orders (venue session down or disabled). Nothing was placed. '504': content: application/json: example: error: code: ORDER_OUTCOME_UNKNOWN message: >- the order may have been placed; check order history, or retry with the same clientOrderRef type: timeout success: false schema: $ref: '#/components/schemas/PredOrdersErrorEnvelope' description: >- The call was cut short and the order may have been placed. Check order history, or retry with the same `clientOrderRef` — never without it. security: - OAuth2: [] servers: - description: Staging url: https://api.tradearies.dev components: schemas: PredOrdersPlaceOrderRequest: additionalProperties: false description: >- Unknown fields are rejected with `400`. The user is always the authenticated caller and cannot be named in the body. properties: accountId: description: The account to place the order on. example: ACCOUNT-0001 type: string clientOrderRef: description: >- Idempotency key. A retry with the same value on the same account returns the order already placed instead of placing a second. Send one on every order so a `504` can be retried safely. example: 7d1c8e0a-4b8f-4e3a-9f43-2a6b1d0c9e11 type: string expireTime: description: Required when `timeInForce` is `gtd`. format: date-time type: string orderType: enum: - limit - stop - stop_limit - market_to_limit example: limit type: string outcome: description: >- The binary outcome the order trades. It is never inferred from `side`. enum: - 'YES' - 'NO' example: 'YES' type: string price: description: >- Limit price as an exact decimal string. Required for `limit` and `stop_limit`. example: '0.54' type: string quantity: description: >- Number of contracts as an exact decimal string. Must be greater than zero. example: '10' type: string side: enum: - buy - sell example: buy type: string stopPx: description: >- Stop price as an exact decimal string. Required for `stop` and `stop_limit`. example: '0.50' type: string symbol: description: >- Prediction-market contract symbol, as returned by search or Get Event Contracts. example: HORC_1126_Republican type: string timeInForce: enum: - day - gtc - ioc - fok - gtd example: day type: string required: - accountId - symbol - outcome - side - orderType - timeInForce - quantity type: object PredMdSuccessEnvelope: description: >- Standard success envelope used by all success responses. `data` is endpoint-specific. properties: data: {} success: example: true type: boolean required: - success type: object PredOrdersOrder: description: >- 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. properties: accountId: example: ACCOUNT-0001 type: string avgPx: description: Average fill price. Exact decimal as a string. example: '0' type: string certainty: description: >- How sure order entry is of `state`. Anything other than `certain` means the order's state could not be confirmed; `certaintyReason` says why. enum: - certain - unknown_unacked - unknown_gap - unknown_store_lost type: string certaintyReason: type: string clOrdId: description: Client order ID sent to the venue. type: string clientOrderRef: example: 7d1c8e0a-4b8f-4e3a-9f43-2a6b1d0c9e11 type: string closedAt: format: date-time type: string createdAt: format: date-time type: string cumQty: description: Quantity filled so far. Exact decimal as a string. example: '0' type: string expireTime: format: date-time type: string firstAckAt: description: When the venue first acknowledged the order. format: date-time type: string leavesQty: description: Quantity still working. Exact decimal as a string. example: '10' type: string orderId: example: 0b9f3c2e-5d6a-4f1b-8e7c-9a0d1e2f3a4b format: uuid type: string orderType: example: limit type: string outcome: enum: - 'YES' - 'NO' example: 'YES' type: string pendingAction: enum: - none - replace - cancel type: string price: description: Exact decimal as a string. example: '0.54' type: string quantity: description: Exact decimal as a string. example: '10' type: string rejectReason: type: string rejectText: description: >- The venue's own rejection text. Most rejections carry their useful detail only here. type: string sentAt: format: date-time type: string side: example: buy type: string state: description: >- Order lifecycle state. `unknown` means order entry lost track of the order and says so rather than guessing; see `certainty`. enum: - pending_new - new - partially_filled - filled - canceled - rejected - expired - done_for_day - unknown example: pending_new type: string stopPx: description: Exact decimal as a string. example: '0.50' type: string symbol: example: HORC_1126_Republican type: string timeInForce: example: day type: string updatedAt: format: date-time type: string venueOrderId: description: Assigned by the venue on acknowledgement. type: string workingOrderType: type: string workingPrice: description: Exact decimal as a string. example: '0.54' type: string workingQuantity: description: Exact decimal as a string. example: '10' type: string required: - orderId - accountId - symbol - outcome - side - orderType - timeInForce - quantity - workingQuantity - state - cumQty - leavesQty - avgPx - createdAt - updatedAt type: object PredOrdersErrorEnvelope: properties: error: $ref: '#/components/schemas/PredOrdersAppError' success: example: false type: boolean required: - success - error type: object ErrorResponse: properties: codes: description: Structured error codes for programmatic handling items: $ref: '#/components/schemas/ErrorCode' type: array error: description: >- Error detail as a string. Exact message content is not fixed and should not be hard-coded. example: string type: string metadata: additionalProperties: true description: Additional error context type: object type: object AuthenticationErrorEnvelope: description: >- JSON envelope where `error` is a nested object (`type`, `code`, `message`, …). Many services use this shape for 400, 401, 403, 404, and 5xx when using the shared HTTP error format. properties: error: $ref: '#/components/schemas/AuthenticationErrorDetail' meta: additionalProperties: true description: Optional metadata type: object type: object PredOrdersAppError: description: Structured error returned by the prediction-market order endpoints. properties: code: description: >- Machine-readable code, e.g. `INVALID_ORDER`, `ORDER_OUTCOME_UNKNOWN`. Branch on this. example: INVALID_ORDER type: string details: additionalProperties: true type: object message: description: >- Human-readable detail. Exact text is not fixed and should not be matched on. example: string type: string request_id: type: string type: description: Categorical error type, in lowercase. enum: - bad_request - authentication - not_found - conflict - rate_limit - unavailable - timeout - internal example: bad_request type: string required: - type - code - message type: object ErrorCode: properties: code: description: Machine-readable error code example: INVALID_PASSWORD type: string description: description: Human-readable description of the error example: Password must be between 8 and 64 characters type: string field: description: Field name that caused the error example: password type: string type: object AuthenticationErrorDetail: description: >- Structured payload for the nested `error` object. Services using the shared Go error writer emit uppercase `type` values aligned with error categories (for example `VALIDATION`, `BAD_REQUEST`, `AUTHENTICATION`, `AUTHORIZATION`, `NOT_FOUND`, `RATE_LIMIT`, `INTERNAL`). properties: code: description: Machine-readable code example: INVALID_TOKEN type: string details: additionalProperties: true description: Optional extra context type: object message: description: >- Error detail as a string. Exact message content is not fixed and should not be hard-coded. example: string type: string request_id: description: Request correlation id when provided type: string type: description: >- Error category emitted by the shared error writer, such as VALIDATION, BAD_REQUEST, AUTHENTICATION, AUTHORIZATION, NOT_FOUND, RATE_LIMIT, or INTERNAL. example: AUTHENTICATION type: string type: object responses: PredOrdersBadRequest: content: application/json: example: error: code: INVALID_ORDER message: string type: bad_request success: false schema: $ref: '#/components/schemas/PredOrdersErrorEnvelope' description: >- Invalid request. `INVALID_ORDER` carries the reason in `message`; on placement this includes refusals from order entry and the venue (price, tick size, account setup). Unauthorized: content: application/json: examples: flat_message: summary: Flat error string (typical) value: error: string flat_with_codes: summary: Flat error with structured codes value: codes: - code: string description: string error: string nested_error_object: summary: Nested error (shared HTTP error format) value: error: code: INVALID_TOKEN message: string type: AUTHENTICATION schema: description: >- 401 responses may use a flat `ErrorResponse` shape or a nested `error` object. Inspect `error`: if it is a string, use the flat shape; if it is an object, use the structured shape. oneOf: - $ref: '#/components/schemas/ErrorResponse' - $ref: '#/components/schemas/AuthenticationErrorEnvelope' description: >- Authentication failed: missing credentials, invalid JWT, or expired access token. **Response body variants:** Some routes return JSON with a string `error` field (and optionally `codes` / `metadata`). Others return JSON where `error` is a structured object (`type`, `code`, `message`, and optionally `details`, `request_id`). In edge cases (for example certain gateway or middleware paths) the response may have **no body** even though the status is 401—clients should treat 401 as unauthenticated and refresh or re-authenticate regardless of body shape. PredOrdersInternalServerError: content: application/json: example: error: code: ORDER_REQUEST_FAILED message: the order request failed type: internal success: false schema: $ref: '#/components/schemas/PredOrdersErrorEnvelope' description: Unexpected server error. securitySchemes: OAuth2: description: >- OAuth2 Bearer token: obtain an access token from the token endpoint and send it in the Authorization header. flows: authorizationCode: authorizationUrl: https://app.aries.com/oauth2/authorize refreshUrl: https://api.aries.com/v1/oauth2/token scopes: account:information: View account balances, positions, and transaction history analytics:information: View analytics, ratings, and market insights calendar:information: Access earnings, economic, and market schedule data market:information: Access live and historical market data market:supplemental: >- News, company profiles, financials, filings, ETF data, technical analysis options:information: Access options chains and expiration data order:execution: Place, modify, and cancel orders order:information: View order history and status position:information: View current positions and holdings user:information: View user profile and personal details user:management: Manage user-scoped resources and saved configuration (internal). watchlist:information: View your watchlists and their symbols. watchlist:management: Create, update, replace, and delete your watchlists. tokenUrl: https://api.aries.com/v1/oauth2/token clientCredentials: refreshUrl: https://api.aries.com/v1/oauth2/token scopes: account:information: View account balances, positions, and transaction history analytics:information: View analytics, ratings, and market insights calendar:information: Access earnings, economic, and market schedule data market:information: Access live and historical market data market:supplemental: >- News, company profiles, financials, filings, ETF data, technical analysis options:information: Access options chains and expiration data order:execution: Place, modify, and cancel orders order:information: View order history and status position:information: View current positions and holdings user:information: View user profile and personal details user:management: Manage user-scoped resources and saved configuration (internal). watchlist:information: View your watchlists and their symbols. watchlist:management: Create, update, replace, and delete your watchlists. tokenUrl: https://api.aries.com/v1/oauth2/token type: oauth2 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.