Transaction Cost Analysis (TCA) API Reference

Overview

The Ediphy TCA API provides comprehensive post-trade analytics, enabling traders and portfolio managers to measure execution quality, quantify transaction costs, and benchmark performance against market activity. Whether you're analyzing a single trade or reviewing an entire portfolio's execution history, TCA delivers actionable insights into how your trades performed relative to the market.

Product Coverage: Fixed Income Bonds (Corporate Credit, Government, Emerging Markets)

Why Ediphy TCA?

• Multi-Source Benchmarking — Compare executions against MiFID post-trade data, TRACE, Consolidated Tape (CT), and evaluated pricing sources
• Flexible Pricing References — Incorporate bank mid prices, fair value marks, or custom pricing feeds based on your data subscriptions
• Intelligent Cost Attribution — Measure costs in basis points (yield spread), dollar terms, and percentage of trade value
• Peer Universe Analysis — See how your execution compares to similar trades by instrument type, maturity, sector, and rating
• Statistical Rigor — Spline interpolation and clustering algorithms derive expected costs from sparse market data
• Seamless Integration — Analyze trades from your OMS, link to EMS executions, or enter trades manually

1. Key Concepts

1.1 Trade Input Methods

TCA accepts trades from multiple sources to accommodate different workflows:

Direct Entry: - Submit trade details directly via API (ISIN, side, quantity, price, timestamp) - Ideal for manual analysis or trades executed outside Ediphy

EMS Linkage: - Reference executed trades by ticket ID from the Ediphy EMS - Automatically pulls execution details including partial fills and average prices

Batch Import: - Upload multiple trades for portfolio-level analysis - CSV/JSON format for OMS integration

1.2 Cost Measurement Framework

TCA measures transaction costs across three dimensions:

Spread Cost (Basis Points)

The distance between your execution price and a reference price, expressed in yield terms:

spread_cost_bps = (execution_yield - reference_yield) × direction_multiplier

Where direction_multiplier is +1 for buys (paying more is a cost) and -1 for sells (receiving less is a cost).

Dollar Cost

The absolute dollar impact of the spread, scaled by trade size and duration:

dollar_cost = spread_cost_bps × duration × notional / 10000

For a 5MM trade with 5-year duration and 10bps spread cost:

dollar_cost = 10 × 5 × 5,000,000 / 10000 = $25,000

Percentage Cost

The cost as a proportion of trade value:

pct_cost = dollar_cost / (notional × clean_price / 100)

1.3 Reference Price Hierarchy

TCA computes costs against multiple reference prices, providing a multi-dimensional view of execution quality:

Reference Selection:

By default, TCA computes costs against all available references. You can specify a primary reference for headline metrics:

JSON
{
  "primary_reference": "arrival_mid",
  "include_all_references": true
}

1.4 Benchmark Data Sources

TCA aggregates market activity from multiple regulatory and commercial sources:

1.4.1 MiFID Post-Trade Data (European Markets)

Trade reports from the MiFID II transparency regime covering European fixed income markets:

1.4.2 TRACE Data (US Corporate & Agency)

FINRA's Trade Reporting and Compliance Engine provides US corporate bond transparency:

1.4.3 Consolidated Tape (CT)

Where available, consolidated tape data provides a unified view across trading venues:

1.4.4 Evaluated Pricing Sources

Client data subscriptions enable additional pricing references:

1.5 Peer Universe Construction

TCA contextualizes your execution by comparing it to a peer universe of similar trades. The peer universe is constructed by filtering market activity across multiple dimensions:

Instrument Characteristics:

Trade Characteristics:

Benchmark Window:

1.6 Statistical Methods

TCA employs statistical techniques to derive meaningful benchmarks from sparse fixed income data:

1.6.1 Spline Interpolation

For instruments with limited direct trading activity, TCA constructs synthetic benchmarks using spline interpolation across the issuer's curve:

• Fit a smooth yield curve to the issuer's traded bonds
• Interpolate/extrapolate to the target maturity
• Estimate fair value spread based on curve position

This is particularly valuable for off-the-run bonds where direct comparables are scarce.

1.6.2 Clustering Analysis

TCA groups instruments into clusters based on similarity across multiple features:

• Credit risk profile (rating, sector, issuer characteristics)
• Duration and convexity
• Liquidity characteristics
• Historical trading patterns

Execution costs are then compared within the cluster to identify outliers and establish expected cost ranges.

1.6.3 Confidence Intervals

Rather than a single "expected cost" point estimate, TCA provides confidence bands:

A trade in the 90th percentile cost a lot more than most comparable trades; 10th percentile indicates exceptional execution.

2. Authentication & Authorization

2.1 Authentication

The API uses Bearer token authentication. Include your API key in the Authorization header:

Authorization: Bearer <api_key>

API keys are managed through the Ediphy client portal. See the EMS Client API documentation for details on key management and rotation.

2.2 Required Permissions

2.3 Data Entitlements

Access to benchmark data sources depends on your subscription:

3. API Design

3.1 Base URL Structure

Production:  https://api.ediphymarkets.com/tca/v1
Sandbox:     https://api.sandbox.ediphymarkets.com/tca/v1

3.2 Common Headers

Request:

Content-Type: application/json
Authorization: Bearer <api_key>

Response:

Content-Type: application/json
X-Ediphy-Request-Id: <uuid>

3.3 Error Response Format

JSON
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid ISIN format",
    "field": "inst_id",
    "request_id": "req_abc123"
  }
}

Error Codes:

3.4 HTTP Status Codes

4. Trade Analysis Endpoints

4.1 Analyze Single Trade

Submits a single trade for TCA analysis and returns comprehensive cost metrics.

Request Body (Direct Entry)

JSON
{
  "trade": {
    "inst_id": "US912828ZT77",
    "side": "buy",
    "quantity": 5000000,
    "price": 99.50,
    "yield": 4.25,
    "executed_at": "2025-01-15T14:30:00.000Z"
  },
  "options": {
    "primary_reference": "arrival_mid",
    "benchmark_windows": ["same_day", "5_day"],
    "peer_dimensions": ["asset_class", "maturity", "rating"],
    "include_curve_analysis": true
  }
}

Request Body (EMS Ticket Linkage)

JSON
{
  "ticket_id": "TICKET_abc123def456",
  "options": {
    "primary_reference": "arrival_mid",
    "benchmark_windows": ["same_day", "5_day"]
  }
}

Trade Field Definitions

*Either price or yield must be provided.

Options Field Definitions

Response (Success - 200 OK)

