Core Order API

Provides the complete set of API endpoints for managing the lifecycle of single-leg orders. These endpoints allow you to submit, retrieve, amend, pause, resume, and cancel single-leg orders.

For other order-specific API workflows, please refer to the documentation for Simple Orders, Algorithmic Orders, Multi-Orders, and Chained Orders.

Get all orders

GET /api/orders/

Get all orders within the past 12 months. Identity is inferred by API token.

Query Parameters

Name

Type

Description

statuses

string

Comma separate values of order statuses. (e.g., "ACTIVE,COMPLETED,CANCELED"). See the Type Reference page for a list of available values.

account_names

string

Comma separated values of account names. If using another user's account, must be scoped with prefix ex. username/account_name

before

string

ISO 8601 format timestamp, orders before this timestamp

after

string

ISO 8601 format timestamp, orders after this timestamp

custom_order_ids

string

Comma separated values of custom_order_id submitted with the order

page

string

1-indexed page number, default: 1

page_size

string

page size, default: 100

Example Request

GET /api/orders/?statuses=ACTIVE,PAUSED&account_names=binance_main,coinbase_pro&page=1&page_size=50&after=2023-12-01T00:00:00Z&before=2023-12-31T23:59:59Z&custom_order_ids=order_123,order_456
Authorization: Bearer <token>

Example Response

{
  "orders": [
    {
      "id": "6debb950-614a-4366-b73b-7d7574fd9e15",
      "custom_order_id": "order_123",
      "parent_order_id": null,
      "notes": "",
      "pair": "BTC-USD",
      "side": "buy",
      "exchanges": ["binance", "coinbase_pro"],
      "buy_token": "BTC",
      "buy_token_amount": "0.1",
      "sell_token": "USD",
      "sell_token_amount": "5000.00",
      "executed_qty": "0.05",
      "executed_buy_qty": "0.05",
      "average_executed_price": "50000.00",
      "executed_notional": "2500.00",
      "target_order_qty": "0.1",
      "target_remaining_qty": "0.05",
      "target_token": "BTC",
      "target_executed_qty": "0.05",
      "pct_filled": "50.00",
      "total_fee": "2.50",
      "strategy": "TWAP",
      "super_strategy": "Standard",
      "duration": 3600,
      "accounts": ["account_1", "account_2"],
      "account_names": ["binance_main", "coinbase_pro"],
      "engine_passiveness": "0.5",
      "schedule_discretion": "0.3",
      "pov_limit": null,
      "pov_target": null,
      "alpha_tilt": "0.0",
      "strategy_params": {},
      "user": "user_123",
      "status": "ACTIVE",
      "active": true,
      "is_simple": true,
      "failure_reason": null,
      "limit_price": "",
      "is_reverse_limit_price": false,
      "time_start": "2023-12-15T10:00:00Z",
      "time_end": "2023-12-15T11:00:00Z",
      "created_at": "2023-12-15T09:55:00Z",
      "updated_at": "2023-12-15T10:30:00Z"
    }
  ],
  "page_number": 1,
  "page_size": 50,
  "num_pages": 1,
  "order_count": 1
}

Response Codes:

```json
{
    "orders": [
        {
            "id": "984ffec9-f0bf-4b28-9dc1-81d5dfda1794",
            "custom_order_id": "custom1",
            "notes": "leverage: 10",
            "pair": "ETH:PERP-USDT",
            "side": "buy",
            "buy_token": "ETH:PERP",
            "sell_token": "USDT", 
            "sell_token_amount": 500.0,
            "executed_qty": 0,
            "average_executed_price": null,
            "executed_notional": 0,
            "total_fee": 0,
            "strategy": "TWAP",
            "duration": 120,
            "accounts": ["d0d54d4f-e3a5-49ba-a2c9-559caf2c69d2"],
            "account_names": ["test"],
            "engine_passiveness": 0.1,
            "schedule_discretion": 0.08,
            "strategy_params": { "passive_only": true },
            "user": "2",
            "status": "ACTIVE",
            "is_simple": false,
            "failure_reason": "",
            "limit_price": -1.0,
            "start_datetime": "2023-05-24T19:15:25.026448Z",
            "time_end": "2023-05-24T19:17:25.026448Z",
            "created_at": "2023-05-24T19:15:25.043965Z",
            "updated_at": "2023-05-24T19:15:25.259855Z"
        }
    ],
    "page_number": 1,
    "page_size": 100,
    "num_pages": 1,
    "order_count": 36
}
```

Occurs when:

Invalid date format provided for before or after parameters (must be ISO 8601 format)
Account names provided don't exist or user doesn't have access to them
The specific error message will indicate which parameter caused the issue

Sample Error Messages

{
  "400": {
    "description": "Bad Request",
    "examples": [
      {
        "scenario": "Invalid date format for 'after' parameter",
        "response": {
          "message": "Invalid after date format"
        }
      },
      {
        "scenario": "Invalid date format for 'before' parameter", 
        "response": {
          "message": "Invalid after date format"
        }
      },
      {
        "scenario": "Invalid account names",
        "response": {
          "error": "Account display name 'invalid_account' not found for user"
        }
      },
      {
        "scenario": "Missing required fields (POST)",
        "response": {
          "error": "Missing required fields: ['pair', 'accounts', 'side', 'duration', 'strategy']"
        }
      },
      {
        "scenario": "No quantity fields provided (POST)",
        "response": {
          "errors": "Need one of the qty fields: ['base_asset_qty', 'quote_asset_qty', 'sell_token_amount']"
        }
      },
      {
        "scenario": "Multiple quantity fields provided (POST)",
        "response": {
          "errors": "Cannot have more than one of the qty fields: ['base_asset_qty', 'quote_asset_qty', 'sell_token_amount']"
        }
      },
      {
        "scenario": "General validation errors (POST)",
        "response": {
          "errors": [
            "Invalid order data",
            "Pair is required", 
            "Side must be either 'Buy' or 'Sell'"
          ]
        }
      },
      {
        "scenario": "Superuser restriction (POST)",
        "response": {
          "error": "Superusers on retail cannot place orders"
        }
      }
    ]
  }
}

Occurs when:

No valid authentication token provided in Authorization header
Token is expired or invalid
User account is not active

Sample Error Messages:

{
  "401": {
    "description": "Unauthorized", 
    "examples": [
      {
        "scenario": "No authentication credentials provided",
        "response": {
          "detail": "Authentication credentials were not provided."
        }
      },
      {
        "scenario": "Invalid or expired token",
        "response": {
          "detail": "Invalid token."
        }
      }
    ]
  }
}

Occurs when:

Database connection issues
Unexpected server errors during order retrieval

Sample Error Message

{
  "500": {
    "description": "Internal Server Error",
    "examples": [
      {
        "scenario": "Unexpected server error",
        "response": {
          "errors": ["An unexpected error occurred. Please try again later."]
        }
      }
    ]
  }
}

Get active orders

get /api/active_orders/

Get all currently active orders for the authenticated user.

Name

Type

Description

exclude_paused

string

Whether to exclude paused orders. Default: true

account_names

string

Comma separated values of account names to filter by

only_active

string

Whether to return only active orders. Default: false

Example Request

GET /api/active_orders/?exclude_paused=true&account_names=binance_main,coinbase_pro&only_active=false
Authorization: Bearer <token>

Example Response

