Trade Simulation¶

Trade simulation is the core of what-if analysis. This guide covers how to add trades to scenarios, configure trade parameters, and run simulations.

Trade Types¶

CalcBridge supports two fundamental trade types:

Buy Trades¶

When you add a buy trade:

1. If the CUSIP does not exist in the portfolio, a new position is created
2. If the CUSIP already exists, the par value is added to the existing position
3. All loan attributes (rating, spread, industry) are captured for compliance calculations

Sell Trades¶

When you add a sell trade:

1. CalcBridge matches by CUSIP to find the existing position
2. If sell par equals or exceeds existing par, the position is fully removed
3. If sell par is less, the position is reduced proportionally

flowchart TD
    A[Trade Input] --> B{Trade Type?}
    B -->|Buy| C{CUSIP Exists?}
    B -->|Sell| D{CUSIP Exists?}

    C -->|No| E[Create New Position]
    C -->|Yes| F[Add to Position]

    D -->|No| G[Trade Ignored]
    D -->|Yes| H{Sell >= Position?}

    H -->|Yes| I[Remove Position]
    H -->|No| J[Reduce Position]

    E --> K[Updated Portfolio]
    F --> K
    I --> K
    J --> K

Trade Parameters¶

Required Fields¶

Optional Fields¶

Adding Trades via UI¶

Using the Trade Builder¶

1. Open your scenario from the Scenarios list
2. Locate the "Add Trade" panel on the right side
3. Select the trade type (Buy or Sell)
4. Enter the required and optional fields
5. Click "Add Trade" to save

Trade Builder Fields¶

The Trade Builder form includes:

• Trade Type: Dropdown to select Buy or Sell
• CUSIP: Text input for the security identifier
• Borrower Name: Text input for the obligor name
• Par Value: Number input (required, must be positive)
• Price (%): Number input for trade price
• Spread (bps): Number input for interest spread
• Ratings: Three text inputs for Moody's, S&P, and Fitch
• Industry: Text input for industry classification
• Maturity Date: Date picker

Quick Actions¶

• Clear: Reset the form to enter a new trade
• Add Trade: Submit the trade to the scenario

Adding Trades via API¶

Single Trade¶

curl -X POST https://api.calcbridge.io/api/v1/scenarios/{scenario_id}/trades \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "trade_type": "buy",
    "cusip": "12345ABC9",
    "borrower_name": "Example Corporation",
    "par_value": 1000000.00,
    "price": 98.50,
    "spread": 3.25,
    "rating_moodys": "B2",
    "rating_sp": "B",
    "industry": "Technology",
    "maturity_date": "2028-12-31"
  }'

Response:

{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "scenario_id": "550e8400-e29b-41d4-a716-446655440000",
  "trade_type": "buy",
  "cusip": "12345ABC9",
  "borrower_name": "Example Corporation",
  "par_value": 1000000.00,
  "price": 98.50,
  "spread": 3.25,
  "rating_moodys": "B2",
  "rating_sp": "B",
  "rating_fitch": null,
  "industry": "Technology",
  "maturity_date": "2028-12-31",
  "created_at": "2026-01-25T10:35:00Z"
}

Bulk Trades During Scenario Creation¶

Add multiple trades when creating the scenario:

curl -X POST https://api.calcbridge.io/api/v1/scenarios \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Portfolio Rebalance",
    "trades": [
      {
        "trade_type": "sell",
        "cusip": "WEAK001",
        "par_value": 500000.00,
        "rating_moodys": "Caa1"
      },
      {
        "trade_type": "sell",
        "cusip": "WEAK002",
        "par_value": 750000.00,
        "rating_moodys": "Caa2"
      },
      {
        "trade_type": "buy",
        "cusip": "STRONG001",
        "par_value": 1250000.00,
        "price": 99.00,
        "spread": 4.00,
        "rating_moodys": "B1"
      }
    ]
  }'

Listing Trades¶

View All Trades in a Scenario¶

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

Response:

[
  {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "scenario_id": "550e8400-e29b-41d4-a716-446655440000",
    "trade_type": "buy",
    "cusip": "12345ABC9",
    "borrower_name": "Example Corporation",
    "par_value": 1000000.00,
    "price": 98.50,
    "spread": 3.25,
    "rating_moodys": "B2",
    "created_at": "2026-01-25T10:35:00Z"
  },
  {
    "id": "660e8400-e29b-41d4-a716-446655440002",
    "scenario_id": "550e8400-e29b-41d4-a716-446655440000",
    "trade_type": "sell",
    "cusip": "OLD123",
    "par_value": 500000.00,
    "created_at": "2026-01-25T10:36:00Z"
  }
]

Removing Trades¶

Remove a trade before running the simulation:

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

Running the Simulation¶

Once trades are configured, run the simulation to see compliance impact:

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

Simulation Process¶

1. Load Base Portfolio: Reads loans from the base workbook (or uses sample data)
2. Apply Trades: Processes each buy/sell trade in order
3. Run Compliance Tests: Calculates all tests on both original and modified portfolios
4. Compare Results: Determines impact direction for each test
5. Store Results: Saves test results to the database
6. Update Status: Sets scenario status to completed or failed

Simulation Response¶

{
  "scenario_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "results": [
    {
      "test_name": "CCC Bucket",
      "test_category": "rating",
      "current_value": 6.5,
      "projected_value": 4.2,
      "threshold_value": 7.5,
      "cushion_current": 1.0,
      "cushion_projected": 3.3,
      "status_current": "pass",
      "status_projected": "pass",
      "impact_direction": "improve"
    }
  ],
  "impact_summary": {
    "improve": 3,
    "worsen": 1,
    "neutral": 8
  },
  "new_failures": 0,
  "total_tests": 12,
  "message": "Simulation completed: 3 trades applied to 150 loans"
}

Trade Scenarios Examples¶

Example 1: Replace CCC Credits¶

Sell low-rated positions and buy higher-quality replacements:

{
  "name": "CCC Reduction",
  "trades": [
    {
      "trade_type": "sell",
      "cusip": "CCC001",
      "par_value": 1000000,
      "rating_moodys": "Caa1"
    },
    {
      "trade_type": "sell",
      "cusip": "CCC002",
      "par_value": 1500000,
      "rating_moodys": "Caa2"
    },
    {
      "trade_type": "buy",
      "cusip": "NEW001",
      "par_value": 2500000,
      "rating_moodys": "B2",
      "spread": 4.5
    }
  ]
}

Example 2: Industry Diversification¶

Reduce concentration in a single industry:

{
  "name": "Healthcare Exit",
  "trades": [
    {
      "trade_type": "sell",
      "cusip": "HEALTH01",
      "par_value": 2000000,
      "industry": "Healthcare"
    },
    {
      "trade_type": "buy",
      "cusip": "TECH001",
      "par_value": 1000000,
      "industry": "Technology"
    },
    {
      "trade_type": "buy",
      "cusip": "MFG001",
      "par_value": 1000000,
      "industry": "Manufacturing"
    }
  ]
}

Example 3: Single Large Position¶

Evaluate adding a significant new position:

{
  "name": "Big Ticket Evaluation",
  "trades": [
    {
      "trade_type": "buy",
      "cusip": "BIGLOAN1",
      "borrower_name": "Major Industries LLC",
      "par_value": 5000000,
      "price": 99.25,
      "spread": 3.50,
      "rating_moodys": "Ba2",
      "rating_sp": "BB",
      "industry": "Chemicals",
      "maturity_date": "2029-06-30"
    }
  ]
}

Modifying Scenarios¶

Reset and Start Over¶

To completely reset a scenario:

1. Delete all existing trades
2. Add new trades
3. Run simulation again

Iterative Analysis¶

For iterative trade analysis:

1. Run simulation with initial trades
2. Review results
3. Delete the scenario
4. Create a new scenario with adjusted trades
5. Repeat until satisfied

Error Handling¶

Common Trade Errors¶

Validation Rules¶

• trade_type must be exactly "buy" or "sell"
• par_value must be a positive number
• price must be between 0 and 200 (if provided)
• maturity_date must be a valid ISO 8601 date (if provided)
• Rating fields accept standard rating notations

Next Steps¶

After configuring your trades:

• Analyze simulation results
• Learn best practices for scenario analysis