JSON
{
  "report_id": "TCA_7f3a9b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "trade": {
    "inst_id": "US912828ZT77",
    "short_name": "T 2.5 05/15/30",
    "legal_name": "US TREASURY N/B",
    "side": "buy",
    "quantity": 5000000,
    "quantity_mm": 5.0,
    "price": 99.50,
    "yield": 4.25,
    "executed_at": "2025-01-15T14:30:00.000Z",
    "arrival_at": "2025-01-15T14:28:30.000Z"
  },

  "instrument": {
    "asset_class": "Government",
    "sector": "Sovereign",
    "rating": "AAA",
    "currency": "USD",
    "maturity": "2030-05-15",
    "maturity_bucket": "Medium",
    "duration": 4.85,
    "coupon": 2.5
  },

  "cost_summary": {
    "primary_reference": "arrival_mid",
    "spread_cost_bps": 3.2,
    "dollar_cost": 7760,
    "pct_cost": 0.0156,
    "direction_label": "Paid up",
    "quality_rating": "Good"
  },

  "reference_prices": {
    "arrival_mid": {
      "price": 99.532,
      "yield": 4.218,
      "source": "live_pricing",
      "spread_cost_bps": 3.2,
      "dollar_cost": 7760
    },
    "execution_mid": {
      "price": 99.525,
      "yield": 4.222,
      "source": "live_pricing",
      "spread_cost_bps": 2.8,
      "dollar_cost": 6790
    },
    "vwap": {
      "price": 99.48,
      "yield": 4.250,
      "source": "trace",
      "spread_cost_bps": -2.0,
      "dollar_cost": -4850,
      "volume": 125000000,
      "trade_count": 47
    },
    "fair_value": {
      "price": 99.51,
      "yield": 4.237,
      "source": "ediphy",
      "as_of": "2025-01-15T00:00:00Z",
      "spread_cost_bps": 1.3,
      "dollar_cost": 3153
    },
    "curve_implied": {
      "price": 99.495,
      "yield": 4.244,
      "source": "spline_fit",
      "curve_residual_bps": 0.6,
      "spread_cost_bps": 0.6,
      "dollar_cost": 1455
    }
  },

  "peer_analysis": {
    "window": "same_day",
    "peer_count": 47,
    "peer_volume": 125000000,
    "peer_dimensions": {
      "asset_class": "Government",
      "maturity_bucket": "Medium",
      "size_bucket": "Medium"
    },
    "cost_distribution": {
      "p10": -2.5,
      "p25": -0.8,
      "p50": 1.2,
      "p75": 3.5,
      "p90": 6.8,
      "mean": 1.8,
      "std_dev": 3.2
    },
    "your_percentile": 62,
    "expected_cost": {
      "low": -0.8,
      "mid": 1.2,
      "high": 3.5
    }
  },

  "curve_analysis": {
    "curve_date": "2025-01-15",
    "issuer_curve_bonds": 12,
    "curve_fit_quality": "Good",
    "curve_r_squared": 0.987,
    "target_curve_yield": 4.244,
    "curve_spread_bps": 0.6,
    "richness_cheapness": "Slightly Cheap",
    "z_score": 0.45
  },

  "market_context": {
    "benchmark_window": "same_day",
    "sources": ["trace", "mifid"],
    "trace": {
      "volume": 125000000,
      "trade_count": 47,
      "vwap_price": 99.48,
      "vwap_yield": 4.250,
      "high_price": 99.72,
      "low_price": 99.31,
      "median_spread_bps": 1.5
    },
    "mifid": {
      "volume": 45000000,
      "trade_count": 18,
      "vwap_price": 99.52,
      "vwap_yield": 4.231
    },
    "liquidity_indicator": "High",
    "market_direction": "Slightly Weaker"
  },

  "data_quality": {
    "overall_confidence": "High",
    "reference_data_available": ["arrival_mid", "execution_mid", "vwap", "twap", "fair_value", "curve_implied"],
    "reference_data_unavailable": ["bank_mid"],
    "peer_universe_depth": "Adequate",
    "curve_data_quality": "Good",
    "warnings": []
  },

  "metadata": {
    "analyzed_at": "2025-01-15T14:35:12.456Z",
    "api_version": "1.0",
    "data_subscriptions_used": ["trace", "mifid", "ediphy_pricing"]
  }
}

4.2 Batch Analysis

Submits multiple trades for analysis. Returns immediately with a batch ID; poll for results.

Request Body

JSON
{
  "trades": [
    {
      "inst_id": "US912828ZT77",
      "side": "buy",
      "quantity": 5000000,
      "price": 99.50,
      "executed_at": "2025-01-15T14:30:00.000Z",
      "client_trade_id": "TRADE-001"
    },
    {
      "inst_id": "US037833EK23",
      "side": "sell",
      "quantity": 10000000,
      "yield": 5.125,
      "executed_at": "2025-01-15T15:45:00.000Z",
      "client_trade_id": "TRADE-002"
    }
  ],
  "options": {
    "primary_reference": "fair_value",
    "benchmark_windows": ["same_day", "5_day"],
    "include_curve_analysis": true
  }
}

Response (Accepted - 202)

JSON
{
  "batch_id": "BATCH_abc123def456",
  "status": "processing",
  "trades_submitted": 2,
  "estimated_completion": "2025-01-15T14:36:00.000Z",
  "links": {
    "status": "/analyze/batch/BATCH_abc123def456",
    "results": "/analyze/batch/BATCH_abc123def456/results"
  }
}

4.3 Get Batch Status

Check the status of a batch analysis request.

Response (Success - 200 OK)

JSON
{
  "batch_id": "BATCH_abc123def456",
  "status": "completed",
  "trades_submitted": 2,
  "trades_analyzed": 2,
  "trades_failed": 0,
  "started_at": "2025-01-15T14:35:00.000Z",
  "completed_at": "2025-01-15T14:35:45.000Z",
  "links": {
    "results": "/analyze/batch/BATCH_abc123def456/results"
  }
}

Batch Status Values:

4.4 Get Batch Results

Retrieve results for a completed batch analysis.

Query Parameters

Response (Success - 200 OK)

JSON
{
  "batch_id": "BATCH_abc123def456",
  "results": [
    {
      "report_id": "TCA_7f3a9b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
      "client_trade_id": "TRADE-001",
      "status": "success",
      "trade": { /* ... */ },
      "cost_summary": { /* ... */ },
      "reference_prices": { /* ... */ },
      "peer_analysis": { /* ... */ }
    },
    {
      "report_id": "TCA_def456ghi789",
      "client_trade_id": "TRADE-002",
      "status": "success",
      "trade": { /* ... */ },
      "cost_summary": { /* ... */ },
      "reference_prices": { /* ... */ },
      "peer_analysis": { /* ... */ }
    }
  ],
  "summary": {
    "total_trades": 2,
    "total_notional": 15000000,
    "aggregate_spread_cost_bps": 2.1,
    "aggregate_dollar_cost": 15750,
    "weighted_percentile": 58
  },
  "pagination": {
    "total": 2,
    "limit": 50,
    "has_more": false
  }
}

4.5 Get Report

Retrieve a previously generated TCA report by ID.

Response (Success - 200 OK)

Returns the full report structure as shown in Section 4.1.

4.6 List Reports

List TCA reports for the authenticated user.

Query Parameters

Response (Success - 200 OK)

JSON
{
  "reports": [
    {
      "report_id": "TCA_7f3a9b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
      "inst_id": "US912828ZT77",
      "short_name": "T 2.5 05/15/30",
      "side": "buy",
      "quantity_mm": 5.0,
      "executed_at": "2025-01-15T14:30:00.000Z",
      "spread_cost_bps": 3.2,
      "percentile": 62,
      "quality_rating": "Good",
      "analyzed_at": "2025-01-15T14:35:12.456Z"
    }
  ],
  "pagination": {
    "total": 127,
    "limit": 50,
    "has_more": true,
    "next_cursor": "eyJpZCI6InRjYV8xMjM0In0="
  }
}

5. Cost Metrics Detail

5.1 Spread Metrics

Yield Spread (Primary)

The difference between your execution yield and the reference yield:

For buys: Paying a higher yield (lower price) is a cost. For sells: Receiving a lower yield (lower price) is a cost.

Price Spread (Secondary)

For instruments where yield isn't meaningful (e.g., floaters), price spread is provided:

5.2 Dollar Cost

Translates yield spread into dollar impact using duration:

dollar_cost = spread_cost_bps × modified_duration × notional / 10000

5.3 Implementation Shortfall

Measures the total cost of implementing a trade decision from arrival to completion:

implementation_shortfall = delay_cost + execution_cost

5.4 Market Impact

For larger trades, TCA estimates the market impact of your execution:

6. Benchmark Data Detail

6.1 MiFID Data Fields

6.2 TRACE Data Fields

6.3 Consolidated Tape Fields

6.4 Evaluated Pricing Fields

7. Statistical Analysis Detail

7.1 Spline Interpolation

The curve_analysis section provides detail on curve-based valuation:

Curve Fit Quality Criteria:

7.2 Clustering Analysis

The cluster_analysis section (when available) provides peer grouping detail:

7.3 Percentile Calculations

Percentile rank contextualizes your execution against the peer universe:

Interpretation Guide:

8. Quality Ratings

TCA provides a summary quality rating for each trade:

The rating considers: - Primary reference spread cost - Peer universe percentile - Data quality and confidence level

9. Data Quality & Confidence

9.1 Confidence Levels

Each TCA report includes a data quality assessment:

Confidence Criteria:

9.2 Common Warnings

10. Client Integration Patterns

10.1 Post-Trade Analysis

Analyze a trade immediately after execution:

PYTHON
import requests

API_BASE = "https://api.ediphymarkets.com/tca/v1"
API_KEY = "ak_live_..."

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

def analyze_trade(isin, side, quantity, price, executed_at):
    payload = {
        "trade": {
            "inst_id": isin,
            "side": side,
            "quantity": quantity,
            "price": price,
            "executed_at": executed_at
        },
        "options": {
            "primary_reference": "arrival_mid",
            "benchmark_windows": ["same_day", "5_day"]
        }
    }

    response = requests.post(
        f"{API_BASE}/analyze",
        json=payload,
        headers=headers
    )
    response.raise_for_status()
    return response.json()

# Analyze a trade
result = analyze_trade(
    isin="US912828ZT77",
    side="buy",
    quantity=5000000,
    price=99.50,
    executed_at="2025-01-15T14:30:00.000Z"
)

print(f"Spread cost: {result['cost_summary']['spread_cost_bps']} bps")
print(f"Dollar cost: ${result['cost_summary']['dollar_cost']:,.0f}")
print(f"Percentile: {result['peer_analysis']['your_percentile']}th")
print(f"Rating: {result['cost_summary']['quality_rating']}")

10.2 Batch Portfolio Analysis

Analyze an entire day's trading activity:

PYTHON
import requests
import time

API_BASE = "https://api.ediphymarkets.com/tca/v1"
API_KEY = "ak_live_..."

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

def analyze_portfolio(trades):
    # Submit batch
    payload = {
        "trades": trades,
        "options": {
            "primary_reference": "fair_value",
            "benchmark_windows": ["same_day"]
        }
    }

    response = requests.post(
        f"{API_BASE}/analyze/batch",
        json=payload,
        headers=headers
    )
    response.raise_for_status()
    batch = response.json()
    batch_id = batch["batch_id"]

    # Poll for completion
    while True:
        status_response = requests.get(
            f"{API_BASE}/analyze/batch/{batch_id}",
            headers=headers
        )
        status = status_response.json()

        if status["status"] in ["completed", "completed_with_errors"]:
            break

        time.sleep(2)

    # Retrieve results
    results_response = requests.get(
        f"{API_BASE}/analyze/batch/{batch_id}/results",
        headers=headers
    )
    return results_response.json()

# Example portfolio
trades = [
    {
        "inst_id": "US912828ZT77",
        "side": "buy",
        "quantity": 5000000,
        "price": 99.50,
        "executed_at": "2025-01-15T14:30:00.000Z",
        "client_trade_id": "TRADE-001"
    },
    {
        "inst_id": "US037833EK23",
        "side": "sell",
        "quantity": 10000000,
        "price": 101.25,
        "executed_at": "2025-01-15T15:45:00.000Z",
        "client_trade_id": "TRADE-002"
    }
]

results = analyze_portfolio(trades)

