Liquidity Checker API Reference

Overview

The Ediphy Liquidity Checker API enables programmatic access to our collaborative trading blotter system, allowing trading teams to manage declared interest, monitor liquidity conditions, and seamlessly transition to firm order execution.

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

Why the Liquidity Checker API?

• Team Collaboration — Shared blotter visibility across your trading desk with user and team view modes
• Liquidity Intelligence — Real-time liquidity scores, trade counts, and alternative instrument suggestions
• Flexible Workflow — Progress from soft interest to firm orders when market conditions are favorable
• Bulk Operations — Sync your internal order management system via CSV upload or batch API
• Real-Time Updates — WebSocket streaming delivers instant blotter updates across connected clients
• Full Audit Trail — Every change is logged with provenance tracking (GUI vs sync)

1. Key Concepts

1.1 Interest Lifecycle

The Liquidity Checker manages declared interest — bonds you're interested in trading but haven't yet committed to as firm orders. Interest progresses through states based on user actions and market conditions.

Interest States (Firmness):

1.2 User vs Team Scope

The blotter supports two visibility modes:

User Mode (Default) - Shows only interest owned by the authenticated user - All users can view and modify their own interest - No special permissions required

Team Mode - Shows interest for all users within the organization - Requires external.data.blottersync.team.view permission - Modifying another user's interest requires external.data.blottersync.team.update permission

1.3 Provenance Tracking

Every interest record tracks its provenance — the source of its most recent update:

Why provenance matters:

• When a CSV sync is uploaded, it replaces all previous sync-sourced entries for that user
• GUI updates are preserved across syncs (firmness set via GUI survives re-sync)
• Audit trail shows whether changes came from automated systems or manual intervention

1.4 Interest Identification

Each interest record has multiple identifiers serving different purposes:

Client ID Behavior:

• If you provide a client_id when adding interest, that ID is preserved
• If omitted, the system generates a short random ID
• The (owner_user, client_id) combination is used to determine whether an update creates new interest or modifies existing interest

1.5 Data Enrichment

The Liquidity Checker enriches each interest record with data from multiple sources to help traders assess market conditions and identify optimal execution windows.

1.5.1 MiFID Post-Trade Data

Market activity data derived from regulatory post-trade reporting (MiFID II transparency regime):

1.5.2 Liquidity Scores

Proprietary liquidity metrics calculated from historical trading patterns:

Trade Count Metrics:

Lookback Metrics (Lower = More Liquid):

Alternative Instruments:

The system identifies similar bonds (same issuer, comparable maturity, similar characteristics) that may offer better liquidity if your target instrument is illiquid.

1.5.3 Live Market Data

Real-time pricing from Ediphy's trading venues:

1.5.4 Liquidity Check Status

The liq_check_status field provides a composite assessment combining the above metrics:

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

Environment values: dev, qa, prod

3. API Design

3.1 Base URL Structure

Production:  https://api.ediphymarkets.com/blotter/v1
Sandbox:     https://api.sandbox.ediphymarkets.com/blotter/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. Interest Endpoints

4.1 Add or Update Interest

Creates new interest or updates existing interest for a bond. If interest already exists for the (owner_user, client_id) combination, the existing record is updated.

Request Body

JSON
{
  "inst_id": "US912828ZT77",
  "client_id": "my-order-001",
  "verb": "buy",
  "qty": 5000000,
  "limit": 99.50,
  "firmness": "Soft",
  "comment": "Opportunistic add"
}

Field Definitions

Response (Success - 200 OK)

JSON
{
  "status": "success",
  "interest_id": "INTEREST_7f3a9b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "client_id": "my-order-001",
  "inst_id": "US912828ZT77",
  "message": "Interest added successfully"
}

Update Semantics

When updating existing interest:

• Provided fields are updated to the new values
• Omitted fields retain their existing values
• Null fields clear the existing value

JSON
{
  "inst_id": "US912828ZT77",
  "client_id": "my-order-001",
  "limit": 99.75
}

This updates only the limit price; verb, qty, firmness, and comment remain unchanged.

