CME GC Allocator API
CME GC Allocator API is a JSON RESTful API that provides support for General Collateral (GC) Repo customers to manage their post-trade GC allocations and substitutions.
GC Repos are a type of Repo transaction that trade against a specified “basket” of underlying collateral. Post-execution, the GC Repo seller allocates the specific piece(s) of collateral from the “basket” to fulfill the GC trade obligation. Upon allocation, the value of the GC trade obligations for cash considerations are determined.
The CME GC Allocator API supports the following functions:
All GC Repo customers can search and retrieve GC Repo trades and associated allocations for their firm on demand
GC Repo sellers may view and submit GC allocations and substitutions for their firm’s trades
GC Repo buyers may view GC allocations and substitutions for their firm’s trades
Underlying Bond Price Override for GC Repo Trades
Support for GC Substitutions is permitted for the US market only.
For US and EU Repos on GC Allocator API, the InstrumentGUID for AON instruments is always retained.
Revision History
Date | Description |
---|---|
11/30/2021 | Migrated content from the BrokerTec Support Portal to the Client Systems wiki. |
6 Aug 2021 | Fields added to Instrument Response Message payload collateral structure
Fields added to Collateral Response Message payload
Field removed from Collateral Response Message payload
Fields added to Collateral Notification Response Message
Field added to Trade Event Response Message
|
27 Jan 2021 | Added DealID to Search for Trades and Get Trades message layouts |
11 Jan 2021 | Error codes details update. |
18 Nov 2020 | Added note for single sign-on whitelisting IP |
12 Nov 2020 | Added Disaster Recovery Considerations |
10 Nov 2020 | Changed launch date: Q4 2020 Q1 2021. |
30 Sep 2020 | Added Onboarding details. Added Error code details. |
20 Aug 2020 | Removed verbiage excluding All Or None trades from GC Allocator capability Updated table formatting |
12 June 2020 | Added new instrument search end point to message specifications |
22 Mar 2020 | Added Underlying Bond Price Override information |
05 Mar 2020 | Full functionality except for All Or None trades |
04 Mar 2020 | Updated New Release date to 05 Mar 2020. |
23 Oct 2019 | Updated New Release date to 1H 2020. "Timestamps" - Added section. "Customer Substitution" - Updated steps and diagram. Updated message specifications. |
11 Oct 2019 | Updated New Release date to Feb 2020. |
08 Jul 2019 | Initial release. |
Onboarding
CME GC Allocator API uses OAuth, an open protocol that supports secure authorization in a simple, standard method and decouples authentication from authorization.
See: Client API Service Adoption using OAuth 2.0 Protocol
Authorization
A registered OAuth API ID is required to access the CME GC Allocator API services. API IDs for CME Group Logins are created and managed in the Customer Center under My Profile.
New Clients
New clients - should start by Creating a CME Group Login.
Once a client creates and activates their CME Group Login ID, they can login to Customer Center under My Profile and create an OAuth API ID
Clients with Existing CME Group Logins
Clients with existing CME Group Login ID can login to Customer Center and under My Profile create an OAuth API ID
Clients with existing CME Group Login ID and existing Basic Auth API ID can convert the Basic Auth API ID to an OAuth API ID under the API Management section of the CME Group Login under My Profile.
Contact Global Account Management (GAM) for CME GC Allocator API access and more information.
Testing and Certification
Certification is required for GC Allocator API services. Please contact Certification Support for Electronic Trading (CSET).
Roles
Roles are required for CME GC Allocator API.
GC Allocator API --Allocator (Trader/Clerk)
External Workstation - Allocator (Trader/Clerk)
External Workstation - GC Allocator Viewer
Connectivity Considerations
During a disaster recovery (DR) event clients will automatically be directed to the DR instance of GC Allocator API. Clients do not need to make any connectivity changes.
GC Allocator API Connectivity
Environment | DNS Name | IP |
---|---|---|
New Release | https://api.gcallocator-nr.cmegroup.com/ | 164.74.123.38 |
Production | https://api.gcallocator.cmegroup.com// | 205.209.196.176 |
GC Allocator UI Connectivity
To access the GC Allocator UI, customers need to authenticate via the Single Sign-On (SSO) portal where whitelisting of the SSO portal IP listed below may be required.
Environment | Single Sign-On DNS Name | Whitelist IP |
---|---|---|
New Release | 164.74.123.178 | |
Production | 205.209.196.82 |
Environment | DNS Name |
---|---|
New Release | |
Production |
System Availability
CME GC Allocator API is available in Production beginning 12:05 PM Central Time Sunday afternoon through 9 PM Central Time Friday.
Functional Specification
Allocations
For both US and EU markets, GC Repo sellers may submit trade allocations for their firm’s trades. GC Repo trades are subject to submission deadlines and validations.
Substitutions
Substitutions are available for a subset of GC Repo instruments in the US Market only. GC Repos can be traded with ‘rights of substitution’ (pre-listed or custom). Substitutions allow the GC Repo seller to recall and replace collateral from active allocations.
Upon substitution, the cash considerations and principal value of the collateral of the trade are re-established.
Underlying Bond Price Override for GC Repo Trades
Cancels and amends are considered "top day" while the markets are still open for the same business date.
Underlying price override is enacted when the bond is not priced correctly or is null for an untradeable instrument.
Underlying bond price override only applies to EU Repos.
For GC Repos - underlying price override is applicable to allocations of a GC Repo Trade; once allocations are cancelled by the GCC (Global Command Center), the trade remains unallocated and reallocation can then be enacted by GCC via a customer request.
Validations
Validations are performed on allocations and substitutions for: type of underlying instrument, time, price, quantity, rights of substitution, and number of collateral (trades can have a maximum number of different bonds allocated to them).
Alerts and Warnings
Alerts and warnings are sent for various events, including:
New GC Repo trades executed on Global Front End Application (GFE)
Unallocated GC Repo trades approaching allocation deadline
New GC Repo trade allocations
Notification of intent to substitute
GC Repo trade substitutions
Trade Collateral approaching its maturity date (US markets only)
Timers
Soft and hard deadlines are set for allocations and substitutions.
Timestamps
All timestamps have microsecond precision.
Scenarios
Scenario One - Customer Allocation
In this scenario, a customer searches their firm's trades for those which are not allocated, and then look up and allocate valued collateral.
Customer searches their firm's trades for those which have not been fully allocated by submitting a GET request, including Status parameters to the endpoint:
Search: /trades/search?collateralStatus=NONE&collateralStatus=PARTIAL;
Return: HTTP 200 (OK) with a TradeResponseMessage with two trades in response.
Customer looks up the collateral allocations for one of those trades by submitting a GET request including the Side GUID to the endpoint /collateral/trades/ABC123; gets back an HTTP 200 (OK) with a CollateralResponseMessage with one allocation.
Customer looks up valid collateral for the general collateral on the repo instrument by submitting a GET request including the Side GUID to the endpoint /instrument/trades/ABC123; gets back an HTTP 200 (OK) with an InstrumentResponseMessage listing all eligible underlying collateral.
Customer allocates collateral by submitting a POST to /collateral, using a CollateralRequestMessage specifying their allocation; gets back an HTTP 200 (OK) with a link to the allocation.
Scenario Two - Customer Substitution
Customer 1 notifies their counterparty of an intent to substitute the allocation they made previously, by submitting a POST to /notifications, using a CollateralNotificationRequestMessage to indicate which allocation, and what quantity will be substituted; gets back an HTTP 200 (OK) with a CollateralNotificationResponseMessage showing their notification.
Customer 2 polls for notifications, by submitting a GET request including the AcknowledgementStatus parameter to /notifications/search?acknowledgementStatus=NOTIFIED; gets back an HTTP 200 (OK) with a CollateralNotificationResponseMessage indicating the allocation on which Customer 1 submitted their notification, as well as an identifier for the notification itself.
Customer 2 acknowledges notification by submitting a POST to /notifications/acknowledgements/, using a CollateralNotificationRequestMessage to indicate which allocation's notification they were responding to; gets back an HTTP 200 (OK) with an updated CollateralNotificationResponseMessage record
(Optional) Customer 1 searches for acknowledged notifications by submitting a GET request including the AcknowledgementStatus parameter to /notifications/search?acknkowledgementStatus=ACKNOWLEDGED; gets back an HTTP 200 (OK) CollateralNotificationResponseMessage with their allocation, showing that their notification has been acknowledged (NOTE: because acknowledgement is not required prior to substitution, this field will be set to ACKNOWLEDGED on the seller's side as soon as the notification is submitted).
Customer 1 substitutes their allocation by submitting a POST to /collateral/substitutions/, using a CollateralRequestMessage to define the substitution; gets back an HTTP 200 (OK) with links to the original allocation, the substitution, and the remaining allocation if appropriate.
Scenario Three - Underlying Bond Price Override for GC Trades
Customer contacts the Global Command Center (GCC) and requests the cancellation of a GC Trade allocation.
The GCC cancels the GC Trade allocation and sends the Notification Request message to indicate the cancellation; receives an HTTP 200 (OK) with a Collateral Notification Response Message showing the notification.
Customer polls for notifications by submitting a GET request including the Acknowledgment Status parameter to /notifications/search?acknowledgementStatus=NOTIFIED; receives an HTTP 200 (OK) with a Collateral Notification Response Message indicating the allocation on which GCC submitted cancellation.
(Optional) Customer requests GC Trade allocation for the previously cancelled GC allocator.
GCC allocates collateral by submitting a POST to /collateral, using a Collateral Request Message specifying their allocation; receives an HTTP 200 (OK) with a link to the allocation
Customer polls for notifications, by submitting a GET request including the Acknowledgement Status parameter to /notifications/search?acknowledgementStatus=NOTIFIED; receives an HTTP 200 (OK) with a Collateral Notification Response Message indicating the allocation on which GCC submitted their notification, as well as an identifier for the notification itself.
How was your Client Systems Wiki Experience? Submit Feedback
Copyright © 2024 CME Group Inc. All rights reserved.