{
  "orders": [
    {
      "id": "6debb950-614a-4366-b73b-7d7574fd9e15",
      "custom_order_id": "my_custom_order_123",
      "parent_order_id": null,
      "notes": "Buy BTC over 1 hour using TWAP strategy",
      "pair": "BTC-USD",
      "side": "buy",
      "exchanges": ["binance", "coinbase_pro"],
      "buy_token": "BTC",
      "buy_token_amount": "0.5",
      "sell_token": "USD",
      "sell_token_amount": "22500.00",
      "strategy": "TWAP",
      "duration": 3600,
      "status": "ACTIVE",
      "time_start": "2023-12-01T10:00:00Z",
      "time_end": "2023-12-01T11:00:00Z",
      "limit_price": "45000.00",
      "engine_passiveness": 0.5,
      "schedule_discretion": 0.3,
      "alpha_tilt": 0.1,
      "pos_side": "long",
      "user": "user_123",
      "created_at": "2023-12-01T09:55:00Z",
      "updated_at": "2023-12-01T09:55:00Z",
      "fills": [
        {
          "id": "fill_123",
          "order_id": "6debb950-614a-4366-b73b-7d7574fd9e15",
          "exchange": "binance",
          "pair": "BTC-USD",
          "side": "buy",
          "quantity": "0.1",
          "price": "44950.00",
          "timestamp": "2023-12-01T10:15:00Z",
          "fee": "0.001",
          "fee_currency": "BTC"
        }
      ]
    },
    {
      "id": "7fecb061-725b-5477-c84c-8e8685ge0f26",
      "custom_order_id": "my_custom_order_456",
      "parent_order_id": null,
      "notes": "Sell ETH using VWAP strategy",
      "pair": "ETH-USD",
      "side": "sell",
      "exchanges": ["coinbase_pro"],
      "buy_token": "USD",
      "buy_token_amount": "5000.00",
      "sell_token": "ETH",
      "sell_token_amount": "2.5",
      "strategy": "VWAP",
      "duration": 1800,
      "status": "PAUSED",
      "time_start": "2023-12-01T11:00:00Z",
      "time_end": "2023-12-01T11:30:00Z",
      "limit_price": "2000.00",
      "engine_passiveness": 0.3,
      "schedule_discretion": 0.2,
      "alpha_tilt": 0.0,
      "pos_side": "short",
      "user": "user_123",
      "created_at": "2023-12-01T10:45:00Z",
      "updated_at": "2023-12-01T11:10:00Z",
      "fills": []
    }
  ],
  "order_count": 2
}

Response Codes

{
    "orders": [
        {
            "id": "984ffec9-f0bf-4b28-9dc1-81d5dfda1794",
            "status": "ACTIVE",
            "pair": "BTC-USDT",
            "side": "buy",
            "executed_qty": 0.5,
            "target_order_qty": 1.0,
            "pct_filled": 50.0
        }
    ],
    "order_count": 1
}

Occurs when:

Invalid account names are provided in the account_names query parameter
The user doesn't have access to the specified accounts
There's an issue resolving the account display names to account IDs

The specific error message depends on what went wrong in the account lookup process, but the response structure is always: {"error": "error message from account lookup"}S

Sample Error Message

{
  "400": {
    "description": "Bad Request",
    "examples": [
      {
        "scenario": "Invalid account names",
        "response": {
          "error": "Account display name 'invalid_account' not found for user"
        }
      }
    ]
  }
}

Occurs when:

No valid authentication token provided
Token is expired or revoked

Sample Error Messages

{
  "401": {
    "description": "Unauthorized",
    "examples": [
      {
        "scenario": "No authentication credentials provided",
        "response": {
          "detail": "Authentication credentials were not provided."
        }
      },
      {
        "scenario": "Invalid or expired token/session",
        "response": {
          "detail": "Invalid token."
        }
      }
    ]
  }
}

Submit an order

POST /api/orders/

Submit an order for scheduling and execution. The request contains all the parameters necessary to carry out the execution until completion.

The order is queued immediately if start_datetime is not set or is in the past.

Request Body

Name

Type

Required

Description

pair

string

Yes

Symbol for the token pair, refer to token pairs reference

side

string

Yes

Order side: buy or sell

pos_side

string

short or long. Use when the account's position mode is set to "Hedge"

base_asset_qty

decimal

Conditional

Quantity of base asset. Must provide exactly one of: base_asset_qty, quote_asset_qty, or sell_token_amount

quote_asset_qty

decimal

Conditional

Quantity of quote asset. Must provide exactly one of: base_asset_qty, quote_asset_qty, or sell_token_amount

sell_token_amount

decimal

Conditional

Quantity of sell token. Must provide exactly one of: base_asset_qty, quote_asset_qty, or sell_token_amount

strategy

string

Yes

Trading algorithm UUID. See the Type Reference page for a list of values

strategy_params

object

Various options for configuring the strategy. See the Type Reference page for more details

accounts

array[string]

Yes

List of account names. You pick this name when linking a new exchange key under key management

duration

integer

Conditional

Duration of execution in seconds. Required unless pov_target is provided

start_datetime

string (ISO 8601)

Time represented in Epoch milliseconds of when to start execution. If not provided, defaults to now

limit_price

string

Limit price for passive orders. If not provided, the algorithm will decide

is_reverse_limit_price

boolean

Engine will only trade at prices worse than limit_price

engine_passiveness

decimal [0, 1]

Yes

Passiveness of the engine (accepted values: 0 to 1). A higher passiveness will result in the engine placing further from the spread. For more information, read about Passiveness

schedule_discretion

decimal [0.02, 0.5]

Yes

Ratio of order size allowed to deviate from the target i.e. decides the upper and lower bounds of the schedule. For more information, read about Discretion

alpha_tilt

decimal [-1, 1]

Implied short-term alpha. See Alpha Tilt for more detail

pov_limit

decimal (0, 1]

The engine will trade at no more than this fraction of market volume. See Participation Rate Limit for more detail. Note that the GUI interprets this value as a percentage

pov_target

decimal (0, 1]

Participation Rate Target. Note that the GUI interprets this value as a percentage

max_otc

decimal [0, 1]

Upper bound of the fraction of the parent order that will be executed via OTC. See Max OTC Percentage. Note that the GUI interprets this value as a percentage

order_condition

string

An expression representing the condition that would trigger the start of execution. Refer to Conditional Order

notes

string

Arbitrary string to add notes

custom_order_id

string

64 max length string that can be used to filter in GET orders endpoint. When TaaS sends orders to supported exchanges, the client order id of the exchange orders will start with "TL" followed by first 9 alphanumeric characters of the custom_order_id

updated_leverage

integer

Leverage for the account can be updated prior to submitting the order (behavior varies based on the venue)

stop_price

decimal

Stop price for stop orders

order_slices

integer

Number of order slices to use for execution. Higher values create more granular execution with smaller individual placements.

target_asset

string

Specifies which asset (base or quote) the order quantity refers to. This determines how the order quantity is interpreted and calculated.

exposure_tolerance

decimal

Tolerance for exposure limits in multi-order scenarios

market_type

string

Market type for the order

super_strategy

string (UUID)

Super strategies are predefined configurations that include strategy parameters, engine passiveness, schedule discretion, and alpha tilt settings.

Example Request

POST /api/orders/
Authorization: Bearer <token>
Content-Type: application/json

{
  "pair": "BTC-USD",
  "side": "buy",
  "accounts": ["binance_main", "coinbase_pro"],
  "strategy": "TWAP",
  "duration": 3600,
  "base_asset_qty": 0.5,
  "custom_order_id": "my_custom_order_123",
  "notes": "Buy BTC over 1 hour using TWAP strategy",
  "limit_price": "45000.00",
  "start_datetime": "2023-12-01T10:00:00Z",
  "engine_passiveness": 0.5,
  "schedule_discretion": 0.3,
  "alpha_tilt": 0.1,
  "pos_side": "long"
}

Example Response

{
  "id": "6debb950-614a-4366-b73b-7d7574fd9e15",
  "custom_order_id": "my_custom_order_123",
  "parent_order_id": null,
  "notes": "Buy BTC over 1 hour using TWAP strategy",
  "pair": "BTC-USD",
  "side": "buy",
  "exchanges": ["binance", "coinbase_pro"],
  "buy_token": "BTC",
  "buy_token_amount": "0.5",
  "sell_token": "USD",
  "sell_token_amount": "22500.00",
  "strategy": "TWAP",
  "duration": 3600,
  "status": "ACTIVE",
  "time_start": "2023-12-01T10:00:00Z",
  "time_end": "2023-12-01T11:00:00Z",
  "limit_price": "45000.00",
  "engine_passiveness": 0.5,
  "schedule_discretion": 0.3,
  "alpha_tilt": 0.1,
  "pos_side": "long",
  "user": "user_123",
  "created_at": "2023-12-01T09:55:00Z",
  "updated_at": "2023-12-01T09:55:00Z"
}

Response Codes

{
    "id": "6debb950-614a-4366-b73b-7d7574fd9e15",
    "buy_token": "ETH",
    "sell_token": "USDT",
    "side": "buy",
    "pair": "ETH-USDT",
    "sell_token_amount": 50000.0,
    "strategy": "6fe4ba3e-c578-45bd-824c-c523bf3c56de",
    "strategy_params": {
        "passive_only": true
    },
    "limit_price": 1.0,
    "start_datetime": "2023-08-08T23:54:06.300319Z",
    "time_end": "2023-08-08T23:59:06.300319",
    "duration": 300,
    "accounts": ["09d3144b-9359-4ec3-8772-2dd1bfb86652"],
    "account_names": ["mock"],
    "user": "2",
    "status": "ACTIVE",
    "engine_passiveness": "0.2",
    "schedule_discretion": "0.08",
    "failure_reason": "",
    "executed_qty": 0,
    "executed_price": null,
    "executed_notional": null,
    "notes": "",
    "custom_order_id": "",
    "updated_leverage": null,
    "placements": [],
    "fills": [
        {
            "id": "44c82c49-1e9d-43f8-98cd-318a2c01a317",
            "created_at": 1660445425000,
            "fill_time": 1660445725000,
            "role": "MAKE",
            "external_id": "21949858",
            "executed_price": 1658.40,
            "executed_qty": 3.5,
            "exchange": "Binance",
            "fee": 0.0443
        },
        //...
    ]
}

Occurs when:

Missing required fields: pair, side, accounts, strategy, or duration (unless pov_target provided)
No quantity field provided: must include exactly one of base_asset_qty, quote_asset_qty, or sell_token_amount
Multiple quantity fields provided: cannot have more than one of base_asset_qty, quote_asset_qty, or sell_token_amount
Invalid parameter values (e.g., negative quantities, invalid strategy UUID)
Invalid account names or insufficient permissions
Invalid pair format or unsupported trading pair
Invalid limit price format or value
Invalid strategy parameters
Invalid order condition expression
Invalid time format for start_datetime
Invalid leverage value for the specified venue

Sample Error Messages

{
  "400": {
    "description": "Bad Request",
    "examples": [
      {
        "scenario": "Missing required fields",
        "response": {
          "errors": ["Need one of the qty fields: ['base_asset_qty', 'quote_asset_qty', 'sell_token_amount']"]
        }
      },
      {
        "scenario": "Multiple quantity fields",
        "response": {
          "errors": ["Cannot have more than one of the qty fields: ['base_asset_qty', 'quote_asset_qty', 'sell_token_amount']"]
        }
      },
      {
        "scenario": "Invalid strategy UUID",
        "response": {
          "errors": ["Invalid strategy: 6fe4ba3e-c578-45bd-824c-c523bf3c56de"]
        }
      },
      {
        "scenario": "Invalid account names",
        "response": {
          "error": "Account display name 'invalid_account' not found for user"
        }
      },
      {
        "scenario": "Invalid pair format",
        "response": {
          "errors": ["Invalid buy_token ASDF"]
        }
      },
      {
        "scenario": "Invalid limit price",
        "response": {
          "errors": ["Limit price must be a positive number"]
        }
      }
    ]
  }
}

Occurs when:

Missing or invalid API token
Token has expired
Insufficient permissions to access the specified accounts

Sample Error Messages

{
  "401": {
    "description": "Unauthorized",
    "examples": [
      {
        "scenario": "Missing API token",
        "response": {
          "detail": "Authentication credentials were not provided."
        }
      },
      {
        "scenario": "Invalid API token",
        "response": {
          "detail": "Invalid token header. No credentials provided."
        }
      },
      {
        "scenario": "Expired token",
        "response": {
          "detail": "Token has expired."
        }
      }
    ]
  }
}

Occurs when:

Superusers on retail environment cannot place orders
Account access restrictions
Trading restrictions on the specified pair or venue

Sample Error Message

{
  "403": {
    "description": "Forbidden",
    "examples": [
      {
        "scenario": "Superuser on retail environment",
        "response": {
          "error": "Superusers on retail cannot place orders"
        }
      },
      {
        "scenario": "Account access denied",
        "response": {
          "error": "Access denied to specified accounts"
        }
      },
      {
        "scenario": "Trading restrictions",
        "response": {
          "error": "Trading not allowed for this pair on the specified venue"
        }
      }
    ]
  }
}

Occurs when:

Insufficient balance for the order
Market restrictions prevent order execution
Exchange-specific limitations
Invalid order configuration for the selected strategy

Sample Error Messages

{
  "422": {
    "description": "Unprocessable Entity",
    "examples": [
      {
        "scenario": "Insufficient balance",
        "response": {
          "errors": ["Insufficient balance for order execution"]
        }
      },
      {
        "scenario": "Market restrictions",
        "response": {
          "errors": ["Market is closed for the specified trading pair"]
        }
      },
      {
        "scenario": "Exchange limitations",
        "response": {
          "errors": ["Order size exceeds exchange limits"]
        }
      },
      {
        "scenario": "Invalid strategy configuration",
        "response": {
          "errors": ["Strategy parameters not compatible with selected trading pair"]
        }
      }
    ]
  }
}

Occurs when:

Database connection issues
External service failures
Unexpected system errors

Sample Error Messages

{
  "500": {
    "description": "Internal Server Error",
    "examples": [
      {
        "scenario": "Database connection error",
        "response": {
          "error": "Database connection failed"
        }
      },
      {
        "scenario": "External service failure",
        "response": {
          "error": "Price feed service unavailable"
        }
      },
      {
        "scenario": "Unexpected system error",
        "response": {
          "error": "Something went wrong"
        }
      }
    ]
  }
}

Get order summary

GET /api/order_summary/{id}

Get basic order information including execution status, quantities, and key parameters. This endpoint provides a concise summary of the order without detailed fill information.

Purpose: Get a list of orders with statistics
Scope: Multiple orders (paginated)
Data: Basic order info + statistics + fills for each order
Use Case: Dashboard, order list view, bulk analytics
Performance: Optimized for bulk retrieval

Path Parameters

Name

Type

Description

id*

string (UUID)

UUID of the order to retrieve

{'id': '45a18223-aeab-4451-9253-c3135261d55b',
 'pair': 'BTC-USDT',
 'side': 'buy',
 'status': 'COMPLETE',
 'start_datetime': '2024-10-25T16:55:03.842747Z',
 'duration': 108,
 'target_token': 'USDT',
 'order_qty': 60000.0,
 'remaining_qty': 3.38620187,
 'executed_qty': 59996.61379813,
 'executed_notional': 59996.61379813,
 'exchange_names': ['MockExchange'],
 'account_names': ['mock'],
 'schedule_discretion': 0.08,
 'engine_passiveness': 0.02,
 'alpha_tilt': 0.01,
 'strategy': None,
 'trajectory': 'VWAP',
 'strategy_params': {'passive_only': True},
 'participation_rate_target_percent': 8.0,
 'market_type': 'spot',
 'parent_order_id': None,
 'failure_reason': '',
 'limit_price': ''}

Occurs when:

No order ID provided in the URL path
Invalid UUID format for the order ID
Order ID is malformed or contains invalid characters

Sample Error Messages

{
  "400": {
    "description": "Bad Request",
    "examples": [
      {
        "scenario": "No order ID provided",
        "response": "No order ID given!"
      },
      {
        "scenario": "Invalid UUID format",
        "response": "Invalid order ID format"
      }
    ]
  }
}

Occurs when:

Missing or invalid API token
Token has expired
User does not have permission to access the specified order

Sample Error Messages

{
  "401": {
    "description": "Unauthorized",
    "examples": [
      {
        "scenario": "Missing API token",
        "response": {
          "detail": "Authentication credentials were not provided."
        }
      },
      {
        "scenario": "Invalid API token",
        "response": {
          "detail": "Invalid token header. No credentials provided."
        }
      },
      {
        "scenario": "Expired token",
        "response": {
          "detail": "Token has expired."
        }
      },
      {
        "scenario": "Order access denied",
        "response": "Unauthorized"
      }
    ]
  }
}

Occurs when:

Order with the specified ID does not exist
Order has been deleted or is not accessible
Order ID is valid but the order is not found in the database

{
  "404": {
    "description": "Not Found",
    "examples": [
      {
        "scenario": "Order does not exist",
        "response": "No order found with given ID!"
      },
      {
        "scenario": "Order not accessible",
        "response": "Order not found or access denied"
      }
    ]
  }
}

Occurs when:

Database connection issues
External service failures
Unexpected system errors during order retrieval

Sample Error Message

{
  "500": {
    "description": "Internal Server Error",
    "examples": [
      {
        "scenario": "Database connection error",
        "response": {
          "error": "Database connection failed"
        }
      },
      {
        "scenario": "External service failure",
        "response": {
          "error": "Price feed service unavailable"
        }
      },
      {
        "scenario": "Unexpected system error",
        "response": {
          "error": "Something went wrong"
        }
      }
    ]
  }
}

Get orders with statistics

GET /api/orders_with_stats/

Retrieve a paginated list of orders with their associated statistics and analytics data. This endpoint provides comprehensive order information including execution statistics, fill breakdowns, and performance metrics.

Purpose: Get a list of orders with statistics
Scope: Multiple orders (paginated)
Data:
- Basic Order Information: ID, pair, side, status, duration, etc.
- Execution Statistics: VWAP, arrival price, departure price, interval volume
- Fill Data: Detailed fill information with placement details
- Performance Metrics: Fee calculations, execution analytics
- Account Information: Associated accounts and exchange details
Use Case: Dashboard, order list view, bulk analytics
Performance: Optimized for bulk retrieval

Query Parameters

Name

Type

Description

page

integer

Page number for pagination (Default: 1; Optional)

page_size

integer

Number of orders per page (Default: 500, Max: 100)

Example Request

GET /api/orders_with_stats/?page=1&page_size=100
Authorization: Bearer <token>

Example Response

{
  "orders": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "pair": "BTC/USDT",
      "side": "buy",
      "status": "COMPLETE",
      "time_start": "2024-01-15T10:00:00Z",
      "duration": 3600,
      "target_token": "BTC",
      "order_qty": "1.00000000",
      "remaining_qty": "0.00000000",
      "executed_qty": "1.00000000",
      "executed_notional": "45000.00",
      "exchange_names": ["binance", "coinbase"],
      "account_names": ["main_account"],
      "schedule_discretion": "0.10000000",
      "engine_passiveness": "0.05000000",
      "alpha_tilt": "0.00000000",
      "strategy": "TWAP",
      "trajectory": "TWAP",
      "strategy_params": {},
      "participation_rate_target_percent": null,
      "market_type": "SPOT",
      "parent_order_id": null,
      "stats": {
        "order_id": "550e8400-e29b-41d4-a716-446655440000",
        "stat_id": "123e4567-e89b-12d3-a456-426614174000",
        "interval_volume": "1000000.00000000",
        "vwap": "45000.00000000",
        "arrival_price": "44950.00000000",
        "departure_price": "45050.00000000"
      },
      "fills": [
        {
          "placement_id": "123e4567-e89b-12d3-a456-426614174001",
          "exchange": "binance",
          "role": "taker",
          "executed_price": "45000.00",
          "executed_qty": "0.50000000",
          "executed_notional": "22500.00",
          "fee": "22.50",
          "fill_time": "2024-01-15T10:30:00Z"
        }
      ]
    }
  ],
  "page_number": 1,
  "page_size": 100,
  "num_pages": 5,
  "order_count": 450
}

Response Codes

{
  "200": {
    "description": "Orders with statistics retrieved successfully",
    "content": {
      "application/json": {
        "example": {
          "orders": [
            {
              "id": "550e8400-e29b-41d4-a716-446655440000",
              "pair": "BTC/USDT",
              "side": "buy",
              "status": "COMPLETE",
              "stats": {
                "vwap": "45000.00000000",
                "arrival_price": "44950.00000000",
                "departure_price": "45050.00000000"
              }
            }
          ],
          "page_number": 1,
          "page_size": 100,
          "num_pages": 5,
          "order_count": 450
        }
      }
    }
  }
}

Occurs when:

The page_size parameter is greater than 1000
Invalid query parameters are provided

Sample Error Message

{
  "400": {
    "description": "Invalid request parameters",
    "content": {
      "application/json": {
        "example": {
          "error": "page_size cannot be greater than 1000"
        }
      }
    }
  }
}

Occurs when:

Invalid or missing authentication token
User is not authenticated

Sample Error Message

{
  "401": {
    "description": "Unauthorized",
    "content": {
      "application/json": {
        "example": {
          "error": "Unauthorized"
        }
      }
    }
  }
}

Notes

Superuser Access: Superusers can retrieve orders for all users; regular users only see their own orders.
Pagination: Use page and page_size to control result set size.
Statistics: Each order includes a stats object with VWAP, arrival price, departure price, and interval volume.
Fills: Each order includes detailed fill data if available.

Related Endpoints

GET /api/orders/ - Get orders (basic info, no stats)
GET /api/order/<id>- Get single order details

Get order details

GET /api/order/{id}

Get detailed single order info along with executed fills

Purpose: Get detailed information about a single order
Scope: One specific order
Data: Comprehensive order details including:
- Full order configuration
- All placements and fills
- Execution analytics
- Market data
- Performance metrics
- Audit trail
Use Case: Order detail page, deep analysis of one order
Performance: Heavy computation for single order

Path Parameters

Name

Type

Description

id*

string

UUID of the order (Required)

Query Parameters

Name

Type

Description

include_fills

boolean

Whether to include fill data in response. (Default: false, Optional)

Example Request

GET /api/order/6debb950-614a-4366-b73b-7d7574fd9e15?include_fills=true
Authorization: Bearer <token>

Example Response

{
  "id": "6debb950-614a-4366-b73b-7d7574fd9e15",
  "custom_order_id": "my_custom_order_123",
  "parent_order_id": null,
  "notes": "Buy BTC over 1 hour using TWAP strategy",
  "pair": "BTC-USD",
  "side": "buy",
  "exchanges": ["binance", "coinbase_pro"],
  "buy_token": "BTC",
  "buy_token_amount": "0.5",
  "sell_token": "USD",
  "sell_token_amount": "22500.00",
  "executed_qty": "0.25",
  "executed_buy_qty": "0.25",
  "average_executed_price": "45000.00",
  "executed_notional": "11250.00",
  "target_order_qty": "0.5",
  "target_remaining_qty": "0.25",
  "target_token": "BTC",
  "target_executed_qty": "0.25",
  "pct_filled": "50.00",
  "total_fee": "5.63",
  "strategy": "TWAP",
  "super_strategy": "Impact Minimization",
  "duration": 3600,
  "accounts": ["account_id_1", "account_id_2"],
  "account_names": ["binance_main", "coinbase_pro"],
  "engine_passiveness": "0.02",
  "schedule_discretion": "0.06",
  "pov_limit": null,
  "pov_target": null,
  "alpha_tilt": "0.00",
  "strategy_params": {
    "max_clip_size": "1000.00"
  },
  "user": "user_123",
  "status": "ACTIVE",
  "active": true,
  "is_simple": false,
  "failure_reason": null,
  "limit_price": null,
  "is_reverse_limit_price": false,
  "time_start": "2023-12-01T10:00:00Z",
  "time_end": "2023-12-01T11:00:00Z",
  "created_at": "2023-12-01T09:59:30Z",
  "updated_at": "2023-12-01T10:30:00Z",
  "fills": [
    {
      "placement_id": "placement_123",
      "exchange": "binance",
      "role": "MAKE",
      "executed_price": "45000.00",
      "executed_qty": "0.125",
      "executed_notional": "5625.00",
      "fee": "2.81",
      "fill_time": "2023-12-01T10:15:00Z"
    },
    {
      "placement_id": "placement_124",
      "exchange": "coinbase_pro",
      "role": "TAKE",
      "executed_price": "45000.00",
      "executed_qty": "0.125",
      "executed_notional": "5625.00",
      "fee": "2.82",
      "fill_time": "2023-12-01T10:30:00Z"
    }
  ]
}

