Orders

The Orders API is the core trading component of the Paper Trading Platform. Use this API to place, modify, cancel, and monitor orders across all asset classes with advanced order types and comprehensive validation.

Overview

The Orders API provides a full suite of trading capabilities designed for paper trading. It simulates real market conditions including partial fills, slippage, market impact, and regulatory requirements while maintaining educational transparency.

API Endpoints Overview

The Orders API provides endpoints for creating, updating, canceling, and retrieving orders. Below is a list of available endpoints.

Endpoint	Method	Description
`/v1/orders`	POST	Create a new order
`/v1/orders/:orderId`	GET	Get order details
`/v1/orders/:orderId`	PUT	Update an order
`/v1/orders/:orderId/cancel`	PUT	Cancel an order
`/v1/orders/account/:accountId`	GET	Get all orders for an account
`/v1/orders/account/:accountId`	DELETE	Cancel all orders for an account
`/v1/orders/batch`	POST	Create multiple orders for multiple accounts

Order Status

Orders can have the following statuses:

Status	Description
`CREATED`	Order has been created
`PENDING`	Order is pending submission
`PENDING_MARKET_OPEN`	Order is waiting for market open
`RESERVING`	Order is reserving funds/shares
`ACTIVE`	Order is active in the market
`FILLED`	Order has been completely filled
`CANCELING`	Order is in the process of being canceled
`CANCELED`	Order has been canceled
`REJECTED`	Order has been rejected
`ERROR`	Order encountered an error

Create Order

Create a new order for equities, options, or futures. Supports various order types and strategies.

Request Body Parameters

Parameter	Type	Description	Required
`portfolioId`	String	Portfolio ID (UUID)	Yes
`symbol`	String	Symbol of the security	Yes
`assetClass`	String	Asset class: EQUITY, OPTION, or FUTURE	Yes
`orderType`	String	Order type: MARKET, LIMIT, STOP, STOP_LIMIT, TRAILING_STOP, TRAILING_STOP_LIMIT	Yes
`positionIntent`	String	Position intent: BUY_TO_OPEN, BUY_TO_CLOSE, SELL_TO_OPEN, SELL_TO_CLOSE	Yes
`quantity`	Number	Number of shares or contracts	Yes
`timeInForce`	String	Time in force: DAY, GTC, IOC, FOK, GTD	Yes
`limitPrice`	Number	Limit price (for LIMIT and STOP_LIMIT orders)	Conditional
`stopPrice`	Number	Stop price (for STOP and STOP_LIMIT orders)	Conditional
`trailingAmount`	Number	Trailing amount in dollars (for TRAILING_STOP)	Conditional
`trailingPercent`	Number	Trailing percentage (for TRAILING_STOP)	Conditional
`strategy`	String	Option strategy (see supported strategies below)	For options
`legs`	Array	Array of option legs for multi-leg strategies	For options
`bracketConfig`	Object	Configuration for bracket orders	For brackets
`latencyProfile`	String	Latency simulation: RETAIL, INSTITUTIONAL, COLOCATED, CUSTOM	No
`goodTillDate`	String	Expiration date for GTD orders (ISO 8601 format)	For GTD

Supported Order Types

Order Type	Description	Required Fields
`MARKET`	Execute immediately at best available price	None
`LIMIT`	Execute at specified price or better	limitPrice
`STOP`	Market order triggered at stop price	stopPrice
`STOP_LIMIT`	Limit order triggered at stop price	stopPrice, limitPrice
`TRAILING_STOP`	Stop order that follows price movement	trailingAmount OR trailingPercent
`TRAILING_STOP_LIMIT`	Stop limit order that follows price movement	trailingAmount OR trailingPercent, limitPrice

Time In Force Types

Time In Force	Description	Notes
`DAY`	Order expires at end of trading day	Default for most orders
`GTC`	Good Till Canceled - remains active until filled or canceled	Maximum 90 days
`IOC`	Immediate or Cancel - fill immediately or cancel unfilled portion	Partial fills allowed
`FOK`	Fill or Kill - fill entire order immediately or cancel	No partial fills
`GTD`	Good Till Date - expires on specified date	Requires goodTillDate parameter

Option Strategies

Strategy	Legs	Description
`VERTICAL_SPREAD`	2	Bull/Bear Call or Put Spread
`IRON_CONDOR`	4	Neutral strategy with limited risk
`BUTTERFLY`	3	Low volatility strategy
`CALENDAR_SPREAD`	2	Time decay strategy
`STRADDLE`	2	Volatility play
`STRANGLE`	2	Volatility play with lower cost

Request

POST

/v1/orders

curl -X POST https://api.paperinvest.io/v1/orders \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "portfolioId": "8b72f1a5-c2e4-48d9-b5a3-1c7e5d3f9e8a",
    "symbol": "AAPL",
    "assetClass": "EQUITY",
    "orderType": "LIMIT",
    "positionIntent": "BUY_TO_OPEN",
    "quantity": 100,
    "limitPrice": 150.00,
    "timeInForce": "DAY"
  }'

Response

201 Created

{
  "orderId": "123e4567-e89b-12d3-a456-426614174000",
  "portfolioId": "8b72f1a5-c2e4-48d9-b5a3-1c7e5d3f9e8a",
  "symbol": "AAPL",
  "assetClass": "EQUITY",
  "orderType": "LIMIT",
  "positionIntent": "BUY_TO_OPEN",
  "quantity": 100,
  "limitPrice": 150.00,
  "timeInForce": "DAY",
  "status": "PENDING",
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}

Option Order Example

Request

POST

/v1/orders

curl -X POST https://api.paperinvest.io/v1/orders \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "portfolioId": "8b72f1a5-c2e4-48d9-b5a3-1c7e5d3f9e8a",
    "symbol": "SPY",
    "assetClass": "OPTION",
    "orderType": "LIMIT",
    "positionIntent": "BUY_TO_OPEN",
    "limitPrice": 2.50,
    "timeInForce": "DAY",
    "strategy": "VERTICAL_SPREAD",
    "legs": [
      {
        "optionSymbol": "SPY240220C00500000",
        "positionIntent": "BUY_TO_OPEN",
        "quantity": 1
      },
      {
        "optionSymbol": "SPY240220C00510000",
        "positionIntent": "SELL_TO_OPEN",
        "quantity": 1
      }
    ]
  }'

Bracket Order Example

Request

POST

/v1/orders

curl -X POST https://api.paperinvest.io/v1/orders \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "portfolioId": "8b72f1a5-c2e4-48d9-b5a3-1c7e5d3f9e8a",
    "symbol": "TSLA",
    "assetClass": "EQUITY",
    "orderType": "MARKET",
    "positionIntent": "BUY_TO_OPEN",
    "quantity": 50,
    "timeInForce": "DAY",
    "bracketConfig": {
      "profitTarget": {
        "orderType": "LIMIT",
        "limitPrice": 260.00
      },
      "stopLoss": {
        "orderType": "STOP",
        "stopPrice": 240.00
      }
    }
  }'

Get Order

Retrieve details of a specific order.

Path Parameters

Parameter	Type	Description	Required
`orderId`	String	The order ID (UUID)	Yes

Request

GET

/v1/orders/:orderId

curl -X GET https://api.paperinvest.io/v1/orders/123e4567-e89b-12d3-a456-426614174000 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

200 OK

{
  "orderId": "123e4567-e89b-12d3-a456-426614174000",
  "portfolioId": "8b72f1a5-c2e4-48d9-b5a3-1c7e5d3f9e8a",
  "symbol": "AAPL",
  "assetClass": "EQUITY",
  "orderType": "LIMIT",
  "positionIntent": "BUY_TO_OPEN",
  "quantity": 100,
  "limitPrice": 150.00,
  "filledQuantity": 100,
  "averagePrice": 149.95,
  "timeInForce": "DAY",
  "status": "FILLED",
  "executedAt": "2025-01-15T10:32:15Z",
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:32:15Z"
}

Get Account Orders

Retrieve all orders for a specific account. This endpoint has a higher rate limit (500 requests/minute) to support frequent polling.

Path Parameters

Parameter	Type	Description	Required
`accountId`	String	The account ID (UUID)	Yes

Query Parameters

Parameter	Type	Description	Required
`page`	Number	Page number (default: 1)	No
`limit`	Number	Results per page (default: 50)	No

Request

GET

/v1/orders/account/:accountId

curl -X GET "https://api.paperinvest.io/v1/orders/account/550e8400-e29b-41d4-a716-446655440000?page=1&limit=10" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

200 OK

{
  "data": [
    {
      "orderId": "123e4567-e89b-12d3-a456-426614174000",
      "symbol": "AAPL",
      "orderType": "LIMIT",
      "quantity": 100,
      "status": "FILLED",
      "createdAt": "2025-01-15T10:30:00Z"
    },
    {
      "orderId": "456e7890-e89b-12d3-a456-426614174111",
      "symbol": "MSFT",
      "orderType": "MARKET",
      "quantity": 50,
      "status": "ACTIVE",
      "createdAt": "2025-01-15T11:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 2,
    "totalPages": 1
  }
}

Update Order

Update an existing order. Only certain fields can be updated based on order status.

Updatable Fields

limitPrice - For LIMIT and STOP_LIMIT orders
stopPrice - For STOP and STOP_LIMIT orders
quantity - Only if no partial fills
timeInForce - Only for certain order types

Request

PUT

/v1/orders/:orderId

curl -X PUT https://api.paperinvest.io/v1/orders/123e4567-e89b-12d3-a456-426614174000 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "limitPrice": 155.00
  }'