4.2 Remove Interest

Marks interest as Inactive with status Inactive. The record is not deleted but is excluded from active blotter views.

Request Body

JSON
{
  "inst_id": "US912828ZT77",
  "client_id": "my-order-001"
}

Response (Success - 200 OK)

JSON
{
  "status": "success",
  "message": "Removed my-order-001"
}

4.3 Clear All Interest

Removes all active interest for the authenticated user. Team administrators with appropriate permissions can clear interest for other users.

Request Body (Optional)

JSON
{
  "on_behalf_of_ediphy_user": "jsmith",
  "on_behalf_of_ediphy_org": "acme-trading"
}

If no parameters provided, clears all interest for the authenticated user.

Response (Success - 200 OK)

JSON
{
  "status": "success",
  "message": "Cleared"
}

4.4 Batch Upload

Upload multiple interest records in a single request. Ideal for syncing with external order management systems.

Request Body

JSON
{
  "rows": [
    {
      "inst_id": "US912828ZT77",
      "client_id": "order-001",
      "verb": "buy",
      "qty": 5000000,
      "limit": 99.50
    },
    {
      "inst_id": "US037833EK23",
      "client_id": "order-002",
      "verb": "sell",
      "qty": 10000000,
      "limit": 101.25
    }
  ]
}

Field Definitions (per row)

Response (Success - 200 OK)

JSON
{
  "status": "success",
  "message": "ISIN list uploaded successfully.",
  "rows_processed": 2
}

Batch Upload Semantics

Example workflow:

1. User has 10 interest records from previous sync
2. User uploads batch with 8 records
3. Result: 8 records from new batch (sync), plus any GUI-modified records preserved

GUI modifications (firmness changes made via UI) are preserved across syncs because they have prov: "gui".

4.5 Get Interest (User Scope)

Returns all active interest for the authenticated user, enriched with liquidity metrics and reference data.

Query Parameters

Response (Success - 200 OK)

JSON
{
  "interest": [
    {
      "interest_id": "INTEREST_7f3a9b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
      "client_id": "my-order-001",
      "inst_id": "US912828ZT77",
      "short_name": "T 2.5 05/15/30",
      "legal_name": "US TREASURY N/B",
      "currency_rd": "USD",
      "maturity": "2030-05-15",

      "verb": "buy",
      "qty": 5.0,
      "limit": 99.50,
      "firmness": "Soft",
      "firmness_pres": "Soft",

      "liq_check_status": "CAN TRADE NOW",
      "livemid": 99.625,
      "flags_tradable": true,

      "tc5": 12,
      "lb5": 2,
      "lb20": 5,
      "lb1mm": 3,
      "lb10mm": 8,
      "alt_count": 4,

      "prov": "gui",
      "owner_user": "jsmith",
      "ts_captured": "2025-01-15T10:30:00.123Z",

      "ticket_id": null,
      "qty_traded": 0,
      "ticket_count": 0
    }
  ]
}

Key Response Fields

4.6 Get Interest (Team Scope)

Returns all active interest for the authenticated user's organization. Requires external.data.blottersync.team.view permission.

Query Parameters

Same as user scope endpoint.

Response (Success - 200 OK)

Same structure as user scope, but includes interest from all team members. Each record includes owner_user to identify the owner.

4.7 Get Latest Changes

Returns the most recent changes to interest records within the current hour. Useful for polling updates without fetching the full blotter.

Response (Success - 200 OK)

JSON
{
  "changes": [
    {
      "interest_id": "INTEREST_7f3a9b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
      "inst_id": "US912828ZT77",
      "status": "Active",
      "verb": "buy",
      "qty": 5.0,
      "limit": 99.75,
      "firmness": "Soft",
      "ts_captured": "2025-01-15T10:45:00.123Z"
    }
  ],
  "timestamp": "2025-01-15T10:46:00.000Z"
}

5. Trading Integration

5.1 Transitioning to Firm

Interest cannot be set to Firm directly via the API. The transition to firm order requires the trading cockpit UI to:

1. Validate trading permissions
2. Apply price protection settings
3. Create the EMS ticket

Workflow:

1. Add interest via API (firmness: "Soft")
2. Monitor liq_check_status via polling or WebSocket
3. When conditions favorable, user clicks "Go Firm" in UI
4. System creates EMS ticket, links to interest_id
5. Interest shows ticket_id, firmness_pres: "FIRM"
6. Fills execute via EMS, qty_traded updates
7. When qty_traded >= qty, firmness_pres becomes "FILLED"

5.2 Linked Ticket Fields

When interest has an active trading ticket:

5.3 Actions Field

The actions field in the response indicates available UI actions:

6. WebSocket Streaming

6.1 Overview

For real-time blotter updates, connect to the WebSocket stream. Updates are pushed when any interest record changes.

Production:  wss://api.ediphymarkets.com/blotter/v1/stream
Sandbox:     wss://api.sandbox.ediphymarkets.com/blotter/v1/stream

6.2 Connection & Authentication

Connect to the WebSocket endpoint and send an authentication message within 5 seconds:

JSON
{"type": "auth", "api_key": "<api_key>"}

Server response (success):

JSON
{
  "type": "connected",
  "session": "2025-01-15",
  "scope": "user",
  "timestamp": "2025-01-15T10:30:00.123Z"
}

6.3 Subscribe to Team Updates

After authentication, optionally subscribe to team-wide updates:

JSON
{"type": "subscribe", "scope": "team"}

Server response:

JSON
{
  "type": "subscribed",
  "scope": "team",
  "timestamp": "2025-01-15T10:30:01.123Z"
}

Requires external.data.blottersync.team.view permission.

6.4 Heartbeat Protocol

Both client and server must send heartbeats to maintain the connection.

Client heartbeat:

JSON
{"type": "heartbeat"}

Server heartbeat:

JSON
{"type": "heartbeat", "timestamp": "2025-01-15T10:30:00.123Z"}

6.5 Server Messages

Interest Update

Sent when any interest record changes:

JSON
{
  "type": "interest_update",
  "interest_id": "INTEREST_7f3a9b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "timestamp": "2025-01-15T10:32:15.789Z",
  "data": {
    "interest_id": "INTEREST_7f3a9b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "inst_id": "US912828ZT77",
    "short_name": "T 2.5 05/15/30",
    "verb": "buy",
    "qty": 5.0,
    "limit": 99.75,
    "firmness": "Soft",
    "liq_check_status": "CAN TRADE NOW",
    "owner_user": "jsmith",
    "ts_captured": "2025-01-15T10:32:15.789Z"
  }
}

Interest Removed

Sent when interest is removed or marked inactive:

JSON
{
  "type": "interest_removed",
  "interest_id": "INTEREST_7f3a9b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "timestamp": "2025-01-15T10:35:00.123Z"
}

Liquidity Update

Sent when liquidity metrics change (batched, typically every few seconds):

JSON
{
  "type": "liquidity_update",
  "timestamp": "2025-01-15T10:32:20.000Z",
  "updates": [
    {
      "interest_id": "INTEREST_7f3a9b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
      "liq_check_status": "CAN TRADE NOW",
      "livemid": 99.65,
      "tc5": 13
    }
  ]
}

Trading Update

Sent when trading state changes (ticket created, fill received):

JSON
{
  "type": "trading_update",
  "interest_id": "INTEREST_7f3a9b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "timestamp": "2025-01-15T10:40:00.123Z",
  "data": {
    "ticket_id": "TICKET_abc123",
    "firmness_pres": "FIRM",
    "qty_traded": 2.5,
    "trading_status": "WORKING"
  }
}

6.6 Reconnection

If the WebSocket connection drops:

1. Wait 1 second, then attempt reconnect
2. On failure, use exponential backoff (2s, 4s, 8s, max 30s)
3. After reconnecting, call GET /interest to sync state
4. Resume normal operation

7. CSV File Format

7.1 Supported Formats