{
    "id": "6debb950-614a-4366-b73b-7d7574fd9e15",
    "buy_token": "ETH",
    "sell_token": "USD",
    "side": "buy",
    "pair": "ETH-USDT",
    "sell_token_amount": 50000.0,
    "strategy": "6fe4ba3e-c578-45bd-824c-c523bf3c56de",
    "super_strategy": "d960c28f-a6bd-4f55-9c5c-fc561cc95640",
    "super_strategy_name": "Impact Minimization",
    "strategy_params": {
        "passive_only": true
    },
    "limit_price": 1.0,
    "start_datetime": "2023-08-08T23:54:06.300319Z",
    "time_end": "2023-08-08T23:59:06.300319",
    "duration": 300,
    "accounts": ["09d3144b-9359-4ec3-8772-2dd1bfb86652"],
    "account_names": ["Binance_1"],
    "user": "2",
    "status": "ACTIVE",
    "engine_passiveness": "0.2",
    "schedule_discretion": "0.08",
    "failure_reason": "",
    "executed_qty": 1.2,
    "executed_price": 1846.5,
    "executed_notional": 2215.8,
    "notes": "",
    "custom_order_id": "",
    "updated_leverage": 10,
    "placements": [
        {
            'id': '6abb7966-9641-4c78-8bd6-f4c9bd075399',
            'created_at': '2023-08-01T08:25:31.704064Z',
            'order': "6debb950-614a-4366-b73b-7d7574fd9e15",
            'placement_type': 'MAKE',
            'price': '28931.15000000000000000000',
            'qty': '0.00000100000000000000',
            'exchange': 'Binance',
            'fills': [
                {
                    "id": "44c82c49-1e9d-43f8-98cd-318a2c01a317",
                    "created_at": '2023-08-01T08:25:31.704064Z',
                    "fill_time": '2023-08-01T08:25:31.704064Z',
                    "role": "MAKE",
                    "external_id": "21949858",
                    "executed_price": 1658.40,
                    "executed_qty": 3.5,
                    "exchange": "Binance",
                    "fee": 0.0443
                },
                //...
            ],
            'passiveness': '0.0078071000',
            'filled': False,
            'external_id': None,
            'status': 'FAILED',
            'sub_status': 'MIN_AMOUNT',
            'is_cross': False,
            'is_simple': False,
            'contract_value': '1.00000000000000000000'
        },
        //...
    ],
}

{
    "message": "Something went wrong"
}

No order found with given ID!

{
    'detail': 'Invalid token.'// Response
}

Response Fields

Field

Type

Description

id

string (UUID)

Unique identifier for the order

parent_order_id

string (UUID) \

null _{Note: ID of the parent multi-order, if applicable}

pair

string

Trading pair symbol

side

string

Order side: buy or sell

status

string

Current order status (e.g., ACTIVE, COMPLETED, CANCELED)

start_datetime

string (ISO 8601)

Order start time in UTC

duration

integer

Order duration in seconds

target_token

string

Token being targeted for the order

target_order_qty

decimal

Total order quantity

remaining_qty

decimal

Remaining quantity to be executed

executed_qty

decimal

Quantity already executed

executed_notional

decimal

Total notional value of executed quantity

exchange_names

array[string]

List of exchanges where the order is being executed

account_names

array[string]

List of account names used for the order

schedule_discretion

decimal

Schedule discretion parameter

engine_passiveness

decimal

Engine passiveness parameter

alpha_tilt

decimal

Alpha tilt parameter

strategy

string \

null _{Note: Super strategy name, if applicable}

trajectory

string

Trading strategy/trajectory name

strategy_params

object

Strategy-specific parameters

participation_rate_target_percent

decimal \

null _{Note: Participation rate target as percentage}

market_type

string

Market type (e.g., spot, perp, option)

failure_reason

string

Reason for order failure, if applicable

limit_price

string

Limit price for the order

placement_live_qty

decimal

Quantity currently in live placements

Get order details by custom ID

To retrieve orders by custom order ID, use the main orders endpoint with the custom_order_ids query parameter:

GET /api/orders/?custom_order_ids={custom_order_id}

Name

Type

Required

Description

custom_order_ids*

string

Yes

Comma-separated list of custom order IDs to filter by

Example Request

GET /api/orders/?custom_order_ids=ETH_ACC_001

Example Response

{
  "orders": [
    {
      "id": "6debb950-614a-4366-b73b-7d7574fd9e15",
      "custom_order_id": "ETH_ACC_001",
      "parent_order_id": null,
      "notes": "ETH accumulation order",
      "pair": "ETH-USDT",
      "side": "buy",
      "exchanges": ["Binance"],
      "buy_token": "ETH",
      "buy_token_amount": 10.5,
      "sell_token": "USDT",
      "sell_token_amount": 17330.25,
      "executed_qty": 0,
      "executed_buy_qty": 0,
      "average_executed_price": null,
      "executed_notional": 0,
      "target_order_qty": 17330.25,
      "target_remaining_qty": 17330.25,
      "target_token": "USDT",
      "target_executed_qty": 0,
      "pct_filled": 0,
      "total_fee": 0,
      "strategy": "TWAP",
      "super_strategy": null,
      "duration": 3600,
      "accounts": ["09d3144b-9359-4ec3-8772-2dd1bfb86652"],
      "account_names": ["my_binance_account"],
      "engine_passiveness": 0.2,
      "schedule_discretion": 0.08,
      "pov_limit": 0.05,
      "pov_target": 0.1,
      "alpha_tilt": 0.1,
      "strategy_params": {
        "passive_only": true
      },
      "user": "2",
      "status": "ACTIVE",
      "active": true,
      "is_simple": false,
      "time_start": "2023-08-08T23:54:06.300319Z",
      "time_end": "2023-08-09T00:54:06.300319Z",
      "limit_price": "1650.50",
      "is_reverse_limit_price": false,
      "placements": [],
      "fills": []
    }
  ],
  "page_number": 1,
  "page_size": 100,
  "num_pages": 1,
  "order_count": 1
}

Path Parameters

[
 {
    "id": "6debb950-614a-4366-b73b-7d7574fd9e15",
    "buy_token": "ETH",
    "sell_token": "USD",
    "side": "buy",
    "pair": "ETH-USDT",
    "sell_token_amount": 50000.0,
    "strategy": "6fe4ba3e-c578-45bd-824c-c523bf3c56de",
    "super_strategy": "d960c28f-a6bd-4f55-9c5c-fc561cc95640",
    "super_strategy_name": "Impact Minimization",
    "strategy_params": {
        "passive_only": true
    },
    "limit_price": 1.0,
    "start_datetime": "2023-08-08T23:54:06.300319Z",
    "time_end": "2023-08-08T23:59:06.300319",
    "duration": 300,
    "accounts": ["09d3144b-9359-4ec3-8772-2dd1bfb86652"],
    "account_names": ["Binance_1"],
    "user": "2",
    "status": "ACTIVE",
    "engine_passiveness": "0.2",
    "schedule_discretion": "0.08",
    "failure_reason": "",
    "executed_qty": 1.2,
    "executed_price": 1846.5,
    "executed_notional": 2215.8,
    "notes": "",
    "custom_order_id": "my_custom_id",
    "updated_leverage": 10,
    "placements": [
        {
            'id': '6abb7966-9641-4c78-8bd6-f4c9bd075399',
            'created_at': '2023-08-01T08:25:31.704064Z',
            'order': "6debb950-614a-4366-b73b-7d7574fd9e15",
            'placement_type': 'MAKE',
            'price': '28931.15000000000000000000',
            'qty': '0.00000100000000000000',
            'exchange': 'Binance',
            'fills': [
                {
                    "id": "44c82c49-1e9d-43f8-98cd-318a2c01a317",
                    "created_at": '2023-08-01T08:25:31.704064Z',
                    "fill_time": '2023-08-01T08:25:31.704064Z',
                    "role": "MAKE",
                    "external_id": "21949858",
                    "executed_price": 1658.40,
                    "executed_qty": 3.5,
                    "exchange": "Binance",
                    "fee": 0.0443
                },
                //...
            ],
            'passiveness': '0.0078071000',
            'filled': False,
            'external_id': None,
            'status': 'FAILED',
            'sub_status': 'MIN_AMOUNT',
            'is_cross': False,
            'is_simple': False,
            'contract_value': '1.00000000000000000000'
        },
        //...
    ],
 },
 {
   //
 },
]

Occurs when:

Missing custom_order_ids parameter
Invalid format for custom_order_ids parameter
Invalid account names in account_names filter
Invalid date format in after or before parameters

Sample Error Messages

{
  "400": {
    "description": "Bad Request",
    "examples": [
      {
        "scenario": "Missing custom_order_ids",
        "response": {
          "error": "custom_order_ids parameter is required"
        }
      },
      {
        "scenario": "Invalid account names",
        "response": {
          "error": "Account display name 'invalid_account' not found for user"
        }
      },
      {
        "scenario": "Invalid date format",
        "response": {
          "message": "Invalid after date format"
        }
      }
    ]
  }
}

Occurs when:

Missing or invalid API token
Token has expired
Insufficient permissions to access the specified accounts

Sample Error Messages

{
  "401": {
    "description": "Unauthorized",
    "examples": [
      {
        "scenario": "Missing API token",
        "response": {
          "detail": "Authentication credentials were not provided."
        }
      },
      {
        "scenario": "Invalid API token",
        "response": {
          "detail": "Invalid token header. No credentials provided."
        }
      },
      {
        "scenario": "Expired token",
        "response": {
          "detail": "Token has expired."
        }
      }
    ]
  }
}