print(f"Total trades: {results['summary']['total_trades']}")
print(f"Total notional: ${results['summary']['total_notional']:,.0f}")
print(f"Aggregate cost: {results['summary']['aggregate_spread_cost_bps']:.1f} bps")
print(f"Aggregate dollar cost: ${results['summary']['aggregate_dollar_cost']:,.0f}")

10.3 EMS Integration

Analyze trades executed via Ediphy EMS:

PYTHON
import requests

API_BASE = "https://api.ediphymarkets.com/tca/v1"
API_KEY = "ak_live_..."

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

def analyze_ems_trade(ticket_id):
    payload = {
        "ticket_id": ticket_id,
        "options": {
            "primary_reference": "arrival_mid",
            "include_curve_analysis": True
        }
    }

    response = requests.post(
        f"{API_BASE}/analyze",
        json=payload,
        headers=headers
    )
    response.raise_for_status()
    return response.json()

# Analyze EMS execution
result = analyze_ems_trade("TICKET_abc123def456")

# Check implementation shortfall
if "implementation_shortfall_bps" in result["cost_summary"]:
    is_bps = result["cost_summary"]["implementation_shortfall_bps"]
    delay = result["cost_summary"]["delay_cost_bps"]
    exec_cost = result["cost_summary"]["execution_cost_bps"]

    print(f"Implementation shortfall: {is_bps:.1f} bps")
    print(f"  - Delay cost: {delay:.1f} bps")
    print(f"  - Execution cost: {exec_cost:.1f} bps")

10.4 Periodic Reporting

Generate weekly TCA summary reports:

PYTHON
import requests
from datetime import datetime, timedelta

API_BASE = "https://api.ediphymarkets.com/tca/v1"
API_KEY = "ak_live_..."

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

def weekly_tca_summary():
    # Get last week's reports
    end_date = datetime.now()
    start_date = end_date - timedelta(days=7)

    response = requests.get(
        f"{API_BASE}/reports",
        params={
            "from": start_date.isoformat() + "Z",
            "to": end_date.isoformat() + "Z",
            "limit": 200
        },
        headers=headers
    )
    response.raise_for_status()
    data = response.json()

    # Aggregate statistics
    total_trades = len(data["reports"])
    total_cost_bps = sum(r["spread_cost_bps"] for r in data["reports"])
    avg_cost_bps = total_cost_bps / total_trades if total_trades > 0 else 0

    ratings = {}
    for r in data["reports"]:
        rating = r["quality_rating"]
        ratings[rating] = ratings.get(rating, 0) + 1

    print(f"Weekly TCA Summary ({start_date.date()} to {end_date.date()})")
    print(f"Total trades analyzed: {total_trades}")
    print(f"Average spread cost: {avg_cost_bps:.1f} bps")
    print(f"Rating distribution: {ratings}")

weekly_tca_summary()

11. Rate Limiting

11.1 Default Limits

11.2 Response Headers

X-Ediphy-RateLimit-Limit: 20
X-Ediphy-RateLimit-Remaining: 18
X-Ediphy-RateLimit-Reset: 2025-01-15T14:31:00Z

11.3 Rate Limit Exceeded (429)

JSON
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests",
    "retry_after": 5
  }
}

12. Security Considerations

12.1 Transport Security

• TLS 1.3 required for all connections
• Certificate pinning recommended for production integrations

12.2 Data Access

• TCA reports are private to the authenticated user
• Team-level access requires explicit permission
• Data source access controlled by subscription entitlements

12.3 Audit Trail

All TCA requests are logged with: - Timestamp - User identity - Request parameters - Data sources used - Results summary

Audit reports available upon request for compliance purposes.

13. Endpoint Summary

14. Appendix: Field Reference

14.1 Trade Request Fields

*Either price or yield required.

14.2 Options Fields

14.3 Cost Summary Fields

14.4 Reference Price Fields

14.5 Peer Analysis Fields

14.6 Curve Analysis Fields

14.7 Market Context Fields

14.8 Data Quality Fields

15. Glossary