Algorithmic Orders (VWAP, TWAP, POV)

Algorithmic Orders are advanced strategies that execute trades over a specified period to achieve specific goals, such as minimizing market impact or achieving a target price.

These orders are submitted through the same POST /api/orders/ endpoint but use algorithmic strategy names and a different set of parameters.

General Parameters

The following parameters are used across all algorithmic order types.

Required Fields:

• strategy (string): Must be one of "TWAP", "VWAP", or another supported algorithmic strategy.

• pair (string): The trading pair symbol (e.g., "BTC-USD").

• side (string): The order side, either "buy" or "sell".

• accounts (array of strings): A list of account names to use for the order.

• One of the following quantity fields is required:

  • base_asset_qty (decimal): The amount of the base asset to buy or sell.

  • quote_asset_qty (decimal): The amount of the quote asset to spend or receive.

  • sell_token_amount (decimal): The amount of the token you are selling.

• One of the following execution-time fields is required:

  • duration (integer): The total time in seconds over which to execute the order. Required unless pov_target is provided.

  • pov_target (decimal): The target participation rate as a fraction of market volume (e.g., 0.1 for 10%). If provided, duration is not required.

Optional Fields:

• limit_price (decimal): A price limit for the order. The engine will not execute at prices worse than this limit.

• is_reverse_limit_price (boolean): If true, the engine will only trade at prices worse than the limit_price.

• engine_passiveness (decimal, 0 to 1): Controls how far from the spread the engine places orders. A higher value (e.g., 0.8) is more passive, while a lower value (e.g., 0.1) is more aggressive.

• schedule_discretion (decimal, 0.02 to 0.5): The ratio of order size the engine can deviate from the target schedule, allowing for opportunistic execution.

• alpha_tilt (decimal, -1 to 1): An implied short-term alpha signal. A positive value (e.g., 0.5) front-loads the execution schedule, while a negative value back-loads it.

• pov_limit (decimal, 0 to 1): The maximum fraction of market volume the engine is allowed to participate in at any given time.

• start_datetime (string, ISO 8601 format): A specific time to start the order execution. If not provided, the order starts immediately.

• notes (string): An arbitrary string for personal notes.

• custom_order_id (string): A unique client-side ID for the order (max 64 chars).

---

VWAP (Volume-Weighted Average Price)

Strategy Name: "VWAP"

Specific Parameters: None. A VWAP order uses the general algorithmic parameters.

Example Request

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

{
  "pair": "ETH-USD",
  "side": "sell",
  "accounts": ["coinbase_pro"],
  "strategy": "VWAP",
  "base_asset_qty": "50.0",
  "duration": 14400,
  "alpha_tilt": -0.2
}

Example Response

{
  "id": "f6a7b8c9-d0e1-2345-6789-0abcdef12345",
  "custom_order_id": "",
  "notes": "",
  "pair": "ETH-USD",
  "side": "sell",
  "exchanges": ["coinbase_pro"],
  "buy_token": "USD",
  "sell_token": "ETH",
  "sell_token_amount": "50.0",
  "strategy": "VWAP",
  "duration": 14400,
  "alpha_tilt": -0.2,
  "status": "ACTIVE",
  "user": "user_789",
  "created_at": "2024-01-11T12:00:00Z",
  "updated_at": "2024-01-11T12:00:03Z"
}

---

TWAP (Time-Weighted Average Price)

Strategy Name: "TWAP"

Specific Parameters: None. A TWAP order uses the general algorithmic parameters, with duration being the key component.

Example Request

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

{
  "pair": "BTC-USD",
  "side": "buy",
  "accounts": ["binance_main"],
  "strategy": "TWAP",
  "base_asset_qty": "1.5",
  "duration": 7200,
  "limit_price": "46000.00",
  "engine_passiveness": 0.5,
  "schedule_discretion": 0.1
}

Example Response

{
  "id": "e5f6a7b8-c9d0-1234-5678-90abcdef1234",
  "custom_order_id": "",
  "notes": "",
  "pair": "BTC-USD",
  "side": "buy",
  "exchanges": ["binance"],
  "buy_token": "BTC",
  "buy_token_amount": "1.5",
  "sell_token": "USD",
  "strategy": "TWAP",
  "duration": 7200,
  "limit_price": "46000.00",
  "engine_passiveness": 0.5,
  "schedule_discretion": 0.1,
  "status": "ACTIVE",
  "user": "user_789",
  "created_at": "2024-01-11T10:00:00Z",
  "updated_at": "2024-01-11T10:00:05Z"
}

---

POV (Percentage of Volume)

A POV (or participation rate) strategy executes an order by targeting a certain percentage of the market volume.

Strategy Name: "POV" or any other algorithmic strategy name.

Specific Parameters:

• pov_target (decimal, required): The target participation rate (e.g., 0.1 for 10%).

• pov_limit (decimal, optional): A cap on the participation rate to prevent overly aggressive trading during volume spikes.

When pov_target is used, the duration parameter is not required, as the order's duration will be calculated based on how long it will take to fill the order at the target participation rate.

Example Request

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

{
  "pair": "SOL-USD",
  "side": "buy",
  "accounts": ["ftx_us"],
  "strategy": "TWAP",
  "base_asset_qty": "2000.0",
  "pov_target": "0.05",
  "pov_limit": "0.1"
}

Example Response

{
  "id": "a7b8c9d0-e1f2-3456-7890-bcdef1234567",
  "custom_order_id": "",
  "notes": "",
  "pair": "SOL-USD",
  "side": "buy",
  "exchanges": ["ftx_us"],
  "buy_token": "SOL",
  "buy_token_amount": "2000.0",
  "sell_token": "USD",
  "strategy": "TWAP",
  "pov_target": "0.05",
  "pov_limit": "0.1",
  "status": "ACTIVE",
  "user": "user_789",
  "created_at": "2024-01-11T14:00:00Z",
  "updated_at": "2024-01-11T14:00:04Z"
}