Response

200 OK

{
  "orderId": "123e4567-e89b-12d3-a456-426614174000",
  "limitPrice": 155.00,
  "status": "ACTIVE",
  "updatedAt": "2025-01-15T10:45:00Z",
  "message": "Order updated successfully"
}

Cancel Order

Cancel an active order.

Request

PUT

/v1/orders/:orderId/cancel

curl -X PUT https://api.paperinvest.io/v1/orders/123e4567-e89b-12d3-a456-426614174000/cancel \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

200 OK

{
  "orderId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "CANCELED",
  "canceledAt": "2025-01-15T10:50:00Z",
  "message": "Order canceled successfully"
}

Cancel All Account Orders

Cancel all active orders for an account.

Request

DELETE

/v1/orders/account/:accountId

curl -X DELETE https://api.paperinvest.io/v1/orders/account/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

200 OK

{
  "canceledCount": 3,
  "canceledOrders": [
    "123e4567-e89b-12d3-a456-426614174000",
    "456e7890-e89b-12d3-a456-426614174111",
    "789e0123-e89b-12d3-a456-426614174222"
  ],
  "message": "3 orders canceled successfully"
}

Batch Create Orders

Create the same order for multiple accounts simultaneously.

Request Body Parameters

Parameter	Type	Description	Required
`accountIds`	Array	Array of account IDs to create orders for	Yes
`orderData`	Object	Order details (same as single order creation)	Yes

Request

POST

/v1/orders/batch

curl -X POST https://api.paperinvest.io/v1/orders/batch \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "accountIds": [
      "550e8400-e29b-41d4-a716-446655440000",
      "660e8400-e29b-41d4-a716-446655440001"
    ],
    "orderData": {
      "symbol": "SPY",
      "assetClass": "EQUITY",
      "orderType": "MARKET",
      "positionIntent": "BUY_TO_OPEN",
      "quantity": 10,
      "timeInForce": "DAY"
    }
  }'

Response

201 Created

{
  "successful": [
    {
      "accountId": "550e8400-e29b-41d4-a716-446655440000",
      "orderId": "123e4567-e89b-12d3-a456-426614174000"
    },
    {
      "accountId": "660e8400-e29b-41d4-a716-446655440001",
      "orderId": "456e7890-e89b-12d3-a456-426614174111"
    }
  ],
  "failed": [],
  "message": "2 orders created successfully"
}

Subscription-Based Features

Order types and features are restricted based on your subscription tier:

Basic Tier

Market and Limit orders only
DAY and GTC time in force only
Equity trading only
Standard market hours

Pro & Enterprise Tiers

All order types (STOP, STOP_LIMIT, TRAILING_STOP, TRAILING_STOP_LIMIT)
All time in force options (IOC, FOK, GTD)
Extended hours trading
Bracket orders
Custom latency profiles
Priority execution

Note: Enterprise tier includes unlimited account creation

Error Handling

Insufficient Funds

400 Bad Request

{
  "statusCode": 400,
  "message": "Insufficient funds",
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "availableCash": 5000.00,
    "requiredAmount": 15000.00
  }
}

Order Type Not Allowed

403 Forbidden

{
  "statusCode": 403,
  "message": "Order type not allowed for your subscription",
  "error": {
    "code": "FEATURE_NOT_AVAILABLE",
    "currentTier": "BASIC",
    "requiredTier": "PRO"
  }
}

Market Closed

400 Bad Request

{
  "statusCode": 400,
  "message": "Market is closed",
  "error": {
    "code": "MARKET_CLOSED",
    "nextOpen": "2025-01-16T09:30:00-05:00"
  }
}

Orders

Overview

API Endpoints Overview

Order Status

Create Order

Request Body Parameters

Supported Order Types

Time In Force Types

Option Strategies

Request

Response

Option Order Example

Request

Bracket Order Example

Request

Get Order

Path Parameters

Request

Response

Get Account Orders

Path Parameters

Query Parameters

Request

Response

Update Order

Updatable Fields

Request

Response

Cancel Order

Request

Response

Cancel All Account Orders

Request

Response

Batch Create Orders

Request Body Parameters

Request

Response

Subscription-Based Features

Basic Tier

Pro & Enterprise Tiers

Error Handling

Insufficient Funds

Order Type Not Allowed

Market Closed

See Also