Skip to navigation
HTTP APIAPI Domains

Trading

Order management, trade execution, and OTC workflows

Trading Domain

The trading domain handles order management, trade execution, and OTC workflows.

Trading Venues

VenueDescriptionOrder Types
ExchangeCentral limit order bookLimit, Market
OTCRequest-for-quote with external dealers (PRIME acts as intermediary)RFQ, Limit, Market, TWAP, Stop*, Stop Limit*

*Stop and Stop Limit orders are created by adding stopParams to a Limit or Market order. See OTC Trading.

Order Lifecycle

PENDING → OPEN → [PARTIALLY_FILLED] → FILLED
            │         │
            └─────────└─→ CANCELLED

Key Concepts

Pair Constraints

Every order must respect the pair’s constraints:

ConstraintDescription
minOrderQuantityMinimum order size
maxOrderQuantityMaximum order size
quantityTicksMinimum quantity increment
priceTicksMinimum price increment

Side

ValueDescription
SIDE_BUYPurchase base instrument
SIDE_SELLSell base instrument

Exchange Trading

Exchange trading uses a central limit order book where orders are matched automatically.

Exchange Order Types

ValueDescription
TYPE_LIMITExecute at specified price or better
TYPE_MARKETExecute immediately at best available
TYPE_POST_ONLYAdd liquidity only (rejected if would match)

Exchange Time in Force

ValueDescription
TIME_IN_FORCE_DAYCancel at end of trading day
TIME_IN_FORCE_GTCGood ‘til cancelled
TIME_IN_FORCE_IOCImmediate or cancel
TIME_IN_FORCE_FOKFill or kill (all or nothing)

Exchange Endpoints

All endpoints below are relative to /api/rest/v1.

EndpointMethodDescription
/ordersPOSTCreate order
/orders/by-sub-account/{subAccountId}GETList orders for sub-account
/orders/by-sub-account/{subAccountId}/{id}GETOrder details
/orders/by-sub-account/{subAccountId}/{orderId}DELETECancel order
/orders/by-sub-account/{subAccountId}/by-pair/{pairId}DELETECancel all orders for pair
/tradesGETTrade history (filter by subAccountId query param)
/trades/{id}GETGet specific trade by ID
/marketplace/tradesGETAnonymized public trades

Exchange Order Request Schema

Exchange Orders Only

The following request schema applies to Exchange orders (POST /orders). For OTC order schemas, see OTC Trading.

Required Fields

FieldTypeDescription
clientOrderIdstringUnique identifier generated by the client (max 36 chars, UUID format recommended)
subAccountIdUUIDSub-account the order belongs to
symbolstringPair symbol (e.g., “BTC/CHF”)
sideenumSIDE_BUY or SIDE_SELL
typeenumTYPE_LIMIT, TYPE_MARKET, or TYPE_POST_ONLY
quantitydecimalMaximum quantity to fill
minQuantitydecimalMinimum quantity per fill
pricedecimalLimit price (required for LIMIT orders)
timeInForceenumTIME_IN_FORCE_DAY, TIME_IN_FORCE_GTC, TIME_IN_FORCE_IOC, TIME_IN_FORCE_FOK
transactTimetimestampClient transaction time (ISO 8601 format)

Order Request Example

{
  "clientOrderId": "9739d2bf-ddb3-4458-ab1f-98eb63279fb0",
  "subAccountId": "7376524e-6b6b-4137-9719-7e07a7709804",
  "symbol": "BTC/CHF",
  "side": "SIDE_BUY",
  "type": "TYPE_LIMIT",
  "quantity": "1.5",
  "minQuantity": "0.001",
  "price": "45000.00",
  "timeInForce": "TIME_IN_FORCE_DAY",
  "transactTime": "2024-01-15T10:30:00Z"
}

Dry-Run Mode

To validate an order without actually placing it, set dry: true in the request:

{
  "clientOrderId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "subAccountId": "7376524e-6b6b-4137-9719-7e07a7709804",
  "symbol": "BTC/CHF",
  "side": "SIDE_BUY",
  "type": "TYPE_LIMIT",
  "quantity": "1.5",
  "minQuantity": "0.001",
  "price": "45000.00",
  "timeInForce": "TIME_IN_FORCE_DAY",
  "transactTime": "2024-01-15T10:30:00Z",
  "dry": true
}

Dry-run mode performs all validation checks (balance, constraints, permissions) without creating the order. Use this to verify orders before submission.

Exchange Order Response Schema

When creating or retrieving an order, the response contains the full order object:

