Strategy Versions

A strategy version represents a snapshot of a strategy's target portfolio composition. When a version is executed, it triggers a rebalance that generates orders to align the portfolio with the new target weights. On this page, we'll cover how to view, execute, and delete strategy versions.

The strategy version model

Properties

Name
id
Type
string
Description
Unique identifier for the strategy version (UUID).
Name
strategy_id
Type
string
Description
The ID of the parent strategy (UUID).
Name
cash_weight
Type
string
Description
The target cash weight as a decimal string (e.g., "5.0").
Name
old_cash_weight
Type
string
Description
The previous cash weight before this version was created.
Name
scheduled_for
Type
timestamp | null
Description
When the version is scheduled for execution, or null if not scheduled.
Name
status
Type
string | null
Description
The status of the associated rebalance. null if no rebalance has been initiated. Possible values: "SCHEDULED", "PENDING", "CREATING_ORDERS", "IN_PROGRESS", "CANCELLED", "COMPLETE", "FAILED".
Name
executed_at
Type
timestamp | null
Description
ISO 8601 timestamp of when the version was executed, or null if not yet executed.
Name
inserted_at
Type
timestamp
Description
ISO 8601 timestamp of when the version was created.
Name
orders
Type
array
Description
The orders generated by the rebalance. Only present when requested via ?include=orders.
Name
positions
Type
array
Description
The version's target positions with weight changes. Only present when requested via ?include=positions.

Order properties

When ?include=orders is specified, each order contains:

Name
id
Type
string
Description
Unique identifier for the order (UUID).
Name
date
Type
string
Description
The order date in YYYY-MM-DD format.
Name
side
Type
string
Description
The order side: "BUY" or "SELL".
Name
symbol
Type
string
Description
The ticker symbol of the security (e.g., "NVDA").
Name
status
Type
string
Description
The order status. Possible values: "PENDING", "IGNORED", "SENT", "FILLED", "FAILED".
Name
status_reason
Type
string | null
Description
Additional context for the order status, if applicable.
Name
order_quantity
Type
string
Description
The requested quantity as a decimal string.
Name
order_value
Type
string
Description
The estimated order value as a decimal string.
Name
filled_quantity
Type
string
Description
The filled quantity as a decimal string.
Name
filled_value
Type
string
Description
The total filled value as a decimal string.
Name
filled_average_price
Type
string
Description
The average fill price as a decimal string.
Name
inserted_at
Type
timestamp
Description
ISO 8601 timestamp of when the order was created.
Name
updated_at
Type
timestamp
Description
ISO 8601 timestamp of when the order was last updated.

Version position properties

When ?include=positions is specified, each position contains:

Name
id
Type
string
Description
Unique identifier for the version position (UUID).
Name
symbol
Type
string
Description
The ticker symbol of the security (e.g., "NVDA").
Name
old_weight
Type
string
Description
The previous target weight as a decimal string (e.g., "0").
Name
weight
Type
string
Description
The new target weight as a decimal string (e.g., "10.0").
Name
action
Type
string
Description
The position action. Possible values: "ADD", "CHANGE", "REMOVE", "IGNORE".

GET/api/v1/strategies/{strategy_id}/versions/{id}

Retrieve a strategy version

Retrieves a single strategy version by ID. The version must belong to a strategy within the API client's organization.

Required scope: strategy_versions:read

Path parameters

Name
strategy_id
Type
string
Description
The ID of the parent strategy (UUID).
Name
id
Type
string
Description
The ID of the strategy version to retrieve (UUID).

Query parameters

Name
include
Type
string
Description
Comma-separated list of associations to include. Allowed values: orders, positions.

Request

GET

/api/v1/strategies/{strategy_id}/versions/{id}

curl "https://app.addigence.com/api/v1/strategies/019d6f6a-9be4-7d69-a04c-91912a8b9100/versions/019d7a2b-c3d4-7e56-b789-01234abcdef0?include=orders,positions" \
  -H "Authorization: Bearer {token}"

Response

{
  "data": {
    "id": "019d7a2b-c3d4-7e56-b789-01234abcdef0",
    "strategy_id": "019d6f6a-9be4-7d69-a04c-91912a8b9100",
    "cash_weight": "5.0",
    "old_cash_weight": "10.0",
    "scheduled_for": null,
    "status": "COMPLETE",
    "executed_at": "2025-03-10T14:30:00.000000Z",
    "inserted_at": "2025-03-10T14:28:00.000000Z",
    "orders": [
      {
        "id": "019d7a2b-d5e6-7f78-c901-23456bcdef01",
        "date": "2025-03-10",
        "side": "BUY",
        "symbol": "NVDA",
        "status": "FILLED",
        "status_reason": null,
        "order_quantity": "10",
        "order_value": "1500.00",
        "filled_quantity": "10",
        "filled_value": "1490.50",
        "filled_average_price": "149.05",
        "inserted_at": "2025-03-10T14:30:00.000000Z",
        "updated_at": "2025-03-10T14:35:00.000000Z"
      }
    ],
    "positions": [
      {
        "id": "019d7a2b-e7f8-7a90-d012-34567cdef012",
        "symbol": "NVDA",
        "old_weight": "0",
        "weight": "10.0",
        "action": "ADD"
      },
      {
        "id": "019d7a2b-e7f8-7a90-d012-34567cdef013",
        "symbol": "GOOG",
        "old_weight": "15.0",
        "weight": "12.5",
        "action": "CHANGE"
      }
    ]
  }
}

