Creating Scenarios¶

A scenario is a container for one or more hypothetical trades that you want to simulate against your portfolio. This guide covers everything you need to know about creating and organizing scenarios.

What Is a Scenario?¶

A scenario represents a "snapshot" of your portfolio with proposed changes applied. It includes:

• Base Portfolio: Your current holdings (from a workbook or sample data)
• Proposed Trades: One or more buy/sell actions to simulate
• Simulation Results: Compliance test outcomes after trades are applied
• Metadata: Name, description, status, and audit information

erDiagram
    SCENARIO ||--o{ TRADE : contains
    SCENARIO ||--o{ RESULT : generates
    SCENARIO }|--|| WORKBOOK : references

    SCENARIO {
        uuid id
        string name
        string description
        string status
        uuid base_workbook_id
        datetime created_at
    }
    TRADE {
        uuid id
        string trade_type
        string cusip
        decimal par_value
        string rating
    }
    RESULT {
        uuid id
        string test_name
        decimal current_value
        decimal projected_value
        string impact_direction
    }

Scenario Lifecycle¶

Every scenario progresses through these states:

stateDiagram-v2
    [*] --> draft: Create Scenario
    draft --> calculating: Run Simulation
    calculating --> completed: Success
    calculating --> failed: Error
    completed --> [*]: Delete
    failed --> draft: Modify & Retry
    failed --> [*]: Delete

Creating a Scenario via UI¶

Step 1: Navigate to Scenarios¶

From the CalcBridge dashboard, click "Scenarios" in the main navigation or use the quick access card.

Step 2: Click "New Scenario"¶

Click the "+ New Scenario" button in the top right corner of the scenarios list.

Step 3: Fill in Scenario Details¶

Step 4: Add Initial Trades (Optional)¶

You can add trades during creation or add them later. See Trade Simulation for details.

Step 5: Save the Scenario¶

Click "Create Scenario" to save. The scenario will be created in draft status, ready for trade simulation.

Creating a Scenario via API¶

Basic Creation¶

Create a scenario with just a name:

curl -X POST https://api.calcbridge.io/api/v1/scenarios \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 2026 Portfolio Optimization"
  }'

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Q1 2026 Portfolio Optimization",
  "description": null,
  "status": "draft",
  "base_workbook_id": null,
  "trade_count": 0,
  "created_by": "user-123",
  "created_at": "2026-01-25T10:30:00Z",
  "updated_at": "2026-01-25T10:30:00Z"
}

With Description and Base Workbook¶

curl -X POST https://api.calcbridge.io/api/v1/scenarios \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 2026 Portfolio Optimization",
    "description": "Evaluating exit from weak credits and adding high-quality loans",
    "base_workbook_id": "550e8400-e29b-41d4-a716-446655440001"
  }'

With Initial Trades¶

Create a scenario with trades in a single request:

curl -X POST https://api.calcbridge.io/api/v1/scenarios \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Healthcare Sector Exit",
    "description": "Reduce healthcare concentration by selling weak positions",
    "base_workbook_id": "550e8400-e29b-41d4-a716-446655440001",
    "trades": [
      {
        "trade_type": "sell",
        "cusip": "WEAK123",
        "borrower_name": "Struggling Healthcare Inc",
        "par_value": 2000000.00,
        "rating_moodys": "Caa2"
      },
      {
        "trade_type": "buy",
        "cusip": "STRONG456",
        "borrower_name": "Solid Tech Corp",
        "par_value": 2000000.00,
        "price": 99.50,
        "spread": 3.75,
        "rating_moodys": "B1",
        "industry": "Technology"
      }
    ]
  }'

Base Workbook Selection¶

The base workbook determines the starting portfolio for your simulation.

With a Base Workbook¶

When you specify a base_workbook_id:

1. CalcBridge loads the portfolio data from the workbook
2. It looks for sheets named "Portfolio", "Holdings", "Loans", "Assets", or "Collateral"
3. The simulation applies trades to this real portfolio data

Without a Base Workbook¶

When no base workbook is specified:

1. CalcBridge uses a sample portfolio for demonstration
2. Useful for learning the feature or testing trade combinations
3. Results reflect the sample data, not your actual portfolio

Scenario Naming Conventions¶

Establish naming conventions for your team to keep scenarios organized:

Recommended Format¶

[Date/Period] [Action] [Target] - [Detail]

Examples¶

Organization Tips¶

1. Use date prefixes for time-sensitive scenarios
2. Include the action type (Buy, Sell, Rebalance, Exit)
3. Reference specific positions when analyzing individual trades
4. Mark templates with a "Template" prefix

Managing Scenarios¶

Listing Scenarios¶

# List all scenarios
curl -X GET https://api.calcbridge.io/api/v1/scenarios \
  -H "Authorization: Bearer $TOKEN"

# Filter by status
curl -X GET "https://api.calcbridge.io/api/v1/scenarios?status_filter=completed" \
  -H "Authorization: Bearer $TOKEN"

# Paginate results
curl -X GET "https://api.calcbridge.io/api/v1/scenarios?page=1&page_size=20" \
  -H "Authorization: Bearer $TOKEN"

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Q1 2026 Portfolio Optimization",
      "status": "completed",
      "trade_count": 5,
      "created_at": "2026-01-25T10:30:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "page_size": 20,
  "pages": 3
}

Getting Scenario Details¶

curl -X GET https://api.calcbridge.io/api/v1/scenarios/{scenario_id} \
  -H "Authorization: Bearer $TOKEN"

Deleting a Scenario¶

curl -X DELETE https://api.calcbridge.io/api/v1/scenarios/{scenario_id} \
  -H "Authorization: Bearer $TOKEN"

Request/Response Reference¶

Create Scenario Request¶

Scenario Response¶

Error Handling¶

Common Errors¶

Validation Rules¶

• Scenario name must be 1-200 characters
• Description must be under 2000 characters
• Base workbook must exist and belong to your tenant
• Trade type must be "buy" or "sell"
• Par value must be positive

Next Steps¶

Now that you have created a scenario, learn how to:

• Add trades to your scenario
• Run simulations and view results
• Implement best practices for your team