Strategies Quick Start

This walkthrough creates a strategy, validates it with a backtest, deploys it (first as a dry run, then live), subscribes to status updates, and pauses it cleanly.

All requests must be signed — see Authentication. The examples assume $API_KEY, $TS, and $SIG are set per the signing scheme.

1. Create a strategy

Send a POST /v1/strategies with your template, params, and execution context. The strategy is created in draft status.

curl -X POST "https://api.pipai.example/v1/strategies" \
  -H "X-PipAI-API-Key: $API_KEY" \
  -H "X-PipAI-Timestamp: $TS" \
  -H "X-PipAI-Signature: $SIG" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "BTC grid 1h",
    "template_id": "tpl_grid",
    "params": {
      "grid_levels": 8,
      "upper_price": "72000",
      "lower_price": "60000",
      "rebalance_threshold": "0.02"
    },
    "symbols": ["BTCUSDT"],
    "timeframe": "1h",
    "capital": "10000.00",
    "leverage": 3
  }'

The response includes the new strategy id (e.g. strat_8f2a1b) and status: "draft". See Create Strategy for the full schema.

2. Backtest before deploying

Run a backtest against historical data to validate the params before risking capital. Submit a backtest job referencing the strategy_id:

curl -X POST "https://api.pipai.example/v1/backtest/jobs" \
  -H "X-PipAI-API-Key: $API_KEY" \
  -H "X-PipAI-Timestamp: $TS" \
  -H "X-PipAI-Signature: $SIG" \
  -H "Content-Type: application/json" \
  -d '{
    "strategy_id": "strat_8f2a1b",
    "from": "2025-10-01T00:00:00Z",
    "to":   "2026-04-01T00:00:00Z"
  }'

Poll the job until it completes and review the report. See the Backtesting module for full details.

3. Deploy (dry-run, then live)

When the backtest looks good, deploy. We recommend a dry-run first — the engine consumes live market data and emits the same events but does not place real orders.

# Step 3a: dry run
curl -X POST "https://api.pipai.example/v1/strategies/strat_8f2a1b/deploy" \
  -H "X-PipAI-API-Key: $API_KEY" \
  -H "X-PipAI-Timestamp: $TS" \
  -H "X-PipAI-Signature: $SIG" \
  -H "Content-Type: application/json" \
  -d '{ "dry_run": true }'

# Step 3b: pause the dry run, then redeploy live
curl -X POST "https://api.pipai.example/v1/strategies/strat_8f2a1b/pause" \
  -H "X-PipAI-API-Key: $API_KEY" \
  -H "X-PipAI-Timestamp: $TS" \
  -H "X-PipAI-Signature: $SIG" \
  -H "Content-Type: application/json" \
  -d '{}'

curl -X POST "https://api.pipai.example/v1/strategies/strat_8f2a1b/deploy" \
  -H "X-PipAI-API-Key: $API_KEY" \
  -H "X-PipAI-Timestamp: $TS" \
  -H "X-PipAI-Signature: $SIG" \
  -H "Content-Type: application/json" \
  -d '{ "dry_run": false }'

See Deploy Strategy.

4. Subscribe to status updates

Open a WebSocket connection (signed per the auth doc) and send the subscribe frame:

{ "op": "subscribe", "channel": "strategy.status", "id": "strat_8f2a1b" }

You will receive deployed, position_opened, order_filled, position_closed, etc. as they happen. See Strategy Status WebSocket for the full event catalogue.

5. Pause and clean up

When you are done, pause the strategy. Set close_positions: true to flatten open positions at market.

curl -X POST "https://api.pipai.example/v1/strategies/strat_8f2a1b/pause" \
  -H "X-PipAI-API-Key: $API_KEY" \
  -H "X-PipAI-Timestamp: $TS" \
  -H "X-PipAI-Signature: $SIG" \
  -H "Content-Type: application/json" \
  -d '{ "close_positions": true }'

If you no longer need the strategy at all, delete it (only allowed in draft, paused, or stopped states):

curl -X DELETE "https://api.pipai.example/v1/strategies/strat_8f2a1b" \
  -H "X-PipAI-API-Key: $API_KEY" \
  -H "X-PipAI-Timestamp: $TS" \
  -H "X-PipAI-Signature: $SIG"