POST/api/v1/strategies/{strategy_id}/versions/execute

Execute a strategy version

Creates a new strategy version with the specified positions and immediately executes it, triggering a rebalance that generates orders.

Required scopes: strategy_versions:create and strategy_versions:execute

The response returns 202 Accepted with a Location header pointing to the created version's show endpoint.

If you try to execute a strategy version, and there are is an existing unexecuted one, you will need to delete that one, before you can create and execute a new one.

Path parameters

Name
strategy_id
Type
string
Description
The ID of the strategy to create the version for (UUID).

Request body

Name
data
Type
object
Description
Wrapper object containing the version data.
Name
data.positions
Type
array
Description
Array of position objects defining the target portfolio composition. Each position must have a symbol (ticker string) and weight (target weight as a decimal string).

Error responses

Name
422 — Unknown symbols
Description
One or more ticker symbols in the request do not exist in the system. The error response lists the unknown symbols.
Name
422 — Version already executed
Description
Returned when there is a conflict with an already-executed version.

Request

POST

/api/v1/strategies/{strategy_id}/versions/execute

curl -X POST https://app.addigence.com/api/v1/strategies/019d6f6a-9be4-7d69-a04c-91912a8b9100/versions/execute \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "positions": [
        {"symbol": "NVDA", "weight": "10.0"},
        {"symbol": "GOOG", "weight": "12.5"},
        {"symbol": "AAPL", "weight": "15.0"}
      ]
    }
  }'

Response

{
  "data": {
    "id": "019d7a2b-c3d4-7e56-b789-01234abcdef0",
    "strategy_id": "019d6f6a-9be4-7d69-a04c-91912a8b9100",
    "cash_weight": "62.5",
    "old_cash_weight": "100.0",
    "scheduled_for": null,
    "status": "PENDING",
    "executed_at": "2025-03-10T14:30:00.000000Z",
    "inserted_at": "2025-03-10T14:30:00.000000Z",
    "orders": [
      {
        "id": "019d7a2b-d5e6-7f78-c901-23456bcdef01",
        "date": "2025-03-10",
        "side": "BUY",
        "symbol": "NVDA",
        "status": "PENDING",
        "status_reason": null,
        "order_quantity": "10",
        "order_value": "1500.00",
        "filled_quantity": null,
        "filled_value": null,
        "filled_average_price": null,
        "inserted_at": "2025-03-10T14:30:00.000000Z",
        "updated_at": "2025-03-10T14:30:00.000000Z"
      }
    ],
    "positions": [
      {
        "id": "019d7a2b-e7f8-7a90-d012-34567cdef012",
        "symbol": "NVDA",
        "old_weight": "0",
        "weight": "10.0",
        "action": "ADD"
      },
      {
        "id": "019d7a2b-e7f8-7a90-d012-34567cdef013",
        "symbol": "GOOG",
        "old_weight": "0",
        "weight": "12.5",
        "action": "ADD"
      },
      {
        "id": "019d7a2b-e7f8-7a90-d012-34567cdef014",
        "symbol": "AAPL",
        "old_weight": "0",
        "weight": "15.0",
        "action": "ADD"
      }
    ]
  }
}

The response includes a Location header: /api/v1/strategies/019d6f6a-.../versions/019d7a2b-...?include=orders,positions

DELETE/api/v1/strategies/{strategy_id}/versions/{id}

Delete a strategy version

Deletes a strategy version that has not been executed. Executed versions cannot be deleted.

Required scope: strategy_versions:delete

Returns 204 No Content on success with an empty response body.

Path parameters

Name
strategy_id
Type
string
Description
The ID of the parent strategy (UUID).
Name
id
Type
string
Description
The ID of the strategy version to delete (UUID).

Error responses

Name
404 — Not found
Description
The version does not exist or belongs to a different organization.
Name
422 — Already executed
Description
The version has already been executed and cannot be deleted.

Request

DELETE

/api/v1/strategies/{strategy_id}/versions/{id}

curl -X DELETE https://app.addigence.com/api/v1/strategies/019d6f6a-9be4-7d69-a04c-91912a8b9100/versions/019d7a2b-c3d4-7e56-b789-01234abcdef0 \
  -H "Authorization: Bearer {token}"

Response (204 No Content)

# Empty response body