Quick Auth:
{" "}
Authenticate once to auto-fill your Bearer token across all API
endpoints
{modalMarkup}
;
}
This is the live **`POST /v1/orders`** endpoint. To place a **stop order**, set `type` to `STOP` and include a `stopPrice` (the trigger). **Omit** `price` and `legs` — once triggered it becomes a market order. Full explanation: [Stop Order guide](/api-reference/orders/stop-order).
Paste this into the request body of the playground below, then hit **Send**:
```json theme={null}
{
"tradingAccountId": "ACC123456",
"symbol": "AAPL",
"side": "SELL",
"type": "STOP",
"qty": "100",
"stopPrice": "145.00",
"timeInForce": "GTC"
}
```
## OpenAPI
````yaml openapi.json POST /v1/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 |
| `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.
- **429 Too Many Requests** – Rate limit exceeded; slow down and respect
`Retry-After` when the header is present. 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 server
url: https://api.aries.com
security: []
tags:
- 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: User management and profile endpoints
name: Users
- description: >-
Order management endpoints for placing, updating, canceling, and
previewing orders
name: Orders
- description: Account management endpoints for positions, orders, and balances
name: Accounts
- description: Calendar and mergers/acquisitions endpoints
name: Calendar
- description: >-
Market data endpoints for symbol search, real-time data access, and equity
details
name: Market Data
- description: >-
Watchlist endpoints for listing, creating, updating, and deleting
watchlists
name: Watchlist
- description: Chart endpoints for config, symbols, history, quotes, and server time
name: Chart
- description: News and news sentiment endpoints
name: News
- description: >-
Indices endpoints for groups, list, search, bar, bars, chart-bars,
realtime values
name: Indices
- description: Logos search and sync endpoints
name: Logos
- description: 'Corporate actions: spinoffs, tender offers, IPO calendar, dividends'
name: Corporate Actions
- description: 'Economy endpoints: inflation, inflation expectations, treasury yields'
name: Economy
- description: >-
Options endpoints: expiry dates, contracts, activity, trades, quotes,
unusual activity
name: Options
- description: >-
Financials: reported, statements, revenue breakdown, short volume, ratios,
short interest
name: Financials
- description: Signals and bull-bear cases
name: Signals
- name: Company
- name: ETF
- name: Filings
- name: Market
- name: Ownership
- name: Stocks
- name: Stock Estimates
- name: Stock Alternative
description: >-
Transcripts, company presentation, social sentiment, investment themes,
supply chain, and ESG data
- name: Technical Analysis
paths:
/v1/orders:
post:
tags:
- Orders
summary: Place an order
description: >-
Place an equity or option order. The order type is automatically
determined:
- No `legs` array = Equity order
- 1 leg in `legs` array = Single-leg option order
- 2-4 legs in `legs` array = Multi-leg option order
Option and multi-leg orders only support `DAY` and `GTC` for
`timeInForce`.
If you send an OSI option symbol in `symbol` and omit `legs`, the
backend derives a single option leg automatically.
Price precision validation:
- `LIMIT` validates `price`
- `STOP` validates `stopPrice`
- `STOP_LIMIT` validates both
- Decimal inputs support up to 5 digits after the decimal point.
operationId: placeOrder
parameters: []
requestBody:
description: >-
The order to place. Required: `tradingAccountId`, `symbol`, `side`,
`type`, `qty`, `timeInForce`. Add `price` for limit-style orders,
`stopPrice` for stop-style orders, and `legs` for option orders. You
may also send an OSI option symbol in `symbol` without `legs` and let
the backend derive the option instrument.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PlaceOrdRequest'
examples:
equityMarket:
summary: Equity Market Order
value:
tradingAccountId: TEST-ACCOUNT-001
symbol: AAPL
side: BUY
type: MARKET
qty: '10'
timeInForce: DAY
equityLimit:
summary: Equity Limit Order
value:
tradingAccountId: TEST-ACCOUNT-001
symbol: AAPL
side: BUY
type: LIMIT
qty: '10'
price: '150.00'
timeInForce: DAY
singleLegCall:
summary: Single-Leg Call Option
value:
tradingAccountId: TEST-ACCOUNT-001
symbol: AAPL
side: BUY
type: LIMIT
qty: '1'
price: '5.50'
timeInForce: DAY
legs:
- side: BUY
ratioQty: '1'
securityType: OPT
putCall: CALL
strikePrice: '150.00'
maturity: '2025-01-17'
positionEffect: OPEN
verticalSpread:
summary: Multi-Leg Vertical Spread
value:
tradingAccountId: TEST-ACCOUNT-001
symbol: AAPL
side: BUY
type: LIMIT
qty: '1'
price: '2.50'
timeInForce: DAY
legs:
- side: BUY
ratioQty: '1'
securityType: OPT
putCall: CALL
strikePrice: '150.00'
maturity: '2025-01-17'
positionEffect: OPEN
- side: SELL
ratioQty: '1'
securityType: OPT
putCall: CALL
strikePrice: '155.00'
maturity: '2025-01-17'
positionEffect: OPEN
responses:
'200':
description: Order placed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/OrdResponse'
example:
success: true
clOrdId: ORDER-20260115-001
status: NEW
symbol: AAPL
side: BUY
qty: '10'
cumQty: '0'
leavesQty: '10'
avgPrice: '0'
text: Order accepted
ordRejReason: ''
transactTime: '2026-01-15T14:30:05Z'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
'503':
description: Broker connection not established
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'504':
description: Order response timeout
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- OAuth2:
- order:execution
components:
schemas:
PlaceOrdRequest:
type: object
description: >-
Request body for placing a live order through the core trading API. Use
Preview Order first when available, then submit this only after the user
confirms the trade.
required:
- tradingAccountId
- symbol
- side
- type
- qty
- timeInForce
properties:
tradingAccountId:
type: string
description: >-
Trading account identifier that should receive the order. Enter the
tradingAccountId selected by the user.
minLength: 1
maxLength: 50
example: TEST-ACCOUNT-001
clientId:
type: string
description: >-
Optional identifier from your app. Send this when you want to tag
orders by app, user, strategy, or integration for your own
reconciliation.
maxLength: 50
example: CLIENT-001
symbol:
type: string
description: >-
Ticker or underlying symbol to trade. Confirm the exact uppercase
value with symbol search before placing an order.
minLength: 1
maxLength: 21
example: AAPL
side:
$ref: '#/components/schemas/OrderSideEnum'
type:
$ref: '#/components/schemas/OrderTypeEnum'
qty:
type: string
description: >-
Number of shares or contracts to trade, sent as a decimal string.
Example: "10" for ten shares or "1" for one option contract.
example: '10'
price:
type: string
description: >-
Limit price as a decimal string. Required for LIMIT and STOP_LIMIT
orders. For buys, this is the maximum price you will pay; for sells,
it is the minimum price you will accept.
example: '150.00'
stopPrice:
type: string
description: >-
Trigger price as a decimal string. Required for STOP and STOP_LIMIT
orders. When the market reaches this price, the stop order becomes
active.
example: '145.00'
timeInForce:
$ref: '#/components/schemas/TimeInForceEnum'
currency:
type: string
description: >-
Three-letter currency code for the order. Use USD for U.S. dollar
orders unless your integration supports another currency.
minLength: 3
maxLength: 3
example: USD
legs:
type: array
description: >-
Option legs for single-leg or multi-leg option orders. Omit this
field for equity orders. Send 1 leg for a single option contract or
2 to 4 legs for a spread or other multi-leg strategy.
maxItems: 4
items:
$ref: '#/components/schemas/OrdLeg'
OrdResponse:
type: object
description: >-
Response returned after submitting an order request. Treat it as
acknowledgement and continue monitoring order status until final fill,
cancel, or rejection.
properties:
success:
type: boolean
description: >-
Whether the order request was accepted by Aries for processing. This
does not guarantee a final fill.
example: true
clOrdId:
type: string
description: >-
Client order ID assigned to this order. Store this value to look up,
replace, or cancel the order later.
example: ORDER-123456
status:
type: string
description: >-
Current order lifecycle state, mirroring FIX Tag 39 (OrdStatus).
Most common values you'll see:
- `PENDING_NEW` — broker has not yet acknowledged the order.
- `NEW` — order is live on the exchange (working, not yet
executing).
- `PARTIALLY_FILLED` — some of `qty` has filled; check `cumQty` and
`leavesQty`.
- `FILLED` — the entire order has executed.
- `PENDING_CANCEL` / `CANCELED` — cancel request in progress /
completed.
- `PENDING_REPLACE` / `REPLACED` — replace request in progress /
completed.
- `REJECTED` — broker refused the order; see `ordRejReason` and
`text`.
- `EXPIRED` — order reached its time-in-force limit without filling.
- `STOPPED`, `SUSPENDED`, `DONE_FOR_DAY`, `CALCULATED`,
`ACCEPTED_FOR_BID`, `SUPERSEDED` — additional FIX states; rare in
normal flows.
example: NEW
enum:
- NEW
- PARTIALLY_FILLED
- FILLED
- DONE_FOR_DAY
- CANCELED
- REPLACED
- PENDING_CANCEL
- STOPPED
- REJECTED
- SUSPENDED
- PENDING_NEW
- CALCULATED
- EXPIRED
- ACCEPTED_FOR_BID
- PENDING_REPLACE
- SUPERSEDED
symbol:
type: string
description: Symbol submitted on the order.
example: AAPL
side:
$ref: '#/components/schemas/OrderSideEnum'
qty:
type: string
description: Original order quantity as a decimal string.
example: '10'
cumQty:
type: string
description: >-
Quantity already filled. Compare this with qty to understand partial
fills.
example: '0'
leavesQty:
type: string
description: >-
Quantity still open and eligible to fill. Value becomes 0 when the
order is fully filled or no longer active.
example: '10'
avgPrice:
type: string
description: >-
Average execution price for filled quantity. This is 0 until fills
occur.
example: '0'
text:
type: string
description: >-
Broker or system message. Show this to users when it explains a
status or warning.
ordRejReason:
type: string
description: >-
Reason the order was rejected, when available. Use this to explain
what the user needs to fix.
transactTime:
type: string
format: date-time
description: Time Aries or the broker recorded the order transaction.
example:
success: true
clOrdId: ORDER-20260115-001
status: NEW
symbol: AAPL
side: BUY
qty: '10'
cumQty: '0'
leavesQty: '10'
avgPrice: '0'
text: Order accepted
ordRejReason: ''
transactTime: '2026-01-15T14:30:05Z'
ErrorResponse:
properties:
codes:
description: Structured error codes for programmatic handling
items:
$ref: '#/components/schemas/ErrorCode'
type: array
error:
type: string
description: >-
Error detail as a string. Exact message content is not fixed and
should not be hard-coded.
example: string
metadata:
additionalProperties: true
description: Additional error context
type: object
type: object
OrderSideEnum:
type: string
description: >-
Which direction to trade in. Pick one:
- `BUY` — buying shares or contracts (opens a long position or closes an
existing short).
- `SELL` — selling shares or contracts you already hold (closes a long
position).
- `SELL_SHORT` — selling shares you do not own (opens a short position).
Subject to short-sale regulations.
- `BUY_TO_COVER` — buying shares to close an open short position.
enum:
- BUY
- SELL
- SELL_SHORT
- BUY_TO_COVER
example: BUY
OrderTypeEnum:
type: string
description: >-
How the order is priced. Pick one:
- `MARKET` — Execute immediately at the best available price. Fast and
guaranteed to fill, but no price guarantee — the actual fill price can
move during execution.
- `LIMIT` — Execute only at the limit `price` or better (lower for buys,
higher for sells). Gives you price control, no execution guarantee.
Requires the `price` field.
- `STOP` — Sits inactive until the market hits `stopPrice`, then
converts to a market order. Common for stop-loss exits. Requires the
`stopPrice` field.
- `STOP_LIMIT` — Sits inactive until the market hits `stopPrice`, then
converts to a limit order at `price`. More control than `STOP`, but the
limit may not fill. Requires both `stopPrice` and `price`.
enum:
- MARKET
- LIMIT
- STOP
- STOP_LIMIT
example: LIMIT
TimeInForceEnum:
type: string
description: >-
How long the order should stay alive before automatically cancelling.
Pick one:
- `DAY` — Active until the end of today's regular trading session, then
cancelled if not filled. The default choice for most orders.
- `GTC` — Good 'Til Cancelled. Stays open across multiple trading days
until you cancel it (the broker may cap at 60–90 days).
- `IOC` — Immediate Or Cancel. Fill whatever you can right now; cancel
the rest immediately. Useful when you want partial fills but no resting
order.
- `FOK` — Fill Or Kill. Fill the entire order immediately, or cancel it
entirely. No partial fills allowed.
- `EXTENDED_HOURS` — Active during pre-market and after-hours trading
sessions in addition to regular hours.
- `AT_THE_OPENING` — Execute at the official market open price; if it
can't fill at open, it's cancelled.
- `AT_THE_CLOSE` — Execute at the official market close price; if it
can't fill at close, it's cancelled.
enum:
- DAY
- GTC
- IOC
- FOK
- EXTENDED_HOURS
- AT_THE_OPENING
- AT_THE_CLOSE
example: DAY
OrdLeg:
type: object
description: >-
One option leg inside a single-leg or multi-leg order. Use this only for
option orders; omit `legs` for normal stock orders.
required:
- side
- ratioQty
- securityType
- positionEffect
properties:
symbol:
type: string
description: >-
Underlying symbol for this option leg. Omit it when the leg uses the
same underlying as the order-level symbol.
maxLength: 21
example: AAPL
side:
type: string
description: >-
Direction for this option leg. Use BUY/B when buying the leg and
SELL/S when selling the leg.
enum:
- B
- S
- BUY
- SELL
example: BUY
ratioQty:
type: string
description: >-
Leg ratio quantity as a decimal string. Use "1" for a standard
one-to-one leg; use other ratios for spreads that require uneven leg
sizing.
example: '1'
cfiCode:
type: string
description: >-
Optional CFI code if your system uses ISO instrument classification.
Most integrations can omit this unless their option workflow
requires it.
maxLength: 10
securityType:
$ref: '#/components/schemas/SecurityTypeEnum'
maturity:
type: string
description: >-
Option expiration date in YYYY-MM-DD format. Required for option
legs when the contract is not fully identified elsewhere.
pattern: ^\d{4}-\d{2}-\d{2}$
example: '2025-01-17'
strikePrice:
type: string
description: >-
Option strike price as a decimal string. Required for option legs
when the contract is not fully identified elsewhere.
example: '150.00'
positionEffect:
type: string
description: >-
Whether this leg opens or closes a position. Use OPEN/O for a new
position and CLOSE/C when closing an existing position.
enum:
- O
- C
- OPEN
- CLOSE
example: OPEN
putCall:
type: string
description: >-
Option contract type. Use CALL/C for call options and PUT/P for put
options.
enum:
- P
- C
- PUT
- CALL
example: CALL
AuthenticationErrorEnvelope:
type: object
description: >-
JSON envelope where `error` is a nested object (`type`, `code`,
`message`, …). Many services use this shape for 400, 401, 403, 404, 429,
and 5xx when using the shared HTTP error format.
properties:
error:
$ref: '#/components/schemas/AuthenticationErrorDetail'
meta:
type: object
additionalProperties: true
description: Optional metadata
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
SecurityTypeEnum:
type: string
description: |-
What kind of instrument the order is for. Pick one:
- `CS` — Common Stock (equity / ETF).
- `OPT` — Option contract (call or put).
enum:
- CS
- OPT
example: CS
AuthenticationErrorDetail:
type: object
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:
type:
type: string
description: >-
Error category emitted by the shared error writer, such as
VALIDATION, BAD_REQUEST, AUTHENTICATION, AUTHORIZATION, NOT_FOUND,
RATE_LIMIT, or INTERNAL.
example: AUTHENTICATION
code:
type: string
description: Machine-readable code
example: INVALID_TOKEN
message:
type: string
description: >-
Error detail as a string. Exact message content is not fixed and
should not be hard-coded.
example: string
details:
type: object
additionalProperties: true
description: Optional extra context
request_id:
type: string
description: Request correlation id when provided
responses:
BadRequest:
description: >-
Invalid query/path/body, malformed JSON, or failed validation.
**Backend (shared HTTP errors):** Routes that use the shared error
writer typically return a **nested** JSON object: `error.type` is an
uppercase category such as `VALIDATION` or `BAD_REQUEST` (see the API
implementation). Other routes may return the **flat** `ErrorResponse`
shape (`error` as a string, optional `codes`). The body may rarely be
empty.
**OpenAPI:** Every operation’s **400** response references this
component so the documented schema and examples stay aligned.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/AuthenticationErrorEnvelope'
- $ref: '#/components/schemas/ErrorResponse'
description: >-
400 responses commonly use a nested `error` object (`type`,
`code`, `message`, optional `details`). Some services still return
flat `ErrorResponse` (`error` string, optional `codes`).
examples:
nested_shared_http_error:
summary: Nested error (typical for shared WriteHTTPError-style responses)
value:
error:
type: VALIDATION
code: VALIDATION_ERROR
message: Query parameter validation failed
details:
fieldName: field is required
nested_bad_request:
summary: Nested error (BAD_REQUEST / invalid JSON)
value:
error:
type: BAD_REQUEST
code: INVALID_JSON
message: string
flat_string:
summary: Flat error string
value:
error: string
flat_with_codes:
summary: Flat error with field codes (some services)
value:
error: string
codes:
- field: string
code: string
description: string
Unauthorized:
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.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ErrorResponse'
- $ref: '#/components/schemas/AuthenticationErrorEnvelope'
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.
examples:
flat_message:
summary: Flat error string (typical)
value:
error: string
flat_with_codes:
summary: Flat error with structured codes
value:
error: string
codes:
- code: string
description: string
nested_error_object:
summary: Nested error (shared HTTP error format)
value:
error:
type: AUTHENTICATION
code: INVALID_TOKEN
message: string
Forbidden:
description: >-
Authenticated but not allowed to perform this action or access this
resource (insufficient scope or role).
**Response body variants:** Flat `ErrorResponse` or nested `error`
object, same pattern as 400/401.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ErrorResponse'
- $ref: '#/components/schemas/AuthenticationErrorEnvelope'
description: 403 responses may use a flat or nested error shape.
examples:
flat:
summary: Flat message
value:
error: string
nested:
summary: Nested error (shared HTTP error format)
value:
error:
type: AUTHORIZATION
code: INSUFFICIENT_SCOPE
message: string
NotFound:
description: >-
The requested resource does not exist or is not visible to this caller.
**Response body variants:** Flat `ErrorResponse` or nested `error`
object.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ErrorResponse'
- $ref: '#/components/schemas/AuthenticationErrorEnvelope'
description: 404 responses may use a flat or nested error shape.
examples:
flat:
summary: Flat message
value:
error: string
nested:
summary: Nested error (shared HTTP error format)
value:
error:
type: NOT_FOUND
code: RESOURCE_NOT_FOUND
message: string
InternalServerError:
description: >-
Unexpected server error or upstream failure. **Retry with exponential
backoff**; do not assume a specific JSON body shape.
**Response body variants:** Flat `ErrorResponse`, nested `error` object,
or occasionally a minimal message. Some paths may return **no body**.
content:
application/json:
examples:
flat_string:
summary: Flat error string
value:
error: string
nested_error_object:
summary: Nested error (shared HTTP error format)
value:
error:
type: INTERNAL
code: INTERNAL_ERROR
message: string
schema:
oneOf:
- $ref: '#/components/schemas/ErrorResponse'
- $ref: '#/components/schemas/AuthenticationErrorEnvelope'
description: 5xx responses may use a flat or nested error shape.
securitySchemes:
OAuth2:
type: oauth2
description: >-
OAuth2 Bearer token: obtain an access token from the token endpoint and
send it in the Authorization header.
flows:
clientCredentials:
tokenUrl: https://api.aries.com/v1/oauth2/token
refreshUrl: https://api.aries.com/v1/oauth2/token
scopes:
user:information: View user profile and personal details
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
user:management: >-
Manage user-scoped resources such as watchlists and other saved
configuration.
authorizationCode:
authorizationUrl: https://app.aries.com/oauth2/authorize
tokenUrl: https://api.aries.com/v1/oauth2/token
refreshUrl: https://api.aries.com/v1/oauth2/token
scopes:
user:information: View user profile and personal details
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
user:management: >-
Manage user-scoped resources such as watchlists and other saved
configuration.
````