> ## Documentation Index
> Fetch the complete documentation index at: https://finance.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# List Prediction Orders
> Returns the authenticated user's prediction-market orders, newest first, with filters for state, account, and symbol and cursor-based paging.
**Use Case:** Show a user's open orders, or find an order after a placement returned `504`.
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
Orders are returned newest first and only ever include the authenticated user's own orders. Each order has the same shape as `data.order` in [Get Prediction Order](/api-reference/predictions/get-order), without the execution reports.
## Filter by state
`status` takes a comma-separated list of states:
```
GET /v1/predictions/orders?status=filled,canceled
```
`open` is shorthand for every state an order can still rest or execute in: `pending_new`, `new`, `partially_filled`, and `unknown`. It can be combined with other states.
```
GET /v1/predictions/orders?status=open
```
Valid states are `pending_new`, `new`, `partially_filled`, `filled`, `canceled`, `rejected`, `expired`, `done_for_day`, and `unknown`. Any other value returns `400`.
`accountId` and `symbol` narrow the results further.
## Paging
`limit` sets the page size. It defaults to `50`, and values above `200` are clamped to `200`.
Pass the response's `nextCursor` as `cursor` to fetch the next page. `nextCursor` is absent on the last page.
```json theme={null}
{
"success": true,
"data": {
"orders": [
{
"orderId": "0b9f3c2e-5d6a-4f1b-8e7c-9a0d1e2f3a4b",
"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",
"workingQuantity": "10",
"state": "new",
"cumQty": "0",
"leavesQty": "10",
"avgPx": "0",
"createdAt": "2026-10-08T14:02:11.482Z",
"updatedAt": "2026-10-08T14:02:11.497Z"
}
],
"nextCursor": "string"
}
}
```
Quantities and prices are exact decimals serialized as JSON strings. Parse them with a decimal type.
## Example
```bash theme={null}
curl -X GET "https://api.tradearies.dev/v1/predictions/orders?status=open&limit=50" \
-H "Authorization: Bearer $ACCESS_TOKEN"
```
## Errors
| Status | `code` | Meaning |
| - | - | - |
| `400` | `INVALID_LIMIT` | `limit` is not a positive integer. |
| `400` | `INVALID_ORDER` | An unknown state in `status`, or a malformed `cursor`. |
| `401` | — | Missing or invalid credentials. |
| `500` | `ORDER_REQUEST_FAILED` | Unexpected server error. |
## OpenAPI
````yaml openapi.json GET /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:
get:
tags:
- Prediction Orders
summary: List prediction orders
description: >-
**Closed beta.** Available only to accounts enrolled in the
prediction-market orders closed beta. Returns the authenticated user's
prediction-market orders, newest first, one page at a time.
operationId: listPredictionOrders
parameters:
- description: >-
Comma-separated order states, or `open` for every state an order can
still rest or execute in (`pending_new`, `new`, `partially_filled`,
`unknown`). An unknown state returns `400`.
example: open
in: query
name: status
schema:
type: string
- description: Only orders on this account.
in: query
name: accountId
schema:
type: string
- description: Only orders on this contract symbol.
in: query
name: symbol
schema:
type: string
- description: >-
Orders per page. Values above 200 are clamped to 200. `0`, a
negative value, or a non-integer returns `400`.
in: query
name: limit
schema:
default: 50
maximum: 200
minimum: 1
type: integer
- description: '`nextCursor` from the previous page.'
in: query
name: cursor
schema:
type: string
responses:
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PredMdSuccessEnvelope'
- properties:
data:
$ref: '#/components/schemas/PredOrdersOrderPage'
type: object
description: One page of orders.
'400':
$ref: '#/components/responses/PredOrdersBadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/PredOrdersInternalServerError'
security:
- OAuth2: []
servers:
- description: Staging
url: https://api.tradearies.dev
components:
schemas:
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
PredOrdersOrderPage:
properties:
nextCursor:
description: Pass as `cursor` to fetch the next page. Absent on the last page.
type: string
orders:
items:
$ref: '#/components/schemas/PredOrdersOrder'
type: array
required:
- orders
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.