Order Splitter API

A REST API for robo-advisors to split a total investment amount across a model portfolio. Given a portfolio (symbols and weights) and an amount, the API returns the amount and quantity per stock and when to execute (markets open Monday–Friday).

Execution instructions

Prerequisites

• Node.js 18+
• npm

Install and run

npm install
npm run build
npm run start

For development with watch mode:

npm run start:dev

The API listens on http://localhost:3000 (override with PORT). Swagger UI is at http://localhost:3000/api.

Environment (optional)

Variable	Description	Default
PORT	HTTP port	3000
SHARE_QUANTITY_DECIMAL_PLACES	Max decimal places for share quantity (0–10)	3

Copy .env.example to .env to override.

---

API overview

Method	Path	Description
POST	/orders	Split an order: send model portfolio + amount; get breakdown and execution time
GET	/orders	List historic split orders (in-memory; lost on restart)

All request/response bodies are JSON.

---

Request examples

Split order (BUY)

Request

curl -X POST http://localhost:3000/orders \
  -H "Content-Type: application/json" \
  -d '{
    "modelPortfolio": [
      { "symbol": "AAPL", "weight": 0.6 },
      { "symbol": "TSLA", "weight": 0.4 }
    ],
    "amount": 100,
    "orderType": "BUY"
  }'

Response (example)

{
  "lineItems": [
    { "symbol": "AAPL", "amount": 60, "quantity": 0.6, "executeAt": "2025-02-24T14:30:00.000Z" },
    { "symbol": "TSLA", "amount": 40, "quantity": 0.4, "executeAt": "2025-02-24T14:30:00.000Z" }
  ],
  "orderType": "BUY",
  "totalAmount": 100,
  "executeAt": "2025-02-24T14:30:00.000Z"
}

• Weights must sum to 1 (e.g. 0.6 + 0.4).
• amount is in USD.
• orderType is BUY or SELL.
• executeAt is the next market open (Mon–Fri) at 14:30 UTC (09:30 US Eastern).

Optional: partner-provided prices

If the partner sends a price per symbol, it overrides the default $100:

{
  "modelPortfolio": [
    { "symbol": "AAPL", "weight": 0.6, "price": 175.50 },
    { "symbol": "TSLA", "weight": 0.4, "price": 245.00 }
  ],
  "amount": 1000,
  "orderType": "BUY"
}

Historic orders

curl http://localhost:3000/orders

Returns an array of previously split orders, each with id, createdAt, and the same shape as the split response.

---

Dependencies and framework

• NestJS – Node.js framework (modules, DI, pipes, interceptors).
• TypeScript – Typed implementation.
• class-validator / class-transformer – Request validation and transformation.
• @nestjs/swagger – OpenAPI (Swagger) docs and UI.
• @nestjs/config – Environment/config (e.g. SHARE_QUANTITY_DECIMAL_PLACES).

---

Performance and behaviour

• Response time: Each request is logged to the console with duration in milliseconds (e.g. POST /orders - 12ms).
• Decimal places: Share quantities are rounded to the number of decimal places set by SHARE_QUANTITY_DECIMAL_PLACES (default 3; configurable for future support of more precision, e.g. 7).

---

Production-style improvements (and why they help)

1. Global validation pipe – Strips unknown fields and validates types so invalid or unexpected input is rejected early and consistently.
2. Structured logging interceptor – Logs method, path, and response time for every request to support performance monitoring and debugging.
3. Configurable share precision – Decimal places for quantities are read from config so the same code can support different exchange/regulatory rules without code changes.
4. RESTful design – POST /orders to create a split, GET /orders for history; clear semantics and easy to add more resources (e.g. GET /orders/:id) later.
5. Swagger – Interactive docs and try-it-out reduce integration time and keep API contract visible.

See ANSWERS for approach, assumptions, and production migration notes.