Occurs when:

Database connection issues
External service failures
Unexpected system errors

Sample Error Messages

{
  "500": {
    "description": "Internal Server Error",
    "examples": [
      {
        "scenario": "Database connection error",
        "response": {
          "error": "Database connection failed"
        }
      },
      {
        "scenario": "External service failure",
        "response": {
          "error": "Price feed service unavailable"
        }
      },
      {
        "scenario": "Unexpected system error",
        "response": {
          "error": "Something went wrong"
        }
      }
    ]
  }
}

Get order errors

GET /api/order_errors/

Retrieve order errors and messages for orders. This endpoint returns error messages, warnings, and informational messages associated with orders, organized by order ID.

The response includes:

Order Errors: System-generated errors, warnings, and info messages
Message Types: ERROR, WARN, INFO classifications
Timestamps: When each message was created
Order Association: Messages grouped by order ID

Notes

There are non-error order messages ex with type message_type "INFO" or "WARNING"
There is currently no dedicated /api/order_messages/{id} endpoint. Order messages are included as part of the response in endpoints such as /api/order/{id} and /api/multi_order/{id}

Query Parameters

Name

Type

Description

order_ids

string

Comma-separated list of order UUIDs to filter by (Optional)

Example Request

GET /api/order_errors/?order_ids=6debb950-614a-4366-b73b-7d7574fd9e15,7fecb061-725b-5477-c84c-8e8685ge0f26
Authorization: Bearer <token>

Example Response

{
"6debb950-614a-4366-b73b-7d7574fd9e15": [
{
"message": "Insufficient balance for order execution",
"message_type": "ERROR",
"created_at": "2023-12-01T10:30:00Z"
},
{
"message": "Generating execution schedule",
"message_type": "INFO",
"created_at": "2023-12-01T10:25:00Z"
}
],
"7fecb061-725b-5477-c84c-8e8685ge0f26": [
{
"message": "Order execution completed",
"message_type": "INFO",
"created_at": "2023-12-01T11:00:00Z"
}
]
}

Response Codes

{
  "550e8400-e29b-41d4-a716-446655440000": [
    {
      "message_type": "ERROR",
      "message": "Failed to place order on exchange: insufficient balance",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "message_type": "WARN",
      "message": "Order partially filled due to market conditions",
      "created_at": "2024-01-15T10:25:00Z"
    }
  ],
  "123e4567-e89b-12d3-a456-426614174000": [
    {
      "message_type": "INFO",
      "message": "Order successfully completed",
      "created_at": "2024-01-15T09:45:00Z"
    }
  ]
}

Occurs when:

No order ID provided in the URL path
Invalid UUID format for the order ID

Sample Error Messages

{
  "400": {
    "description": "Invalid request parameters",
    "content": {
      "application/json": {
        "example": {
          "error": "No order ID given!"
        }
      }
    }
  }
}

Occurs when:

The order does not belong to the authenticated user and the user is not a superuser

Sample Error Message

{
  "401": {
    "description": "Unauthorized",
    "content": {
      "application/json": {
        "example": {
          "error": "Order 6debb950-614a-4366-b73b-7d7574fd9e15 does not belong to you"
        }
      }
    }
  }
}

Occurs when:

No order exists with the given ID

Sample Error Message

{
  "404": {
    "description": "Order not found",
    "content": {
      "application/json": {
        "example": {
          "error": "Order 6debb950-614a-4366-b73b-7d7574fd9e15 not found"
        }
      }
    }
  }
}

Notes:

If no order_ids parameter is provided, returns errors for all orders accessible to the user
Response is a dictionary where keys are order IDs and values are arrays of error messages
Messages are sorted by creation time (newest first)
Includes non-error messages with types "INFO" and "WARNING" in addition to "ERROR"

Cancel order

DELETE /api/order/{id}

Cancel order along with all activity on at all venues.

Path Parameters

Name

Type

Description

id*

string

UUID of the order

What Happens When You Cancel an Order

When you cancel an order, the following actions are performed:

Cancel Active Placements: All active placements across all venues are canceled
Update Order Status: Order status is changed to "CANCELED"
Cancel Sibling Orders: If this is a child order in a multi-order, sibling orders are also canceled
Trigger Chain Progression: If this is part of a chained order, chain progression is triggered
Cleanup Tasks: Order cleanup tasks are queued for execution
Analytics: On-complete analytics are scheduled to run
Broadcast Updates: Order cancellation event is broadcast to connected clients
Notifications: Order event notifications are sent
Points & Achievements: Points and achievements are applied based on order performance

Example Request

DELETE /api/order/6debb950-614a-4366-b73b-7d7574fd9e15
Authorization: Bearer <token>

Example Response

"Order canceled!"

Note: The response is a simple string message. If the order was already canceled, the response would be:

"Order already canceled!"

Response Codes

{
  "200": {
    "description": "OK",
    "examples": [
      {
        "scenario": "Order successfully canceled",
        "response": "Order canceled!"
      },
      {
        "scenario": "Order already canceled",
        "response": "Order already canceled!"
      }
    ]
  }
}

Occurs when:

No order ID provided in the URL path
Invalid UUID format for the order ID
Order ID is malformed or contains invalid characters

Sample Error Messages

{
  "400": {
    "description": "Bad Request",
    "examples": [
      {
        "scenario": "No order ID provided",
        "response": "No order ID given!"
      },
      {
        "scenario": "Invalid UUID format",
        "response": "Invalid order ID format"
      }
    ]
  }
}

Occurs when:

Missing or invalid API token
Token has expired
User does not have permission to access the specified order

Sample Error Messages

{
  "401": {
    "description": "Unauthorized",
    "examples": [
      {
        "scenario": "Missing API token",
        "response": {
          "detail": "Authentication credentials were not provided."
        }
      },
      {
        "scenario": "Invalid API token",
        "response": {
          "detail": "Invalid token header. No credentials provided."
        }
      },
      {
        "scenario": "Expired token",
        "response": {
          "detail": "Token has expired."
        }
      },
      {
        "scenario": "Order access denied",
        "response": "Unauthorized"
      }
    ]
  }
}

Occurs when:

Order with the specified ID does not exist
Order has been deleted or is not accessible
Order ID is valid but the order is not found in the database

Sample Error Messages

{
  "404": {
    "description": "Not Found",
    "examples": [
      {
        "scenario": "Order does not exist",
        "response": "No order found with given ID!"
      },
      {
        "scenario": "Order not accessible",
        "response": "Order not found or access denied"
      }
    ]
  }
}

Occurs when:

Order is in a state that prevents cancellation
Failed to cancel active placements on exchanges
Exchange-specific cancellation failures
Database transaction failures during cancellation
Network connectivity issues with exchanges
Order is part of a complex workflow that cannot be interrupted

Sample Error Messages

{
  "422": {
    "description": "Unprocessable Entity",
    "examples": [
      {
        "scenario": "Failed to cancel placements",
        "response": {
          "error": "Failed to cancel all placements"
        }
      },
      {
        "scenario": "Exchange cancellation failure",
        "response": {
          "error": "Unexpected cancel failure"
        }
      },
      {
        "scenario": "Database transaction failure",
        "response": {
          "error": "Failed to commit cancellation changes"
        }
      },
      {
        "scenario": "Network connectivity issue",
        "response": {
          "error": "Connection timeout while canceling placements"
        }
      },
      {
        "scenario": "Order state prevents cancellation",
        "response": {
          "error": "Order is in a state that cannot be canceled"
        }
      }
    ]
  }
}

Occurs when:

Database connection issues
External service failures
Unexpected system errors during cancellation process
Worker queue failures
Analytics service failures

Example Responses

{
  "500": {
    "description": "Internal Server Error",
    "examples": [
      {
        "scenario": "Database connection error",
        "response": {
          "error": "Database connection failed"
        }
      },
      {
        "scenario": "External service failure",
        "response": {
          "error": "Exchange API service unavailable"
        }
      },
      {
        "scenario": "Worker queue failure",
        "response": {
          "error": "Failed to queue cleanup tasks"
        }
      },
      {
        "scenario": "Unexpected system error",
        "response": {
          "error": "Something went wrong"
        }
      }
    ]
  }
}

Notes

