OTC Deals Service (Specs)

The OTC (Over-The-Counter) Deals Service manages custom, high-volume foreign exchange transactions negotiated directly between institutional trading counterparties outside public order-book exchanges.

This API provides enterprise treasury desks, corporate market participants, and liquidity partners with end-to-end deal lifecycle management, bilateral settlement time tracking, dual-currency volume reconciliation, and audit log inspection.

flowchart TD
    subgraph Negotiation["1. Negotiation & Quotation"]
        Quote["Custom Bilateral Quote Created"]
        Awaiting["Status: awaitingClientResponse"]
    end

    subgraph ClientDecision["2. Client Action"]
        Accept["Client Accepts Deal (status: clientAccepted)"]
        Reject["Client Rejects Deal (status: clientRejected)"]
        Expire["Expiration Window Closes (status: expired)"]
    end

    subgraph Settlement["3. Dual-Leg Settlement"]
        Inward["Inward Settlement Leg (status: inwardSettlementDone)"]
        Outward["Outward Settlement Leg (status: outwardSettlementDone)"]
        Final["Settled (status: settled)"]
    end

    Quote --> Awaiting
    Awaiting --> Accept
    Awaiting --> Reject
    Awaiting --> Expire
    Accept --> Inward
    Inward --> Outward
    Outward --> Final

---

Key Capabilities

• Bespoke Pricing & High Volumes: Execute block-sized currency conversions with negotiated spreads and custom expiration periods (expirationPeriodMins).
• Flexible Settlement Scheduling: Coordinate separate scheduled and actual timestamps for inwardSettlementTime and outwardSettlementTime.
• Granular Filtering & Sorting: Filter deals by currency pairs (sellCurrency, buyCurrency), status, settlement windows, creation dates, and volume thresholds (minimumAmount / maximumAmount).
• Auditability: Every deal inherits comprehensive audit metadata (createdAt, modifiedAt, modifiedByUserId, dealAcceptedByUserId).

---

Deal Status Lifecycle

Status	Stage	Description
awaitingClientResponse	Quotation	Deal terms proposed by trading desk, awaiting counterparty review and confirmation.
clientAccepted	Confirmed	Client accepted proposed exchange rate and settlement schedule.
clientRejected	Declined	Client declined the proposed trade terms.
expired	Inactive	Acceptance window expired before confirmation was received.
inwardSettlementDone	Settlement (Leg 1)	Client has funded the sell leg of the deal.
outwardSettlementDone	Settlement (Leg 2)	Counterparty has delivered the bought funds to client account.
settled	Final	Both inward and outward settlement legs confirmed and completed.

---

Available Endpoints

Endpoint	Method	Operation ID	Description
/deals	GET	get_deals	Retrieve a paginated, filterable list of OTC deals

---

Authentication

All requests require a valid JWT Bearer access token:

Authorization: Bearer <your_jwt_access_token>