{
  "result": {
    "id": "2312bb39-a624-4785-aaf7-49b09034b560",
    "subAccountId": "7376524e-6b6b-4137-9719-7e07a7709804",
    "clientAccountId": "8aee564e-2eb1-4a57-b686-05476c2cfd93",
    "userId": "c43f7356-ad91-48bf-b647-96aa3ec59cf2",
    "pairId": "7a3fae7e-5a17-4931-821c-54b021f643da",
    "clientOrderId": "my-order-123",
    "side": "SIDE_BUY",
    "quantity": "1.5",
    "minQuantity": "0.001",
    "executedQuantity": "0",
    "reservedFunds": "67500.00",
    "price": "45000.00",
    "status": "STATUS_NEW",
    "type": "TYPE_LIMIT",
    "symbol": "BTC/CHF",
    "timeInForce": "TIME_IN_FORCE_DAY",
    "transactTime": "2024-01-15T10:30:00Z",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}

Order Fields

FieldTypeDescription
idUUIDUnique order identifier
subAccountIdUUIDSub-account the order belongs to
clientAccountIdUUIDClient account ID
userIdUUIDUser who created the order
pairIdUUIDTrading pair ID
clientOrderIdstringClient-provided unique identifier
sideenumSIDE_BUY or SIDE_SELL
quantitydecimalMaximum quantity to fill
minQuantitydecimalMinimum quantity per fill
executedQuantitydecimalQuantity already executed
reservedFundsdecimalFunds reserved for the order (null if not applicable)
pricedecimalLimit price (for LIMIT orders)
statusenumOrder status (see below)
typeenumTYPE_LIMIT, TYPE_MARKET, TYPE_POST_ONLY
symbolstringPair symbol (may be empty for legacy orders)
timeInForceenumOrder duration policy
clientCreationTimetimestampClient-side creation time
transactTimetimestampServer transaction time (null if not yet processed)
createdAttimestampOrder creation time
updatedAttimestampLast update time
averagePricedecimalAverage fill price (null until partially/fully filled)
rejectionCausestringReason for rejection (empty if not rejected)
reservedTransactionFeedecimalReserved transaction fee (null if not applicable)
reservedSwissStampTaxdecimalReserved Swiss stamp tax (null if not applicable)
settleInstrumentIdUUIDSettlement instrument ID (null if not applicable)

Order Status Values

StatusDescription
STATUS_PENDINGOrder submitted, awaiting processing
STATUS_NEWOrder accepted, on order book
STATUS_PARTIALLY_FILLEDSome quantity executed
STATUS_FILLEDFully executed
STATUS_CANCELEDCanceled by user or system
STATUS_REJECTEDRejected (see rejectionCause)
STATUS_REPLACEDReplaced by another order

Time in Force Values

ValueDescription
TIME_IN_FORCE_DAYCancel at end of trading day
TIME_IN_FORCE_GTCGood ‘til cancelled
TIME_IN_FORCE_IOCImmediate or cancel
TIME_IN_FORCE_FOKFill or kill (all or nothing)

Exchange Order List Filtering

When listing orders via GET /orders/by-sub-account/{subAccountId}, the response is paginated. See Making Requests for pagination details.

Available Filters

FilterDescription
statusFilter by order status
typeFilter by order type
time_in_forceFilter by time in force
pair_idFilter by trading pair
created_afterOrders created after date
created_beforeOrders created before date

Sorting

Sort KeyDescription
created_at-ascOldest first
created_at-descNewest first (default)

OTC Trading

OTC (Over-the-Counter) trading enables trades with external dealers where PRIME acts as an intermediary. OTC trading offers two distinct approaches:

MethodProtocolUse Case
RFQ (Request for Quote)WebSocketReal-time quote negotiation with dealers
OTC OrdersRESTDirect limit, market, TWAP, or stop order placement

OTC Trading Methods

RFQ (Request for Quote)

RFQ is a real-time WebSocket workflow for negotiating quotes with external dealers. The investor requests quotes, dealers respond with prices, and the investor can accept a quote to execute the trade.

For complete RFQ documentation including WebSocket message formats and workflows, see RFQ (Request for Quote).

Field Naming Convention

RFQ WebSocket messages use PascalCase field names (RfqID, Quantity, Token), while OTC REST endpoints use camelCase (pairId, quantity).

OTC Orders

OTC Orders use the REST API for placing orders that execute with external dealers. Unlike Exchange orders, OTC orders support additional order types like TWAP (Time-Weighted Average Price) and can include scheduling parameters.

For complete OTC order schemas and workflows, see OTC Trading Use Case.

OTC Endpoints

All endpoints below are relative to /api/rest/v1.

EndpointMethodDescription
/otc/orders/by-sub-account/{subAccountId}GETList OTC orders
/otc/orders/by-sub-account/{subAccountId}/{orderId}GETOTC order details
/otc/ordersPOSTCreate OTC order
/otc/orders/by-sub-account/{subAccountId}/{orderId}DELETECancel OTC order
/otc/trades/by-sub-account/{subAccountId}GETOTC trades
/otc/listings/{pairId}GETOTC listing for pair
/quotes/by-sub-account/{subAccountId}GETAccepted RFQ quotes

Balance Impact

When placing orders:

  1. Buy Order: Quote currency reserved (price × quantity)
  2. Sell Order: Base currency reserved (quantity)

Reserved funds become available again if order is cancelled.

WebSocket Events

Exchange WebSocket Topics

TopicEvents
{id}@subaccount-ordersExchange order updates
{pair}@tradesPublic trades (Exchange)
{pair}@depth@{speed}Order book (speed: 100ms, 1000ms)

OTC WebSocket Topics

OTC trading uses WebSocket for the RFQ workflow. See RFQ (Request for Quote) for complete WebSocket message formats.