Idempotent: Canceling an already canceled order will return a success message
Sibling Orders: Canceling a child order in a multi-order will also cancel sibling orders
Chained Orders: Canceling an order in a chain may trigger progression to the next order
Placement Cancellation: All active placements, including OTC placements, are canceled
Cleanup: Order cleanup happens asynchronously and includes reconciliation of active placements
Analytics: Order analytics are generated 3 minutes after cancellation to ensure all data is collected

Pause order

POST /api/pause_order/

Pause an active order, canceling all active placements and stopping execution until resumed. The order will maintain its current state and can be resumed later.

What Happens When You Pause an Order

When you pause an order, the following actions are performed:

Cancel Active Placements: All active placements across all venues are canceled, including OTC placements
Update Order Status: Order status is changed to "PAUSED"
Set Pause Timestamp: The paused_at timestamp is recorded
Clear Resume Condition: For manual pauses, any resume condition is cleared to prevent automatic resumption
Clear Future Schedule Points: Future schedule points are removed to prevent confusion during resumption
Pause Market Data Collection: Market data collection for the order is paused
Broadcast Updates: Order paused event is broadcast to connected clients
Send Notifications: Order pause event notifications are sent

Path Parameters

Name

Type

Description

order_id

string

UUID of the order

Example Request

POST /api/pause_order/
Authorization: Bearer <token>
Content-Type: application/json

{
  "order_id": "6debb950-614a-4366-b73b-7d7574fd9e15"
}

Example Response

{
  "message": "Successfully paused order."
}

Response Codes

Occurs when:

Order is successfully paused
All active placements are canceled
Order status is updated to "PAUSED"

{
  "202": {
    "description": "Accepted",
    "examples": [
      {
        "scenario": "Order successfully paused",
        "response": {
          "message": "Successfully paused order."
        }
      }
    ]
  }
}

Occurs when:

Missing order_id in request body
Invalid UUID format for the order ID
Order ID is malformed or contains invalid characters

Sample Error Messages

{
  "400": {
    "description": "Bad Request",
    "examples": [
      {
        "scenario": "Missing order_id",
        "response": {
          "error": "Missing required field: order_id"
        }
      },
      {
        "scenario": "Invalid UUID format",
        "response": {
          "error": "Invalid order ID format"
        }
      }
    ]
  }
}

Occurs when:

Missing or invalid API token
Token has expired
User does not have permission to access the specified order

Sample Error Messages

{
  "401": {
    "description": "Unauthorized",
    "examples": [
      {
        "scenario": "Missing API token",
        "response": {
          "detail": "Authentication credentials were not provided."
        }
      },
      {
        "scenario": "Invalid API token",
        "response": {
          "detail": "Invalid token header. No credentials provided."
        }
      },
      {
        "scenario": "Expired token",
        "response": {
          "detail": "Token has expired."
        }
      }
    ]
  }
}

Occurs when:

No order exists with the given ID

Sample Error Message

{ 
"error": "No order found with given ID!" 
}

Occurs when:

Order is not in an active/running state
Order is already paused
Order is completed, canceled, or in another terminal state
Failed to cancel active placements on exchanges
Exchange-specific cancellation failures
Database transaction failures during pause operation
Network connectivity issues with exchanges
Order is part of a complex workflow that cannot be paused

Sample Error Messages

{
  "422": {
    "description": "Unprocessable Entity",
    "examples": [
      {
        "scenario": "Order not running",
        "response": {
          "error": "Order is not running."
        }
      },
      {
        "scenario": "Order already paused",
        "response": {
          "error": "Order is not running."
        }
      },
      {
        "scenario": "Order completed",
        "response": {
          "error": "Order is not running."
        }
      },
      {
        "scenario": "Failed to cancel placements",
        "response": {
          "error": "Failed to cancel all placements"
        }
      },
      {
        "scenario": "Exchange cancellation failure",
        "response": {
          "error": "Unexpected cancel failure"
        }
      },
      {
        "scenario": "Database transaction failure",
        "response": {
          "error": "Failed to commit pause order changes: Database connection failed"
        }
      },
      {
        "scenario": "Network connectivity issue",
        "response": {
          "error": "Failed to commit pause order changes: Connection timeout"
        }
      },
      {
        "scenario": "Order not found",
        "response": {
          "error": "Order not found."
        }
      }
    ]
  }
}

Occurs when:

Database connection issues
External service failures
Unexpected system errors during pause process
Market data service failures
Notification service failures

Sample Error Messages

{
  "500": {
    "description": "Internal Server Error",
    "examples": [
      {
        "scenario": "Database connection error",
        "response": {
          "error": "Database connection failed"
        }
      },
      {
        "scenario": "External service failure",
        "response": {
          "error": "Market data service unavailable"
        }
      },
      {
        "scenario": "Notification service failure",
        "response": {
          "error": "Failed to send pause notification"
        }
      },
      {
        "scenario": "Unexpected system error",
        "response": {
          "error": "Something went wrong"
        }
      }
    ]
  }
}

Notes

Order State Requirement: Only orders with status "ACTIVE" can be paused
Idempotent: Pausing an already paused order will return an error
Placement Cancellation: All active placements, including OTC placements, are canceled during pause
Schedule Preservation: Future schedule points are cleared to prevent confusion during resumption
Manual vs System Pause: Manual pauses clear resume conditions to prevent automatic resumption
Resume Condition: If a resume condition is provided, it will be set for automatic resumption
Market Data: Market data collection is paused to conserve resources
Notifications: Pause notifications are sent to inform users of the order state change

Related Endpoints

Resume Order: POST /api/resume_order/ - Resume a paused order
Pause All Orders: POST /api/pause_all_orders/- Pause all active orders for the user
Pause Multi Order: POST /api/pause_multi_order/ - Pause a multi-order and all its child orders
Pause Chained Order: POST /api/pause_chained_order/ - Pause a chained order

Resume order

POST /api/resume_order/

Resume a previously paused order. This operation will restart order execution, update the order status to "ACTIVE", and trigger the execution workflow.

Path Parameters

Name

Type

Description

order_id

string

UUID of the order

Example Request

POST /api/resume_order/
Authorization: Bearer <token>
Content-Type: application/json

{
  "order_id": "6debb950-614a-4366-b73b-7d7574fd9e15"
}

Example Response

{
  "message": "Successfully resumed order."
}

Response Codes

{
  "202": {
    "description": "Order successfully resumed",
    "content": {
      "application/json": {
        "example": {
          "message": "Successfully resumed order."
        }
      }
    }
  }
}

Occurs when:

The order_id field is missing from the request body
The provided order_id is not a valid UUID

Sample Error Message

{
  "400": {
    "description": "Invalid request parameters",
    "content": {
      "application/json": {
        "example": {
          "error": "Missing required field: order_id"
        }
      }
    }
  }
}

Occurs when:

No order exists with the given order_id

Sample Error Message

{
  "404": {
    "description": "Order not found",
    "content": {
      "application/json": {
        "example": {
          "error": "Order not found."
        }
      }
    }
  }
}

Occurs when:

The order is not in a paused state (cannot be resumed)
There is a failure amending the order schedule
There is a database or internal error during the resume process

Sample Error Message

{
  "422": {
    "description": "Resume operation failed",
    "content": {
      "application/json": {
        "example": {
          "error": "Order is not paused."
        }
      }
    }
  }
}

Amend order

POST /api/amend_order/

Amend an existing order by updating specific fields. This operation allows you to modify order parameters such as quantity, duration, limit price, and POV target while the order is still active.

Request Body

Name

Type

Required

Description

order_id*

string (UUID)

Yes

UUID of the order to amend

changes*

object

Yes

Object containing the fields to update and their new values

Updatable Fields

Field

Type

Description

Constraints

base_asset_qty

number

Base asset quantity (cannot be used with quote_asset_qty)

Must be positive

quote_asset_qty

number

Quote asset quantity (cannot be used with base_asset_qty)

Must be positive

duration

integer

Order duration in seconds

Must be at least 5% more than elapsed time

pov_target

number

Percentage of volume target (0-1)

Must be between 0 and 1

limit_price

string

Limit price for the order

Must be valid price expression

Example Request

POST /api/amend_order/
Authorization: Bearer <token>
Content-Type: application/json

{
  "order_id": "6debb950-614a-4366-b73b-7d7574fd9e15",
  "changes": {
    "duration": 900,
    "limit_price": "51000"
  }
}

Example Response

{
  "message": "Successfully amended order."
}