The batch upload endpoint and UI sync feature accept:

• CSV files (.csv)
• Excel files (.xlsx, .xls)

7.2 Required Columns

7.3 Optional Columns

7.4 Example CSV

CSV
isin,client_id,verb,quantity,limit
US912828ZT77,order-001,buy,5000000,99.50
US037833EK23,order-002,sell,10000000,101.25
XS1234567890,order-003,buy,2000000,

8. Client Integration Patterns

8.1 OMS Synchronization

Sync your internal order management system with the Liquidity Checker:

PYTHON
import requests
import csv

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

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

# Export orders from your OMS
def export_from_oms():
    # Your OMS export logic
    return [
        {"isin": "US912828ZT77", "client_id": "ORD-001", "verb": "buy", "qty": 5000000},
        {"isin": "US037833EK23", "client_id": "ORD-002", "verb": "sell", "qty": 10000000},
    ]

# Sync to Liquidity Checker
def sync_to_blotter():
    orders = export_from_oms()

    payload = {"rows": orders}

    response = requests.post(
        f"{API_BASE}/interest/batch",
        json=payload,
        headers=headers
    )
    response.raise_for_status()
    print(f"Synced {len(orders)} orders")

# Run sync periodically (e.g., every 5 minutes)
sync_to_blotter()

8.2 Liquidity Monitoring

Monitor liquidity conditions and alert when favorable:

PYTHON
import requests
import time

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

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

def check_liquidity():
    response = requests.get(f"{API_BASE}/interest", headers=headers)
    response.raise_for_status()

    for interest in response.json()["interest"]:
        if interest["liq_check_status"] == "CAN TRADE NOW":
            if interest["firmness"] == "Soft":
                print(f"ALERT: {interest['short_name']} ready to trade!")
                print(f"  Livemid: {interest['livemid']}")
                print(f"  Your limit: {interest['limit']}")
                print(f"  Trade count (5d): {interest['tc5']}")

# Poll every 30 seconds
while True:
    check_liquidity()
    time.sleep(30)

8.3 WebSocket Integration

Real-time blotter monitoring:

PYTHON
import websocket
import json
import threading

API_KEY = "ak_live_..."

def on_message(ws, message):
    data = json.loads(message)

    if data["type"] == "interest_update":
        interest = data["data"]
        print(f"Update: {interest['short_name']} - {interest['liq_check_status']}")

    elif data["type"] == "trading_update":
        print(f"Trading: {data['data']['firmness_pres']} - filled {data['data']['qty_traded']}MM")

def on_open(ws):
    # Authenticate
    ws.send(json.dumps({"type": "auth", "api_key": API_KEY}))

    # Start heartbeat thread
    def heartbeat():
        while True:
            ws.send(json.dumps({"type": "heartbeat"}))
            time.sleep(25)

    threading.Thread(target=heartbeat, daemon=True).start()

ws = websocket.WebSocketApp(
    "wss://api.ediphymarkets.com/blotter/v1/stream",
    on_message=on_message,
    on_open=on_open
)
ws.run_forever()

9. Rate Limiting

9.1 Default Limits

9.2 Response Headers

X-Ediphy-RateLimit-Limit: 10
X-Ediphy-RateLimit-Remaining: 8
X-Ediphy-RateLimit-Reset: 2025-01-15T10:31:00Z

9.3 Rate Limit Exceeded (429)

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

10. Security Considerations

10.1 Transport Security

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

10.2 Data Isolation

• User-scope endpoints only return the authenticated user's data
• Team-scope endpoints require explicit permission
• Cross-organization access is not permitted

10.3 Audit Trail

All API requests are logged with:

• Timestamp
• User identity
• Request payload
• Response status
• Provenance tracking

Audit reports are available upon request for compliance purposes.

11. Endpoint Summary

12. Appendix: Field Reference

12.1 Interest Request Fields

12.2 Interest Response Fields

Core Interest Fields:

Reference Data Fields:

MiFID Post-Trade Data:

Liquidity Score Fields:

Live Market Data:

Trading Status Fields: