CME GC Allocation 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 Allocation 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 Allocation, the InstrumentGUID for AON instruments is always retained.
|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: |
30 Sep 2020
Added Onboarding details.
Added Error code details.
|20 Aug 2020|
Removed verbiage excluding All Or None trades from GC Allocation 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.|
CME GC Allocation API uses OAuth, an open protocol that supports secure authorization in a simple, standard method and decouples authentication from authorization.
A registered OAuth API ID is required to access the CME GC Allocation API services. API IDs for CME Group Logins are created and managed in the Customer Center under My Profile.
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 Allocation API access and more information.
Testing and Certification
Certification is required for GC Allocation API services. Please contact Certification Support for Electronic Trading (CSET).
Roles are required for CME GC Allocation API.
- GC Allocation API --Allocator (Trader/Clerk)
- External Workstation - Allocator (Trader/Clerk)
- External Workstation - GC Allocation Viewer
During a disaster recovery (DR) event clients will automatically be directed to the DR instance of GC Allocation API. Clients do not need to make any connectivity changes.
GC Allocation API Connectivity
GC Allocation UI Connectivity
To access the GC Allocation 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|
CME GC Allocation API is available in Production beginning 12:05 PM Central Time Sunday afternoon through 9 PM Central Time Friday.
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 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 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)
Soft and hard deadlines are set for allocations and substitutions.
All timestamps have nanosecond precision.
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. (NOTE: the two customers will receive different notificationGuids)
- 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 (NOTE: a notification must be sent prior to a substitution, but it is not required that the notification be acknowledged).
- (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 allocation.
- 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.