Derivatives Migration

This route provides an endpoint for migrating legacy derivatives to the new derivative model with underlying assets.

Migrate derivatives

POST /v1/derivatives/migration migrates legacy derivatives based on filter criteria.

The migration process:

• Identifies derivatives matching the provided criteria
• Creates underlying asset entities for each unique underlying security
• Links the derivatives to their corresponding underlying assets
• Returns a summary of successful migrations, ignored nodes, and any errors

Request body

The request accepts one or more filter criteria to identify which derivatives to migrate.

Filter types

underlying_node: Filter derivatives by their underlying financial graph node ID.

{
  "criteria": [
    {
      "type": "underlying_node",
      "value": 200
    }
  ]
}

node_type: Filter derivatives by their node type (e.g., forward contracts, options).

{
  "criteria": [
    {
      "type": "node_type",
      "value": "FORWARD_CONTRACT"
    }
  ]
}

Multiple criteria

Multiple criteria can be combined. The migration will process all derivatives matching all of the provided criteria.

{
  "criteria": [
    {
      "type": "underlying_node",
      "value": 200
    },
    {
      "type": "node_type",
      "value": "STRUCTURED_PRODUCT"
    }
  ]
}

Responses

• 200 OK: success

{
  "node_count": 5,
  "nodes_migrated_count": 3,
  "nodes_migrated": [1001, 1002, 1003],
  "ignore_summaries": [
    {
      "ignore_reason_message": "Derivative already migrated",
      "affected_node_count": 1,
      "affected_node_ids": ["1004"]
    }
  ],
  "error_summaries": [
    {
      "error_message": "Missing required underlying asset information",
      "affected_node_count": 1,
      "affected_node_ids": ["1005"]
    }
  ]
}

Response fields:

• node_count: Total number of nodes evaluated for migration
• nodes_migrated_count: Number of nodes successfully migrated
• nodes_migrated: Array of node IDs that were successfully migrated
• ignore_summaries: Array of summaries for nodes that were intentionally skipped
  • ignore_reason_message: Explanation of why nodes were ignored
  • affected_node_count: Number of nodes affected by this ignore reason
  • affected_node_ids: Array of node IDs that were ignored for this reason
• error_summaries: Array of summaries for nodes that encountered errors
  • error_message: Description of the error
  • affected_node_count: Number of nodes affected by this error
  • affected_node_ids: Array of node IDs that encountered this error
• 400 Bad Request: invalid payload (e.g., missing required fields, invalid filter criteria)
• 403 Forbidden: not permitted to make the request

Downgrade derivatives

POST /v1/derivatives/migration/downgrade reverts derivatives from the new derivative model back to legacy format.

The downgrade process:

• Identifies new derivatives matching the provided criteria (or all new derivatives if no criteria provided)
• Sets isNewDerivative to false on each derivative
• Deletes underlying asset relationships
• Returns a summary of downgraded nodes and deleted relationships

Request body

The request accepts optional filter criteria to identify which derivatives to downgrade. If no criteria are provided, all new derivatives will be downgraded.

Filter types

node_type: Filter derivatives by their node type (e.g., forward contracts, options).

{
  "criteria": [
    {
      "type": "node_type",
      "value": "OPTION"
    }
  ]
}

No criteria: Downgrade all new derivatives.

{
  "criteria": []
}

Restrictions

The underlying_node filter is not supported for downgrade operations and will result in a 400 Bad Request error. Underlying node relationships are specific to the new derivative model and are deleted during downgrade.

Responses

• 200 OK: success

{
  "node_count": 3,
  "nodes_downgraded": [2001, 2002, 2003],
  "relationships_deleted": 3
}

Response fields:

• node_count: Number of derivatives downgraded
• nodes_downgraded: Array of node IDs that were downgraded
• relationships_deleted: Number of underlying asset relationships deleted
• 400 Bad Request: invalid payload (e.g., underlying_node filter used, invalid filter criteria)
• 403 Forbidden: not permitted to make the request