{
  "202": {
    "description": "Order successfully amended",
    "content": {
      "application/json": {
        "example": {
          "message": "Successfully amended order."
        }
      }
    }
  }
}
    }
  }
}

Occurs when:

The order_id or changes field is missing from the request body
The changes field is not an object
Both base_asset_qty and quote_asset_qty are provided
The provided values are not valid (e.g., non-numeric quantities)

Sample Error Message

{
  "400": {
    "description": "Invalid request parameters",
    "content": {
      "application/json": {
        "example": {
          "error": "Missing required field(s): order_id, changes"
        }
      }
    }
  }
}

Occurs when:

A superuser attempts to amend an order in a retail environment

Sample Error Message

{
  "403": {
    "description": "Superuser on retail cannot place orders",
    "content": {
      "application/json": {
        "example": {
          "error": "Superusers on retail cannot place orders"
        }
      }
    }
  }
}

Occurs when:

No order exists with the given order_id

Sample Error Message

{
  "404": {
    "description": "Order not found",
    "content": {
      "application/json": {
        "example": {
          "error": "Order 6debb950-614a-4366-b73b-7d7574fd9e15 not found"
        }
      }
    }
  }
}

Occurs when:

The order is too close to completion (less than 15 seconds remaining)
The order is a child order (unless in dev mode)
Both base_asset_qty and quote_asset_qty are provided
The new sell_token_amount is less than 5% above executed quantity
The new duration is less than 5% above elapsed time
The new limit_price is invalid
There is a failure updating the order or schedule

Sample Error Message

{
  "422": {
    "description": "Amendment failed",
    "content": {
      "application/json": {
        "example": {
          "error": "Cannot update both base_asset_qty and quote_asset_qty"
        }
      }
    }
  }
}

Occurs when:

Database connection issues
Unexpected server errors during order retrieval

Sample Error Message

{
  "500": {
    "description": "Internal Server Error",
    "examples": [
      {
        "scenario": "Unexpected server error",
        "response": {
          "errors": ["An unexpected error occurred. Please try again later."]
        }
      }
    ]
  }
}

Cancel all orders

POST /api/cancel_all_orders/

Cancel all active orders for the authenticated user. This operation will cancel all orders that are not in a terminated state (excluding COMPLETED, CANCELED, and other final statuses). By default, paused orders are also excluded unless specified otherwise.

Path Parameters

Name

Type

Description

account_names

Comma-separated strings

Optional. List of account names. You pick this name when creating an account under account management. If not provided, all user accounts are considered

Query Parameters

Name

Type

Description

exclude_paused

boolean

Whether to exclude paused orders from cancellations. (Default: true, Optional)

Example Request

POST /api/cancel_all_orders/
Authorization: Bearer <token>
Content-Type: application/json

{
  "account_names": "binance_main,coinbase_pro"
}

Example Response

{
  "message": "Successfully canceled all orders."
}

Response Codes

{
  "200": {
    "description": "Orders successfully canceled or no orders to cancel",
    "content": {
      "application/json": {
        "example": {
          "message": "Successfully canceled all orders."
        }
      }
    }
  }
}

Occurs when:

The account_names field is provided but is not a comma-separated string
There are errors fetching the specified accounts

Sample Error Message

{
  "400": {
    "description": "Invalid request parameters",
    "content": {
      "application/json": {
        "example": {
          "message": "No active orders to cancel. Failed to fetch accounts: ['Account not found: bad_account']"
        }
      }
    }
  }
}

Occurs when:

Some orders could not be canceled due to internal errors
There were failures canceling placements or updating order status
There were errors fetching the specified accounts and some orders failed to cancel

Sample Error Message

{
  "422": {
    "description": "Cancellation failed for some or all orders",
    "content": {
      "application/json": {
        "example": {
          "error": "Canceled 2 orders with 1 failures: ['Failed to cancel order 12345'] Failed to fetch accounts: ['Account not found: bad_account']"
        }
      }
    }
  }
}

Pause all orders

POST /api/pause_all_orders/

Pause all active orders for the authenticated user. This operation will pause all orders with status "ACTIVE" and cancel their active placements. The orders will maintain their current state and can be resumed later.

What Happens When You Pause All OrdersWhen you pause all orders, the following actions are performed for each active order:

Cancel Active Placements: All active placements across all venues are canceled, including OTC placements
Update Order Status: Order status is changed from "ACTIVE" to "PAUSED"
Record Pause Time: The paused_at timestamp is recorded
Clear Resume Condition: Any resume conditions are cleared to prevent automatic resumption
Clear Future Schedule Points: Future schedule points are removed to prevent confusion
Pause Market Data Collection: Market data collection for the order is paused
Send Notifications: Order pause notifications are sent

Request Body

This endpoint does not require any request body parameters.

Example Request

POST /api/pause_all_orders/
Authorization: Bearer <token>
Content-Type: application/json

Example Response

{
  "message": "Successfully paused all orders."
}

Response Codes

{
  "200": {
    "description": "All orders paused successfully",
    "content": {
      "application/json": {
        "example": {
          "message": "Successfully paused all orders."
        }
      }
    }
  }
}

Occurs when:

No active orders to pause, or invalid request parameters (e.g., account not found)

Sample Error Message

{
  "400": {
    "description": "Invalid request parameters",
    "content": {
      "application/json": {
        "example": {
          "message": "No active orders to cancel. Failed to fetch accounts: ['Account not found: bad_account']"
        }
      }
    }
  }
}

Occurs when:

Invalid or missing authentication token
User is not authenticated

Sample Error Message

{
  "401": {
    "description": "Unauthorized",
    "content": {
      "application/json": {
        "example": {
          "error": "Unauthorized"
        }
      }
    }
  }
}

Occurs when:

Some orders failed to pause due to system errors
Orders are in an invalid state for pausing

Sample Error Message

{
  "422": {
    "description": "Unprocessable entity",
    "content": {
      "application/json": {
        "example": {
          "error": "Paused 5 orders with 2 failures: ['order-id-1', 'order-id-2']"
        }
      }
    }
  }
}

Notes

Superuser Access: Superusers can pause all orders across all users
Regular Users: Regular users can only pause their own active orders
Partial Failures: If some orders fail to pause, the response will indicate which orders failed
Order State: Paused orders maintain their current execution state and can be resumed later
No Request Body: This endpoint does not require any request parameters

Related Endpoints

POST /api/resume_all_orders/- Resume all paused orders
POST /api/pause_order/- Pause a single order
POST /api/resume_order/- Resume a single order

Resume all orders

POST /api/resume_all_orders/

Resume all paused single orders for the authenticated user. This operation will resume all orders with status "PAUSED" and restart their execution. Orders will transition back to "ACTIVE" and execution will continue from where they left off.

What Happens When You Resume All Orders

When you resume all orders, the following actions are performed for each paused order:

Update Order Status: Order status is changed from "PAUSED" to "ACTIVE"
Resume Execution: Order execution is restarted from the paused state
Resume Market Data Collection: Market data collection for the order is resumed
Send Notifications: Order resume notifications are sent

Request Body

This endpoint does not require any request body parameters.

Example Request

POST /api/resume_all_orders/
Authorization: Bearer <token>
Content-Type: application/json

Example Response

{
  "message": "Successfully resumed all orders."
}

Response Codes

{
  "200": {
    "description": "All orders resumed successfully",
    "content": {
      "application/json": {
        "example": {
          "message": "Successfully resumed all orders."
        }
      }
    }
  }
}

Occurs when:

No paused orders to resume

{
  "400": {
    "description": "No paused orders to resume",
    "content": {
      "application/json": {
        "example": {
          "message": "No paused orders to resume."
        }
      }
    }
  }
}

Occurs when:

Invalid or missing authentication token
User is not authenticated

Sample Error Message

{
  "401": {
    "description": "Unauthorized",
    "content": {
      "application/json": {
        "example": {
          "error": "Unauthorized"
        }
      }
    }
  }
}

Notes

Superuser Access: Superusers can resume all paused orders across all users
Regular Users: Regular users can only resume their own paused orders
No Request Body: This endpoint does not require any request parameters

Related Endpoints

POST /api/pause_all_orders/- Pause all active orders
POST /api/pause_order/- Pause a single order
POST /api/resume_order/ - Resume a single order

PreviousAPI Reference NextSimple Orders (Market, Limit, IOC, Iceberg)

Last updated 1 month ago

Was this helpful?