General Inquiries, Onboarding, and Product Support: support@provablemarkets.com
Provable Markets LLC (PML) is a New York-based FINRA broker-dealer committed to enhance efficiency, reduce risk and strengthen market structure for cash and synthetic equity finance trading. PML operates the cloud-native SEC Registered Alternative Trading System (“ATS”) Aurora that optimizes securities lending workflows, delivering seamless execution, pre and post-trade operational efficiencies, and risk reduction across the full value chain. Aurora operates as the only regulated Approved Submitter for the Depository Trust and Clearing Corporation’s (“DTCC”) Securities Finance Transaction (“SFT”) Clearing Service, providing full-service National Securities Clearing Corporation (“NSCC”) members and Sponsored Member firms access to central clearing and settlement for overnight borrows and loans on eligible NSCC securities.
The purpose of this document is to outline the technical connectivity specifications for the Aurora ATS. Specifically, this document:
The information contained in this document is preliminary and conceptual to establish a basis for a standardized protocol for use of Aurora and broader market securities lending workflows. As such, it is for informational purposes only; message structures are subject to and likely may change. In addition, some features may be pending product delivery. Please coordinate with your PML representative prior to beginning any development work based on the message specifications outlined in this document.
The following high level functionalities are available on Aurora:
Aurora allows for centralized price discovery, liquidity discovery, and automated matching of contracts in US securities. As an Approved SFT Submitter, Aurora also offers straight-through processing into the DTCC SFT Clearing Service.
Aurora allows for centralized price discovery, liquidity discovery, and automated matching of contracts and borrows in US securities. As an Approved SFT Submitter, Aurora also offers straight-through processing into the DTCC SFT Clearing Service.
Subscribers to Aurora have the option to agree on contract economics off-platform and submit as a Manual Contract into Aurora to benefit from the interface for contract lifecycle management post-match.
Aurora offers Subscribers a custom Web API capable of managing the full contract lifecycle, including support for the recall and return of contracts and the ability to propose a contract rebate modification.
The calculated settlement amounts of contracts generated or confirmed on Aurora follow established market convention. In this section we describe the relationship between various point-of-trade values on Aurora to corresponding values in the settlement layer.
Each contract on Aurora has the following five input values, all of which are known at the time of trade:
This is the official closing price for the security at the end of the previous trading day, used to value the current day's contract. The value is sent by Aurora
as last_close_price in response to the ListContracts endpoint.
This is the number of shares to be borrowed or loaned.
For order book messages this value is contained in quantity within orders or
as last_quantity for the unsolicited messages.
Where Manual Contracts are being confirmed on Aurora, also a quantity field is used.
In line with existing convention, the terms of the contract may require that the borrower places additional collateral against the contract. The percentage of collateralization is known as the Collateral Rate. For NSCC SFTs this value is 100 + the NSCC’s “Independent Amount”.
This is the (annualized) interest rebate charged on the contract, based on a 360-day year. A negative value represents payment from the borrower to the lender while a positive value represents payment from the lender to the borrower.
In Order Book messaging workflows, the fields price and last_price are used to indicate rebate at
the order- and execution level.
In all other workflows, the rebate is carried in the custom rebate (or rate) and benchmark fields where benchmark refers to one of the reference benchmarks NoBenchmark, OBFR, EFFR, SOFR, BGCR, TGCR or IORB.
Fee (-1 * “Spread”) This is the fee charged on the contract, relative to the applicable benchmark.
Per convention, the settled collateralized value of the security used in the calculation for the contract is always rounded up (never down) to an indicated monetary increment. Accepted values are NO_ROUNDING, UP_TO_NEAREST_0_DOT_01, UP_TO_NEAREST_0_DOT_05,
UP_TO_NEAREST_0_DOT_10, UP_TO_NEAREST_0_DOT_25, UP_TO_NEAREST_1_DOT_0.
Once the input values above are known, the following settlement values are calculated and echoed on relevant messages:
Collateral Price = Round (Closing Price x Collateral Rate)
This is an adjusted, rounded price per share loaned or borrowed, taking into account both the required collateral rate and rounding rule. For example, consider a contract for a share which closed at $100.03 with a collateral rate of 102%, then:
Collateral Price = Round (100.03 x 1.02) = Round (102.0306)
If the rounding rule was to round to the nearest quarter, this gives a Collateral Price of $102.25. Note that the rounding is always up for this calculation.
Contract Value = Contract Quantity x Collateral Price
With the Collateral Price known, the total Contract Value is calculated by multiplying it by the Contract Quantity.
If the contract above were for 10 shares, then the Contract Value would equal $1,022.50.
This calculated value is present in messages in the contract_details as contract_value.
Rebate Amount = Contract Value x ( Rebate / 360 )
The daily interest amount can now be calculated using a simple interest calculation, assuming a 360-day year. A positive amount represents cash owed to the borrower from the lender, whereas a negative amount refers to a Transfer in the opposite direction.
If the Rebate agreed in our previous example was 5%, then the daily RebateAmount would be:
Rebate Amount = $1,022.50 x 0.05 / 360 = $0.14
The calculated interest due on a daily basis is in messages in the contract_details as interest_due_amount.
Contract Value Adjustment = Contract Value - ( Contract Quantity x Closing Price )
This calculated value measures the additional collateralization of the contract in excess of the underlying stock value. It is the monetary impact of the Collateral Rate and the effect of the Rounding Rule.
This value is presented in messages in the contract_details as contract_value_adjustment.
To be completed; please reach out to Provable Markets for further information.
Aurora will be closed for US exchange holidays but remains open for US bank holidays in accordance with the DTCC settlement timelines.
Aurora can be accessed between 04:00 and 18:00 Eastern Time. Within this technical connectivity availability window, the range of actions available may be influenced by the timelines of the settlement and/or clearing service. The following table summarizes key time windows.
Aurora daily schedule (all times are ET)
| Session Management | Timing | Description |
|---|---|---|
| System Availability | 04:00 - 18:00 | Subscribers should establish a Web API session to Aurora shortly after the system becomes available at 04:00 and stay connected until 18:00. |
| Order Book | Timing | Description |
|---|---|---|
| Order Entry | 04:00 - 15:00 | Orders may be placed into Aurora, with active orders considered for matching. |
| Order Matching | 04:00 - 15:00 | An order matched during this phase results in a contract being submitted for settlement and/or clearing. |
| Market Data | 04:00 - 15:00 | Subscribers may request order book market data during this phase. |
| Manual Contract Matching | Timing | Description |
|---|---|---|
| Contract Propose | 04:00 - 15:00 | Lenders may propose loans against borrowers during this phase. If accepted, the contract will be processed for settlement and/or clearing. Proposed contracts not accepted on the same day within the “contract acceptance” window will expire. |
| Contract Acceptance | 04:00 - 15:00 | Borrowers may accept (or reject) contracts proposed by lenders. If accepted, the contract will be processed for settlement and/or clearing. |
| Contract Management | Timing | Description |
|---|---|---|
| Contract Status | 04:00 - 18:00 | Aurora is available to query contract status at any point during the System Availability window. Note, contracts cleared and settled through the SFT Clearing Service are rolled between 04:00-11:30, which will cause Aurora to update the contract status and therefore send unsolicited ContractStatusReport [UA] messages. |
| Contract Return | 04:00 - 15:00 | Instructions to return contracts may be entered. |
| Contract Recall | 04:00 - 16:30 | Recall instructions received before 15:00 will be processed the same day (buy-in expected two business days later). Recalls after this time will be processed the next business day (buy-in three days later). |
| Rebate Modification | 04:00 - 15:45 | While messages may be submitted and confirmed during this time, downstream processing only occurs after this time upon completion of certain end-of-day events. Any proposed rebate change which is not accepted within this window will expire. |
| Buy-In Submission & Processing | 15:10 - 17:00 | Where a contract has been recalled but not returned (and the earliest buy-in execution date has been reached), lenders may buy-in the stock and submit the execution details through a buy-in message to Aurora which will be processed by downstream providers between 16:30 and 17:00. |
Connect is a family of libraries for building browser and gRPC-compatible HTTP APIs.
Connect servers and clients support three protocols: gRPC, gRPC-Web, and Connect's own protocol.
The instrument field is used for identifying instruments across Aurora. Aurora accepts securities to be identified either
by their CUSIP or their commonly-known exchange ticker symbol.
For inbound messages, Subscribers can use the CUSIP or the Ticker Symbol to identify the instrument.
For outbound messages, Aurora will always populate both instrument.ticker and instrument.cusip with the symbol and the CUSIP of the
instrument.
The Parties component is used for identifying Subscribers within Aurora.
The field counterparty_id can be used to address a counterparty.
Due to the asynchronous nature of Aurora message processing, a set of events are available for customers through a number of different channels.
Customers are required to communicate with the Aurora team (eg support@provablemarkets.com) over which event categories they are interested in subscribing to.
The following categories are available:
| Category | List of events |
|---|---|
| CONTRACTS | Contract Events |
| CONTRACT REQUESTS | Contract Request Events |
| ORDERS | OMS Events |
| MARKETPLACE | Marketplace Events |
| EXECUTIONS | Execution Events |
Customers can subscribe to all of them or to any subset of specified categories.
To receive unsolicited messages from the Aurora over Webhook connection type in real-time,
customers must implement a Webhook service on their side.
The Webhook service should be capable of receiving HTTP POST requests with JSON payloads.
Below are the requirements and specifications for setting up the Webhook service.
POSTapplication/jsonBasic Auth or HMAC Auth or API KeyCustomers are required to inform the Aurora team (eg support@provablemarkets.com) which type of authentication they are interested in applying for webhook communication.
The payload sent by Aurora will be in JSON format represented as AuroraMessage.
Below is an example of the JSON structure you can expect:
{
"msgId": "b1a354b1-e52c-4c47-a660-f1832be48d5e",
"msgType": "aurora.core.apiengine.omsv1.OrderCreatedEvent",
"msgPayload": "...",
"timestamp": "2024-01-24T12:45:26.295Z"
}
To ensure the authenticity of the requests, Aurora can use one of available authentication
methods.
Aurora will then provide customers the auth details of the selected method, and it is the
responsibility of the customer to enforce the authentication on server side.
Aurora will try to deliver all events with an at least once policy.
In case of delivery failures an Exponential Backoff strategy is applied, and deliveries
will be retried indefinitely.
Events are delivered in chronological order. If the receiver is not successfully acknowledging
receipt of a message, we will halt delivery of subsequent messages until the receiver has recovered.
Acknowledging is done by returning a successful HTTP status code (eg a 200 OK) as a response to the call.
To receive unsolicited messages from the Aurora over RPCHooks in real-time, customers must
implement an RPC service on their side.
The RPC service should be capable of handling the method calls defined by the Aurora spec.
Below are the requirements and specifications for setting up the RPC service.
Basic Auth or HMAC Auth or API KeyThese details should be communicated with the Aurora team (eg support@provablemarkets.com) so they can be enabled.
The RPC service should expose the following method services:
For handling Executions the documented Execution Events
For handling Contracts the documented Contract Service Events
For handling Contract Requests the documented Contract Request Service Events
For handling Marketplace the documented Venue Service Events
For handling Orders the documented OMS Service Events
To ensure the authenticity of the requests, Aurora can use one of available authentication
methods.
Aurora will then provide customers the auth details of the selected method, and it is the
responsibility of the customer to enforce the authentication on server side.
Aurora will try to deliver all events with an at least once policy.
In case of delivery failures an Exponential Backoff strategy is applied, and deliveries
will be retried indefinitely.
Events are delivered in chronological order. If the receiver is not successfully acknowledging
receipt of a message, we will halt delivery of subsequent messages until the receiver has recovered.
Acknowledging is done by returning a successful HTTP status code (eg a 200 OK) as a response to the call.
Clients can configure the authentication method to be used for securing requests sent by Aurora. The available authentication methods are:
Basic Authentication requires the client to provide a username and password provided by the client. The Authorization header will be included in each webhook request.
POST /webhook HTTP/1.1
Host: client.service
Authorization: Basic Y2xpZW50X3VzZXJuYW1lOmNsaWVudF9wYXNzd29yZA==
Content-Type: application/json
{
"msgId": "b1a354b1-e52c-4c47-a660-f1832be48d5e",
"msgType": "aurora.core.apiengine.omsv1.OrderCreatedEvent",
"msgPayload": "...",
"timestamp": "2024-01-24T12:45:26.295Z"
}
Note: The Authorization header value is the Base64 encoded string of username:password.
HMAC (Hash-based Message Authentication Code) signing uses a secret key provided by the client to generate a signature for each request. The signature is included in the Authorization header. Additionally Digest header is included.
POST /webhook HTTP/1.1
Host: client.service
Digest: DmBmbfpKVHor+7JKWh/X4Gz73r/ec3OQjBr5EWgxY00=
Authorization: hmac-username="usr", hmac-signature="nkA3PFvPG8wpSRKBeNHPFxvhfeQqAHYOkPAYIKkzI+U="
Content-Type: application/json
{
"msgId": "b1a354b1-e52c-4c47-a660-f1832be48d5e",
"msgType": "aurora.core.apiengine.omsv1.OrderCreatedEvent",
"msgPayload": "...",
"timestamp": "2024-01-24T12:45:26.295Z"
}
Note: The Digest is computed as sha256(payload), where payload is the JSON body of the request. The hmac-signature is computed as sha256(digest + secret)
The API Key method requires an API key provided by the client to be included in the Authorization header for each request.
POST /webhook HTTP/1.1
Host: client.service
Authorization: X-API-KEY nkA3PFvPG8wpSRKBeNHPFxvhfeQqAHYOkPAYIKkzI+U=
Content-Type: application/json
{
"msgId": "b1a354b1-e52c-4c47-a660-f1832be48d5e",
"msgType": "aurora.core.apiengine.omsv1.OrderCreatedEvent",
"msgPayload": "...",
"timestamp": "2024-01-24T12:45:26.295Z"
}
Note: The Authorization header will have the value X-API-KEY client_api_key.
Customers can connect to Aurora via a WebSocket to receive unsolicited messages in real-time.
To establish a WebSocket connection, the customer must perform a web socket handshake.
Once the connection is established, Aurora will send unsolicited messages over the connection.
The payload sent by Aurora will be in JSON format represented as AuroraMessage.
Below is an example of the JSON structure you can expect:
{
"msgId": "b1a354b1-e52c-4c47-a660-f1832be48d5e",
"msgType": "aurora.core.apiengine.omsv1.OrderCreatedEvent",
"msgPayload": "...",
"timestamp": "2024-01-24T12:45:26.295Z"
}
To ensure secure communication:
Here is an example of how to open a websocket connection:
websocat wss://provablemarkets.com/api/1/websocket/events -H "Authorization: Bearer $API_KEY" -H "X-CONNECTION-CONFIG-ID: $CONFIG_ID"
The Company Service allows you to retrieve a list of eligible companies.
API Reference: CompanyService/ListCompanies
All methods of the Aurora Connect-API require an access token.
You can call the method LoginWithApiCredentials to get yours.
Please note that your access token will have a TTL of 1 week.
API Reference: LoginService/LoginWithApiCredentials
The Aurora Configuration Service API allows customers to manage their connection configurations and event subscriptions for unsolicited events.
It allows to create, fetch, update, and delete connection configurations, as well as manage event subscriptions.
Customers are required to communicate with the Aurora team (eg support@provablemarkets.com) over which event categories they are interested in subscribing to.
Aurora currently supports two connection types
Aurora innovates securities lending by implementing a central limit order book that resembles other modern financial markets. Prospective borrowers and lenders can enter competitive orders to be matched against counterparties to generate contracts.
For easy integration, please respect the following definitions to fit the securities lending domain and the value proposition of the Aurora Marketplace.
The side field accepts the values of BORROW and LOAN.
The Aurora order book currently accepts standard limit and market orders in field order_type using the values of LIMIT and MARKET. These operate similar to most order books. By convention limit orders require a rate field indicating maximum or minimum interest rate (rebate) to be paid / received as a percentage of the contract amount. Market orders are only valid with time_in_force of IOC or FOK or with order_intent IOI.
Subscribers may stage orders before entering them in the order book by setting an active value of False.
This allows Subscribers to have straight through processing of borrow or lending interest into the system, where they can later indicate routing decisions or apply trade parameters into the Provable Markets Marketplace venue, alternative venues, or automation strategies.
Provable Marketplace supports two values for order_intent, "FIRM" (tradable) and "IOI" (Conditional or not tradable. Firm orders represent an intent to borrow or lend for the full quantity at the rate represented to any party to which the order is exposed (see Agreement Filtering). IOI orders represent an interest to borrow or lend, which is a non-binding, non-executable request that signals a trader’s willingness to transact if a suitable match is found.
Provable recommends that orders displayed in the Orderbook as Firm are actively or systematically monitored for accuracy. PM monitors subscriber activity for fail rates, and may consult with clients on the usage of the platform or temporarily block access in cases of nonconformance with best practices. IOIs are not considered for market access exposure limits.
Given the above, a subscriber may find it most suitable to express Lending or Borrowing interest in the form of an IOI initially. When a counterparty (CP) order enters the Marketplace which is a suitable potential match for the IOI, the original IOI sender can respond with a firm order (sometimes slightly modifying the rate or quantity) to replace the IOI. The firm order - assuming the parameters match - will match against the CP order and generate an execution for both parties.
Provable Marketplace uses “Agreements” to manage the relationship between counterparties. Counterparty agreements represent various trade parameters shared with a given counterparty. When Agreement(s) are applied to an order, they isolate the range of potential match outcomes to reduce the risk of misalignment on trade details between counterparties after execution.
PM recommends sending individual agreement ID(s) to achieve the most direct result. However, PM supports directly sending certain parameters of an Agreement on an Order basis.
When Agreement parameters are sent on a CreateOrder or ModifyOrder the parameters act as an AND condition, narrowing the set of applicable agreements by the applied parameters.
Subscribers must have at least one agreement meeting the specified criteria, or the order will reject. Subscribers can use the following inputs to filter Agreements and matching outcomes: Counterparty via booking_accounts, collateral_currencies, collateral_types, counterparty_booking_accounts, counterparty_ids, delivery_types, ids, settlement_types and trade_types.
If no Agreement ID or Agreement parameters are passed then the Order will be created with all applicable counterparty agreements eligible.
Within the Aurora order book, prospective market participants compete on contract rates they are willing to pay or receive. This positive or negative rate is described as the “Rebate” in the Order/Contract Inputs and Calculations section and is expressed as a float value representing the interest rate percentage or fee.
By default, all orders within the Aurora order book are visible and attributed in market data, however they are only visible to eligible subscribers based on the Agreements provided.
Matches in the order book are immediately confirmed by a OrderExecutedEvent message.
Since Aurora offers settlement of contracts, however, the OrderExecutedEvent message will be followed by an unsolicited, ContractCreated message as the first entry-point into the contract lifecycle workflow, described later in this document.
Subscribers may place limit orders into the Aurora order book to either borrow or lend securities using a CreateOrderRequest message.
Matches in the order book are immediately confirmed with the OrderCreated event. When using Aurora for the settlement of contracts. The OrderExecuted event will follow. Then the ContractCreated event will be received as the first entry-point into the contract lifecycle workflow, described later in this document.
All firm limit orders which are not immediately filled upon entry into the order book will appear to authorized subscribers (where the order has been exposed to them, via the Agreements terms) in the market data snapshot until they expire. These orders will appear as attributed in market data, based on the anonymous field.
Orders entered into Aurora will initially be acknowledged by returning an order ID in the order_ref field.
Accepted firm orders will then be considered for matching against other orders already in the order book generating zero, one, or multiple fills.
In cases where Subscribers are using Aurora to manage the contract lifecycle, each fill or partial fill will be conveyed using an ContractCreated event, indicating entry into the post-trade contract management cycle.
The rate_details and quantity fields on these messages will indicate the rebate and quantity of the fill.
Should an order have any remaining, unmatched quantity after this initial series of fills, then this remaining quantity will
either be placed into the order book or immediately expired, depending on the time_in_force instruction on the original order.
Orders with a time_in_force value of DAY will expire at the end of the day (see Daily Schedule).
Expiry events are conveyed using an OrderExpiredEvent message.
API Reference: OmsService/CreateOrder
API Reference: OmsEventsService/OrderCreated
API Reference: OmsEventsService/OrderExecuted
API Reference: OmsEventsService/OrderExecuted
API Reference: OmsEventsService/OrderExecuted
API Reference: OmsEventsService/OrderExpired
Subscribers may attempt to amend and cancel any open order using the ModifyOrderRequest or CancelOrderRequest message respectively.
In both cases, the order to be amended is identified using the order_ref value relating to the order.
The modification message will also contain a fresh order_ref value which can then be used by the Subscriber to further modify the order if required.
If the order has been successfully modified or canceled, Aurora will respond with an OrderModifiedEvent message which echoes many of the key (updated) order attributes.
If the order cannot be modified or canceled for any reason (for example, because it has already been fully filled or had already expired), Aurora will respond with an error message, indicating the reason for the rejection. Note the order_status in the event indicates the current status of the order after the modification or cancellation failure has been taken into account.
API Reference: OmsService/CancelOrder
API Reference: OmsEventsService/OrderCanceled
Since orders may remain in Aurora for multiple days, it is possible to request a status report of all open orders using the
ListOrdersRequest message, including filter parameters, if required.
Aurora will respond with a stream of OrderDetails messages, each reporting the status of an open order in the platform.
API Reference: OmsService/ModifyOrder
API Reference: OmsEventsService/OrderModified
API Reference: OmsEventsService/OrderClosed
API Reference: OmsService/ListOrders
API Reference: OmsService/GetOrder
Both borrowers and lenders may place orders into the OMS (private holding blotter) before making them available to other Aurora venue subscribers. These orders are not available for matching and do not appear in market data snapshots or quotes.
To do this, the Subscriber should submit a standard CreateOrderRequest message, setting an active value of False
Similar to orders sent to the Aurora Marketplace venue, successful entry of a staged order is either acknowledged or rejected using the standard CreateOrderResponse message. Since staged (i.e. inactive) orders do not pass into the venue order book, they will not appear
in market data and cannot receive fills.
Staged orders can be modified using the ModifyOrderRequest message or canceled using the CancelOrderRequest message.
To allow orders to be moved between staged and immediately executable in the order book, Aurora lets Subscribers modify the active field value on orders.
API Reference: OmsService/CreateOrder
API Reference: OmsService/ModifyOrder
The Agreements Service allows you to retrieve a list of current agreements with counterparties for trading. You can also create new agreements, modify agreements and approve or reject agreements.
API Reference: AgreementService/ListAgreements
API Reference: AgreementService/ApproveAgreement
API Reference: AgreementService/CancelAgreement
API Reference: AgreementService/CreateAgreement
API Reference: AgreementService/GetAgreement
API Reference: AgreementService/ModifyAgreement
API Reference: AgreementService/RejectAgreement
The Instrument Service allows you to retrieve a list of eligible securities (instruments) for trading.
API Reference: InstrumentService/ListCompanies
The Execution Service allows you to retrieve and acknowledge executions.
API Reference: ExecutionService/ListExecutions
API Reference: ExecutionService/AckExecutions
API Reference: ExecutionEventsService/Execution
Subscribers may query the current order book using QueryOrderBookDetailedRequest message.
If the QueryOrderBookDetailedRequest message is valid, Aurora responds with a single QueryOrderBookDetailedRequestResponse message providing details of all orders in the order book (all levels as a repeating group within a single message). Note that Aurora also returns this message when there are no instruments in the order book.
Orders detailed in the QueryOrderBookDetailedRequestResponse response will be attributed in nature (based on the current anonymous
value default). Attributed orders will contain the Parties block, containing the identity of the order originator.
If market data can not be returned for any reason, the orders list will be empty.
API Reference: VenueService/QueryOrderBookDetailed
API Reference: VenueEventsService/OrderAdded
API Reference: VenueEventsService/OrderRemoved
As an alternative to confirming contract details by matching with an eligible counterparty in the Marketplace, Provable Markets provides Subscribers with a convenient workflow for managing contracts, beginning with Contract Booking. Aurora provides a confirmation mechanism to allow Subscribers to enter manually-agreed contracts into the platform.
Note that in order to initiate the contract, Aurora seeks to conclude the manual contract confirmation process within the same
trading day and before relevant clearing and/or settlement deadlines. For this reason,
unmatched manual contracts are automatically expired at the end of each day.
See Expiry of Unmatched Manual Contracts for more information.
Entering Manual Contract Requests
The workflow to confirm and submit for clearing a contract matched outside of Aurora begins when one party to the trade
submits a SubmitContractRequest message providing the key contract details and the contra’s identity.
When booking a manual contract, Aurora subscribers can leverage functionality linking the underlying contract to a commonly-known
benchmark rate by setting the benchmark field.
rate and set benchmark to empty.benchmark to OBFR, EFFR, SOFR, BGCR, TGCR, or IORB
to identify the benchmark and add an offset to that benchmark using rate.
Note that this offset may be either positive or negative.Aurora will log the proposed contract details, allocate it a unique contract_display_id reference, and immediately respond with a
SubmitContractRequestResponse message. This message indicates whether the trade capture has been accepted by the system for
processing using the status field.
Once the SubmitContractRequest has been accepted by Aurora, it will send an outbound, unsolicited ContractRequestOpenedEvent
message to the party indicated in the report, in order to confirm the details. This outbound message will present
the proposed contract details as well as the unique contract_display_id reference, as the borrower will need to quote this to confirm or reject the contract.
API Reference: ContractRequestService/SubmitContractRequest
API Reference: ContractRequestEventsService/ContractRequestOpened
API Reference: ContractRequestService/DeclineContractRequest
API Reference: ContractRequestEventsService/ContractRequestDeclined
API Reference: ContractRequestService/AcceptContractRequest
API Reference: ContractRequestEventsService/ContractRequestAccepted
API Reference: ContractEventsService/ContractCreated
API Reference: ContractRequestService/SubmitContractRequest
API Reference: ContractRequestService/SubmitContractRequest
API Reference: ContractRequestEventsService/ContractRequestAccepted
API Reference: ContractEventsService/ContractCreated
Since the manual trade confirmation process is asynchronous in nature (i.e. there is a potentially significant delay between the lender proposing a contract and the borrower accepting it), the workflow places an proposed trade into a “PENDING” state until the borrower has responded.
If, during the window before the borrower accepts a contract, the lender realizes that there has been an error in their
proposal, they may cancel their proposed contract by submitting a second CancelContractRequest message, indicating the
contract_display_id of the original submission.
This will immediately cancel the original proposed manual contract, and both parties will receive a ContractRequestCanceledEvent
message.
API Reference: ContractRequestService/CancelContractRequest
API Reference: ContractRequestEventsService/ContractRequestCancelled
The process of responding to proposed manual contracts is manual and may extend over extended periods of time. Aurora therefore provides a mechanism for Subscribers to request a list of pending manual contract proposals to see a clear picture of what is still outstanding.
This is triggered by a Subscriber sending a QueryContractRequests message. This message may optionally include a variety of filtering parameters. To prevent erroneously broad queries, the message results are capped at 100 unique contract requests.
Aurora will initially respond with a standard QueryContractRequestsResponse message, which includes a count of the found reports in number_of_contracts.
These will then be streamed individually using a series of outbound QueryContractRequestResponse messages as described previously.
API Reference: ContractRequestService/QueryContractRequests
As described at the start of the section, Aurora seeks to conclude the manual trade capture and confirmation process on the same day, and before relevant clearing and/or settlement deadlines.
Unmatched manual contracts are therefore auto-expired at the end of each trading day.
This action is communicated to lenders using an unsolicited ContractRequestCanceledEvent message.
Borrowers will also receive an unsolicited ContractRequestCanceledEvent.
API Reference: ContractRequestEventsService/ContractRequestCanceled
Not only does Aurora provide Subscribers the ability to electronically identify counterparties and agree contracts, it also acts as an interface for the settlement and management of those contracts.
While Aurora has been designed to be real-time in nature, the processing of contracts still requires confirmation within DTC. This means that many of the contract lifecycle processes are asynchronous - Aurora may acknowledge an action in real-time, but there may be a delay until DTC confirms successful processing - and therefore various status fields will contain “PENDING” states to bridge this time gap.
Aurora is designed to facilitate the majority of interactions for clearing and record keeping, but the initialization of a
contract still requires the Deliver Order (DO) message and sufficient assets to make delivery.
When a contract is either automatically matched or confirmed on Aurora, it is submitted to clearing providers and the status
is marked as “PENDING”. The counterparties have until the end of the day to make delivery on the contract. If this doesn't
happen by the time of the DTC drop, the contract will be considered “DROPPED”, and both parties will be notified by Aurora
by an unsolicited contract message with status is DROPPED.
display_id vs settlement_idContracts may be represented by downstream clearing and settlement providers (e.g. DTCC SFT Clearing Service) as overnight contracts and allocated a unique contract ID which is valid for a single day only. Subscribers may find this contract ID using
the custom settlement_id field in the GetContract messages.
For Lenders wishing to initiate the Deliver Order (DO) themselves, this ID must be consumed from ContractCreated
message and provided on the DO
message to link the delivery to the pending SFT. The status field will transition to OPEN when the SFT On Leg has made.
In addition, Aurora allocates a unique display_id to all contracts matched on the platform,
either in the order book or confirmed via manual contract processing. This unique display_id remains the same for the lifetime of the contract.
request_idIt is a standard pattern that request-style messages contain a string identifier which is then echoed in response
messages to allow the Subscriber to match up the input message to one or more output messages. The request_id which
is part of most message addresses this issue.
The asynchronous and complex nature of the contract lifecycle would - ordinarily - require the definition of a large number
of such unique references which seems excessive given the comparatively slow-moving nature of the lifecycle. For this reason,
the API simply re-uses a single such identifier of request_id in a variety of scenarios.
An important message in the contract lifecycle workflow are the ContractStatusReport messages, which reports the current status
of the contract over time. This is an outbound message from Aurora, which is sent in the following scenarios:
ListContracts service method,The message contains information on the status of the contract, provides a link between the persistent display_id and the daily
settlement_id, as well as providing a range of elements related to interest rate (rebate) and settlement amounts for the contract.
Provides a list of contracts based on filter criteria.
API Reference: ContractsService/ListContracts
Provides detailed info for a contract.
API Reference: ContractsService/GetContract
Provides the events that occurred for a contract.
API Reference: ContractsService/ListContractHistory
When Aurora OMS matches 2 orders from the order book it will create a Contract
and notify both parties by issuing the ContractCreated service event
API Reference: ContractEventsService/ContractCreated
When a manually created order is accepted by the counterparty, Aurora will create the contract and notify both parties by generating the ContractCreated service event.
API Reference: ContractEventsService/ContractCreated
Example: gRPC websocket event with json payload
When a contract is either automatically matched or confirmed on Aurora, it is submitted to clearing providers and the status is marked as “PENDING”. The counterparties have until the end of the day to make delivery on the contract.
API Reference: ContractEventsService/ContractPending
When a contract settles via the depository. The status is marked as “OPEN”.
API Reference: ContractEventsService/ContractMade
The counterparties have until the end of the day to make delivery on the contract. If this doesn't happen by the time of the DTC drop, the contract will be considered “DROPPED”, and both parties will be notified by Aurora by an unsolicited ContractDropped service event.
API Reference: ContractEventsService/ContractDropped
API Reference: ContractEventsService/ContractRejected
There is a window of time between a contract being agreed on Aurora (either as a result of matching in the order book or
confirming manual contracts) and being processed for downstream settlement. During this window, the status field
of the GetContract message will indicate a status of PENDING.
It is possible for either the borrower or lender to outright cancel the contract during this processing period if
required by submitting a CancelContractRequest message.
Note that this message can only be used before the contract has settled.
Contract cancellation is an asynchronous action that must be confirmed by downstream clearing and settlement partners,
so the canceling party will receive an immediate CancelContractResponse acknowledgement with a status of OK (200) and the contract ID.
If the cancellation is subsequently successful, then both parties will receive an unsolicited CancelContractAcceptedEvent
message with a status value of CANCELED.
If the cancel request is unsuccessful, however, then the Subscriber will receive a CancelContractRejectedEvent message with
an explanation for the rejection. In this case, the original contract proceeds to processing as normal.
API Reference: ContractsService/CancelContract
API Reference: ContractEventsService/CancelContractAccepted
API Reference: ContractEventsService/CancelContractRejected
Since the GetContract message contains a variety of data elements used for contract settlement and management,
Subscribers are encouraged to track them carefully.
As described in the Daily Schedule, Aurora is expected to send a stream of unsolicited ContractRolledEvent messages
each morning for open contracts as the platform confirms that the contract has rolled and/or the price differential has been calculated.
API Reference: ContractEventsService/ContractRolled
API Reference: ContractService/ReturnContract
When (part of) the shares of a contract were returned by the borrower, Aurora will notify the borrower
and the lender by firing the ContractReturnExecuted service event. If the return was in response to
a recall Aurora will also fire the ContractRecallExecuted service event.
API Reference: ContractEventsService/ContractReturnExecuted
API Reference: ContractEventsService/ContractReturnPending
API Reference: ContractEventsService/ContractReturnPendingLenderApproval
API Reference: ContractService/AcceptAwaitingContractReturn
API Reference: ContractService/RejectAwaitingContractReturn
API Reference: ContractService/CancelAwaitingContractReturn
API Reference: ContractEventsService/ContractReturnRejected
API Reference: ContractEventsService/ContractReturnFailed
API Reference: ContractService/CancelSinglePendingReturn
API Reference: ContractService/CancelAllPendingReturns
API Reference: ContractEventsService/ContractReturnCancelAccepted
Should the cancellation of the contract return instruction fail for any reason (such as the cancellation being received
too late to process), the borrower will receive a ContractReturnCancelRejectedEvent service event with a further explanation of the
failure.
API Reference: ContractEventsService/ContractReturnCancelRejected
All Contract Returns that are still pending approval by the lender will be dropped at the end of the day. Both Lender and Borrower will be notified
by emitting the ContractReturnDropped event.
API Reference: ContractEventsService/ContractReturnDropped
This will occur only if the client has set a Return Cutoff time in Aurora.
If the lender accepted the late contract return, the borrower is notified by emitting the ContractReturnAcceptedByLender event
API Reference: ContractEventsService/ContractReturnAcceptedByLender
If the lender rejected the late contract return, the borrower is notified by emitting the ContractReturnRejectedByLender event.
API Reference: ContractEventsService/ContractReturnRejectedByLender
As long as the Lender has not responded to the late Contract Return request, the borrower can still cancel the return. As a result the contract stays open and the contract return is canceled.
API Reference: ContractService/CancelSinglePendingReturn
If the borrower cancels a late contract return the lender will be notified by emitting the ContractReturnCanceledByBorrower event.
API Reference: ContractEventsService/ContractReturnCanceledByBorrower
API Reference: ContractService/RecallContract
API Reference: ContractEventsService/ContractRecallRejected
In case of acceptance by the DTC both parties will be notified by Aurora by sending
the ContractRecallOpened service event.
API Reference: ContractEventsService/ContractRecallOpened
API Reference: ContractService/ReturnContract
When a borrower successfully returns shares in response to a recall request of the lender, or when a lender
executes a buy-in, both the lender and the borrower are notified by Aurora by sending the ContractRecallExecuted service event.
API Reference: ContractEventsService/ContractRecallExecuted
There might be situations in which a lender wishes to amend the quantity of a contract to be recalled. The way in which this is achieved may differ, depending on whether the lender wishes to increase or decrease the recalled quantity.
Should the lender wish to increase the total quantity recalled, then the recommended approach is to send a
new (second) RecallContractRequest with the incremental quantity to be returned.
Shares returned by a borrower will be allocated against multiple open recalls on a first-in-first-out (FIFO) basis.
Should the lender wish to reduce the quantity recalled, however, then they could either:
RecallContractRequest with the lower quantity, orNotes:
The ability to amend a contract recall is currently not supported for contracts initiated through the SFT Clearing Service,
Option (2) has a functional advantage over option (1) in that it will preserve the allowed_execution_date of the
original recall request, thus allowing the lender to receive back their shares sooner. Restarting the process under
option (1) would also reset the allowed_execution_date.
API Reference: ContractService/CancelRecallContract
API Reference: ContractService/CancelAllRecalls
API Reference: ContractEventsService/ContractRecallCanceled
API Reference: ContractEventsService/ContractRecallCancelRejected
When Aurora detects Corp Actions for contracts with open recalls it will notify both parties by
sending the ContractRecallUpdated service event
API Reference: ContractEventsService/ContractRecallUpdated
API Reference: ContractService/ListRecalls
API Reference: ContractService/BuyInContract
API Reference: ContractEventsService/ContractBuyInRejected
API Reference: ContractService/BuyInContract
API Reference: ContractEventsService/ContractBuyInAccepted
API Reference: ContractEventsService/ContractBuyInExecuted
API Reference: ContractService/CreateRateModification
API Reference: ContractEventsService/ContractRateModificationOpened
API Reference: ContractService/AcceptRateModification
API Reference: ContractService/RejectRateModification
Whenever AURORA detects a change in the rebate of a Contract it will trigger
the ContractRateModificationAccepted service event.
API Reference: ContractEventsService/ContractRateModificationAccepted
When both sides have agreed to the Rebate Rate (or Fee) change, Aurora will trigger
the ContractRateModificationExecuted service event.
API Reference: ContractEventsService/ContractRateModificationExecuted
API Reference: ContractEventsService/ContractRateModificationRejected
If both the lender and the borrower of the contract propose exactly the same new rebate, the modification
is automatically accepted and both will receive the unsolicited ContractRateModificationExecuted message.
A contract modification proposed by a lender expires at the end of the day
API Reference: ContractEventsService/ContractRateModificationExpired
API Reference: ContractEventsService/ContractRateModificationCanceled
API Reference: ContractService/CancelRateModification
After a borrower or lender receives a proposal to modify the rebate of an existing contract they may decide to exit the contract, either by returning (in the case of the borrower), or initiating a buy-in (in the case of a lender).
An action that will close a contract makes the contract rebate modification obsolete, and therefore a successful return will
automatically cancel (reject) any outstanding contract rebate modification negotiations for the contract_display_id.
In this case, the proposer and the recipient of the rebate change will receive an unsolicited ContractRateModificationAutoCanceledEvent message.
API Reference: ContractEventsService/ContractRateModificationAutoCanceled
API Reference: ContractService/ListRateModifications
The Aurora Services are split in two parts, Methods and Events.
You can use Methods to submit to and query data from Aurora.
Events are not like methods a service you can call, but they are endpoints that you, as customer, can implement.
Aurora will call these endpoints to notify you of events that occurred in Aurora and concern your data.
For more information on implementing an Event Service you can read about Hooks and Websockets in Unsolicited messages distribution
Aurora offers services in the following categories:
| Category | Description | Methods | Events |
|---|---|---|---|
| Login | Get authenticated and retrieve an access token | Login API | - |
| Contracts | Contract Lifecycle events like Recalls and Buyins | Contract API | Contract Events |
| Contract Requests | Propose and Respond to Contract Requests from your counterparties | Contract Request API | Contract Request Events |
| Orders | Lend and Borrow Orders in the OMS system | OMS API | OMS Events |
| Agreements | Order matching agreements in the OMS system | Agreement API | |
| Venue | Query the Marketplace | Venue API | Venue Events |
| Companies | Query for Counterparties | Company API | |
| Instruments | Query eligible Instruments | Instrument API |
Before you can call any method on Aurora you need to get authenticated and retrieve an access-token. We suggest you start reading about the Login Service first.