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 blotter.team.view permission
• Modifying another user's interest requires blotter.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

Provenance Override:

By default, when an API sync updates a record that was previously modified via GUI (prov: "gui"), certain fields may be preserved to prevent stale OMS data from overwriting recent manual changes.

To force an update regardless of provenance (when your OMS has authoritative data), use the force_overwrite: true flag:

JSON
{
  "inst_id": "US912828ZT77",
  "client_id": "my-order-001",
  "limit": 99.00,
  "force_overwrite": true
}

When force_overwrite: true:

• All provided fields are updated regardless of current provenance
• The record's provenance is set to prov: "sync"
• The OMS effectively "reclaims" the record

1.4 Firm Orders and EMS Integration

When interest transitions to Firm status, the Liquidity Checker creates a live trading ticket in the Execution Management System (EMS). At this point, the order becomes visible and monitorable in both the Liquidity Checker and the EMS API/GUI.

Cross-System Visibility:

Linking Records Across Systems:

The linked_interest_id field ties the two systems together:

• EMS orders include linked_interest_id pointing back to the originating Liquidity Checker interest record
• Use this field to correlate execution events in the EMS with the corresponding interest on your blotter
• When querying the EMS API for orders, filter by linked_interest_id to find all executions related to a specific interest

1.5 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.6 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.6.1 MiFID Post-Trade Data

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

1.6.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.6.3 Live Market Data

Real-time pricing from Ediphy's trading venues:

1.6.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

3. API Design

3.1 Base URL Structure

Production:  https://api.ediphy.io/blotter/v1
Sandbox:     https://api-sandbox.ediphy.io/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
{
  "mode": "replace",
  "force_overwrite": false,
  "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
    }
  ]
}

Batch-Level Parameters

Upload Modes:

Field Definitions (per row)

Response (Success - 200 OK)

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

Batch Upload Semantics

Example workflow (replace mode):

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

Example workflow (merge mode):

1. User has 10 interest records from previous sync
2. User uploads batch with 3 records (mode: merge)
3. Result: 3 records upserted, 7 original records preserved

GUI modifications (firmness changes made via UI) are preserved across syncs because they have prov: "gui". Use force_overwrite: true to override this behavior.

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": 5000000,
      "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 blotter.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": 5000000,
      "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 can transition to Firm via the API using the POST /interest/{interest_id}/go-firm endpoint or via the trading cockpit UI. The transition:

1. Validates trading permissions
2. Applies price protection settings
3. Creates an EMS order linked to this interest

Workflow (API):

1. Add interest via API (firmness: "Soft")
2. Monitor liq_check_status via polling or WebSocket
3. When conditions favorable, call POST /interest/{interest_id}/go-firm
4. System creates EMS order with linked_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"

Workflow (UI):

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 order with linked_interest_id
5. Same as above...

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:

5.4 Go Firm Endpoint

Transitions soft interest to a firm order. Creates an EMS order linked to this interest record.

Path Parameters

Request Body (Optional)

JSON
{
  "limit": 99.50,
  "time_in_force": "GTT",
  "expire_at": "2025-01-15T16:00:00Z",
  "price_protection": "market"
}

If no body is provided, the order uses the interest's existing limit and default time-in-force settings.

Response (Success - 202 Accepted)

JSON
{
  "status": "success",
  "interest_id": "INTEREST_7f3a9b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "order_id": "ord_abc123",
  "ticket_id": "TICKET_xyz789",
  "message": "Interest transitioned to firm. EMS order created.",
  "links": {
    "interest": "/interest/INTEREST_7f3a9b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "order": "https://api.ediphy.io/ems/v1/orders/ord_abc123"
  }
}

Error Responses

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.ediphy.io/blotter/v1/stream
Sandbox:     wss://api-sandbox.ediphy.io/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 blotter.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": 5000000,
    "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": 2500000,
    "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.ediphy.io/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.ediphy.io/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":
        filled_mm = data['data']['qty_traded'] / 1_000_000
        print(f"Trading: {data['data']['firmness_pres']} - filled {filled_mm}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.ediphy.io/blotter/v1/stream",
    on_message=on_message,
    on_open=on_open
)
ws.run_forever()

9. Rate Limiting

9.1 Default Limits

Need higher limits? Contact support@ediphymarkets.com to discuss increased rate limits for high-volume use cases.

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 Concurrency Model

The Liquidity Checker uses a last-write-wins concurrency model. When multiple users or systems update the same interest record simultaneously, the most recent write takes precedence.

• No optimistic locking (ETags, version numbers) is enforced
• Conflicting updates are resolved by timestamp
• All changes are recorded in the audit trail for forensic review

10.4 Audit Trail

All API requests are logged with:

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

Query Audit Log

Query the audit trail for interest changes. Useful for compliance, debugging, and understanding change history.

Query Parameters

Response (Success - 200 OK)

JSON
{
  "audit_entries": [
    {
      "entry_id": "audit_abc123",
      "timestamp": "2025-01-15T10:32:15.789Z",
      "user": "jsmith",
      "action": "update",
      "interest_id": "INTEREST_7f3a9b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
      "client_id": "my-order-001",
      "inst_id": "US912828ZT77",
      "changes": {
        "limit": { "old": 99.50, "new": 99.75 },
        "prov": { "old": "sync", "new": "gui" }
      },
      "source": "api",
      "request_id": "req_xyz789"
    },
    {
      "entry_id": "audit_def456",
      "timestamp": "2025-01-15T10:30:00.123Z",
      "user": "oms_service",
      "action": "create",
      "interest_id": "INTEREST_7f3a9b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
      "client_id": "my-order-001",
      "inst_id": "US912828ZT77",
      "changes": {
        "qty": { "old": null, "new": 5000000 },
        "verb": { "old": null, "new": "buy" },
        "limit": { "old": null, "new": 99.50 }
      },
      "source": "batch",
      "request_id": "req_batch_001"
    }
  ],
  "pagination": {
    "total": 2,
    "limit": 100,
    "has_more": false
  }
}

Audit Entry Fields

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: