Order Management

Complete reference for order management on Liquidity.io. Covers order types, the full order lifecycle, modification and cancellation rules, and accreditation requirements per asset type.

Order Types

Market Orders

Execute immediately at the best available price. Used for public equities, crypto, and retail private securities where real-time pricing is available.

{
  "assetId": "AAPL",
  "side": "BUY",
  "orderType": "market",
  "quantity": 10
}

Routing:

• Public equities route through the broker with 16-venue smart order routing for best execution
• Crypto orders route through fortress.api to BitGo Prime
• Private securities match internally on the ATS

Limit Orders

Execute only at the specified price or better. The order stays open until filled, cancelled, or expired.

{
  "assetId": "AAPL",
  "side": "BUY",
  "orderType": "limit",
  "quantity": 10,
  "limitPrice": 245.00
}

Limit orders sit on the order book until:

• A matching counter-order arrives at the limit price or better
• The user cancels the order
• The order expires (if a time-in-force is set)

Matching priority: FIFO within each price level. Earlier orders at the same price fill first.

Pre-IPO Orders

Interest-based orders for pre-IPO securities. These are non-binding indications of interest that convert to firm orders upon listing.

{
  "assetId": "SPACEX-PRE",
  "side": "BUY",
  "orderType": "market",
  "quantity": 5,
  "isPreIPO": true
}

Pre-IPO orders have special behavior:

• They are stored as indications of interest, not firm orders
• They convert to firm orders when the issuer triggers a listing event
• They are subject to the same accreditation gates as standard orders
• Lockup periods are defined by the issuer and enforced on the resulting positions

Order Lifecycle

CREATE ──> PENDING ──> MATCHED ──> EXECUTED
                │                      │
                │                      └──> PARTIALLY_FILLED ──> EXECUTED
                │
                └──> CANCELLED (by user)
                └──> REJECTED (validation failure)

1. Create

The client submits an order via POST /v1/orders.

Validation checks performed:

If any check fails, the order is rejected with 400 Bad Request and an error code.

2. Pending

The order passes validation and is persisted with status PENDING. At this point:

• The order is visible in the user's order list
• For limit orders, it is placed on the order book
• For market orders, it is immediately sent for execution

3. Matched

The order finds a matching counter-order:

Public equities and crypto:

• Crypto orders are sent to BitGo Prime for execution
• Public equities are routed through the broker to one of 16 execution venues
• The matching engine (Go, Redis) handles internal order book matching

Private securities:

• Matched internally on the ATS
• Both parties must meet accreditation requirements
• FIFO priority within price levels

4. Executed

The order is fully filled. The final state includes:

{
  "orderId": "ord_a1b2c3d4e5f6",
  "assetId": "AAPL",
  "side": "BUY",
  "orderType": "market",
  "quantity": 10,
  "filledQuantity": 10,
  "averagePrice": 249.93,
  "status": "EXECUTED",
  "createdAt": "2026-03-19T00:35:00Z",
  "executedAt": "2026-03-19T00:35:02Z"
}

Partially Filled

For limit orders, partial fills are possible. The order stays open with status PARTIALLY_FILLED until fully filled or cancelled.

{
  "orderId": "ord_a1b2c3d4e5f6",
  "status": "PARTIALLY_FILLED",
  "quantity": 10,
  "filledQuantity": 5,
  "remainingQuantity": 5,
  "averagePrice": 249.90
}

Cancelled

The user cancels the order, or it expires. Only PENDING and PARTIALLY_FILLED orders can be cancelled.

DELETE /v1/orders/{id}
Authorization: Bearer {iam_access_token}
tenant-authorization: {tenant_jwt}

Rejected

The order fails validation and is immediately rejected. Common rejection reasons:

Settlement

Settlement varies by asset type:

Crypto Settlement

1. Order is submitted to BitGo Prime via fortress.api
2. BitGo executes the trade
3. BitGo sends a TRANSFER webhook back to fortress.api
4. fortress.api updates the order status and records the trade via saveCryptoTransaction
5. Trade is saved to the unified trades table for reporting

Equities Settlement

• Public equities: T+1 settlement through the clearing broker
• Private securities (internal match): Immediate settlement on the ATS

Pre-IPO Settlement

• Indications of interest convert to firm orders upon listing
• Subject to issuer-defined lockup periods
• Listing event triggers the conversion and initial settlement

Order Modification

Orders can be modified while in PENDING status:

PUT /v1/orders/{id}
Authorization: Bearer {iam_access_token}
tenant-authorization: {tenant_jwt}
Content-Type: application/json

{
  "quantity": 15,
  "limitPrice": 248.00
}

Modifiable fields:

Modification re-runs all validation checks (accreditation, balance, restrictions). If validation fails, the modification is rejected and the original order remains unchanged.

Partially filled orders cannot be modified. Cancel the existing order and create a new one instead.

Cancellation

DELETE /v1/orders/{id}
Authorization: Bearer {iam_access_token}
tenant-authorization: {tenant_jwt}

Rules:

• Only PENDING orders can be cancelled
• PARTIALLY_FILLED orders can be cancelled (unfilled portion is cancelled)
• EXECUTED, CANCELLED, and REJECTED orders cannot be cancelled
• Cancellation is immediate for limit orders on the internal book
• For orders already sent to BitGo or the broker, cancellation is best-effort

Response:

{
  "data": {
    "orderId": "ord_a1b2c3d4e5f6",
    "status": "CANCELLED",
    "filledQuantity": 0,
    "cancelledAt": "2026-03-19T00:36:00Z"
  },
  "message": "ok"
}

Accreditation Requirements

Every order creation path enforces accreditation checks. The backend checks the buyer's accreditationStatus against the asset's accreditationType.

Accreditation Flow

1. User initiates KYC through Simplici
2. For 506b: user self-certifies accredited status
3. For 506c: Simplici performs third-party income/asset verification
4. accreditationStatus is set to completed on success
5. Every order creation checks the buyer's accreditation status against the asset's accreditationType
6. If the check fails, the order is rejected with 400 Bad Request and error code ACCREDITATION_REQUIRED

Resale Restrictions

Securities acquired under certain regulations have mandatory hold periods before resale.

Lot Tracking

Lots are tracked FIFO with a restriction_end_date:

{
  "assetId": "SPACEX-PRE",
  "lots": [
    {
      "quantity": 5,
      "acquisitionDate": "2025-09-15T00:00:00Z",
      "restrictionEndDate": "2026-09-15T00:00:00Z",
      "isRestricted": true,
      "offeringType": "506c"
    },
    {
      "quantity": 3,
      "acquisitionDate": "2025-03-01T00:00:00Z",
      "restrictionEndDate": "2026-03-01T00:00:00Z",
      "isRestricted": false,
      "offeringType": "506c"
    }
  ]
}

Restricted Sell Orders

When selling securities from a restricted lot:

• The sell order is flagged as isRestrictedOrder=true
• The buyer must be an accredited investor (exemption under Reg D/CF)
• Unrestricted lots can be sold to any investor
• FIFO ordering ensures oldest lots are sold first

SDK Order Management

TypeScript

import { Client } from '@luxfi/trading';

// Market buy
const order = await client.buy('AAPL', 10);

// Limit buy
const limitOrder = await client.limitBuy('AAPL', 10, 245.00);

// Limit sell
const sellOrder = await client.limitSell('BTC-USD', '0.5', '85000');

// Cancel
const cancelled = await client.cancelOrder(order.order_id, 'AAPL', 'liquidity');

// Cancel all orders for a symbol
const allCancelled = await client.cancelAllOrders('BTC-USD');

// List open orders
const openOrders = await client.openOrders('AAPL');
for (const o of openOrders) {
  console.log(`${o.order_id}: ${o.side} ${o.quantity} ${o.symbol} @ ${o.price} [${o.status}]`);
}

Python

from decimal import Decimal

# Market buy
order = await client.buy("AAPL", Decimal("10"))

# Limit buy
limit_order = await client.limit_buy("AAPL", Decimal("10"), Decimal("245.00"))

# Limit sell
sell_order = await client.limit_sell("BTC-USD", Decimal("0.5"), Decimal("85000"))

# Cancel
cancelled = await client.cancel_order(order.order_id, "AAPL", "liquidity")

# Cancel all
all_cancelled = await client.cancel_all_orders("BTC-USD")

# Open orders
open_orders = await client.open_orders("AAPL")
for o in open_orders:
    print(f"{o.order_id}: {o.side} {o.quantity} {o.symbol} @ {o.price} [{o.status}]")