# General

# Provable Markets

## Support Contacts

General Inquiries, Onboarding, and Product Support: support@provablemarkets.com

## Introduction

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:

- Defines the message specifications for Aurora using gRPC format,
- Illustrates available workflows in Aurora,
- Defines the roles and responsibilities of Aurora,
- Defines the roles and responsibilities of the Subscriber or sending system to Aurora.


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.

## ATS & Platform Overview

### Functionalities

The following high level functionalities are available on Aurora:

#### Order Management

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.

#### Order Book

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.

#### Manual Contract Entry

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.

#### Contract Lifecycle Management

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.

### Terminology, Inputs, and Calculations

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:

#### Unit Price

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.

#### Contract Quantity

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.

#### Collateral Rate

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

#### Rebate ("Interest Rate")

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.

#### Rounding Rule

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


```
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 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 (Interest) Amount


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

### System Connectivity

To be completed; please reach out to Provable Markets for further information.

### Business Days

Aurora will be closed for US exchange holidays but remains open for US bank holidays in accordance with the DTCC settlement timelines.

### Daily Schedule

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


# Aurora Connect API

## Component Definitions

### Protocol

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.

- Connect fully supports the gRPC protocol, including streaming, trailers, and error details. Any gRPC client, in any language, can call a Connect server, and Connect clients can call any gRPC server. We validate our gRPC compatibility with an extended version of Google's own interoperability tests.
- Connect also offers direct support for the gRPC-Web protocol used by grpc/grpc-web, without relying on a translating proxy like Envoy.
- Finally, Connect supports its own protocol: a straightforward HTTP-based protocol that works over HTTP/1.1, HTTP/2, and HTTP/3. It takes the best parts of gRPC and gRPC-Web, including streaming, and packages them into a protocol that's equally at home in browsers, monoliths, and microservices. By default, implementations support both JSON- and binary-encoded Protobuf.


### Standard Header / Envelope

### Instrument

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.

### Parties

The Parties component is used for identifying Subscribers within Aurora.
The field `counterparty_id` can be used to address a counterparty.

## Unsolicited messages distribution

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***](https://aurora-api-review.redoc.ly/tag/ContractEventsService) |
| CONTRACT REQUESTS | [***Contract Request Events***](https://aurora-api-review.redoc.ly/tag/ContractRequestEventsService) |
| ORDERS | [***OMS Events***](https://aurora-api-review.redoc.ly/tag/OmsEventsService) |
| MARKETPLACE | [***Marketplace Events***](https://aurora-api-review.redoc.ly/tag/VenueEventsService) |
| EXECUTIONS | [***Execution Events***](https://aurora-api-review.redoc.ly/tag/ExecutionEventsService) |


Customers can subscribe to all of them or to any subset of specified categories.

### Webhook

#### Overview

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.

#### Requirements

- Endpoint: The endpoint URL where Aurora will send the HTTP POST requests.
- HTTP Method: `POST`
- Content Type: `application/json`
- Authentication: either `Basic Auth` or `HMAC Auth` or `API Key`
- Optional custom header: expected headers Aurora should include in each request


Customers are required to inform the Aurora team (eg support@provablemarkets.com)
which type of authentication they are interested in applying for webhook communication.

#### JSON Payload

The payload sent by `Aurora` will be in JSON format represented as `AuroraMessage`.
Below is an example of the JSON structure you can expect:


```json
{
  "msgId": "b1a354b1-e52c-4c47-a660-f1832be48d5e",
  "msgType": "aurora.core.apiengine.omsv1.OrderCreatedEvent",
  "msgPayload": "...",
  "timestamp": "2024-01-24T12:45:26.295Z"
}
```

#### Security

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.

#### Delivery

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.

### RPCHooks

#### Overview

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.

#### Requirements

- Endpoint: The base endpoint URL where Aurora will send the HTTP POST requests.
- HTTP version: 2.0
- Authentication: either `Basic Auth` or `HMAC Auth` or `API Key`
- Optional custom header: expected headers Aurora should include in each request


These details should be communicated with the Aurora team (eg support@provablemarkets.com)
so they can be enabled.

#### Service definition

The RPC service should expose the following method services:

For handling Executions [the documented Execution Events](https://aurora-api-review.redoc.ly/tag/ExecutionEventsService)

For handling Contracts [the documented Contract Service Events](https://aurora-api-review.redoc.ly/tag/ContractEventsService)

For handling Contract Requests [the documented Contract Request Service Events](https://aurora-api-review.redoc.ly/tag/ContractRequestEventsService)

For handling Marketplace [the documented Venue Service Events](https://aurora-api-review.redoc.ly/tag/VenueEventsService)

For handling Orders [the documented OMS Service Events](https://aurora-api-review.redoc.ly/tag/OmsEventsService)

#### Security

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.

#### Delivery

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.

### Authentication methods for Webhooks and RPCHooks

Clients can configure the authentication method to be used for securing requests sent by `Aurora`. The available authentication methods are:

1. Basic Authentication
2. HMAC Signing Requests
3. API Key


#### Basic Authentication

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.


```http
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

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.


```http
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)

#### API Key

The API Key method requires an API key provided by the client to be included in the Authorization header for each request.


```http
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.

### Websocket

#### Overview

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.

#### WebSocket Endpoint

- Endpoint: wss://provablemarkets.com/api/1/websocket/events


#### Message format

The payload sent by `Aurora` will be in JSON format represented as `AuroraMessage`.
Below is an example of the JSON structure you can expect:


```json
{
  "msgId": "b1a354b1-e52c-4c47-a660-f1832be48d5e",
  "msgType": "aurora.core.apiengine.omsv1.OrderCreatedEvent",
  "msgPayload": "...",
  "timestamp": "2024-01-24T12:45:26.295Z"
}
```

#### Security

To ensure secure communication:

- The WebSocket connection must be established using the wss protocol
- An Api key, obtained from the [Login service](https://aurora-api-review.redoc.ly/tag/LoginService#operation/LoginWithApiCredentials)
- The Connection configuration id should also be included, as it will inform details over the connection like for example which events to subscribe to


Here is an example of how to open a websocket connection:


```bash
websocat wss://provablemarkets.com/api/1/websocket/events -H "Authorization: Bearer $API_KEY" -H "X-CONNECTION-CONFIG-ID: $CONFIG_ID"
```

# Aurora Workflows

## Company Service

### Overview

The Company Service allows you to retrieve a list of eligible companies.

#### List Companies Available

API Reference: [***CompanyService/ListCompanies***](https://aurora-api-review.redoc.ly/tag/CompanyService#operation/ListCompanies)

## Login Service

### Overview

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.

#### Login with API Credentials

API Reference: [***LoginService/LoginWithApiCredentials***](https://aurora-api-review.redoc.ly/tag/LoginService#operation/LoginWithApiCredentials)

## Configuration Service

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.

### Available connection types

`Aurora` currently supports two connection types

1. Webhooks
2. RPCHooks


## Order Entry and Matching

### Overview

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.

#### Order Side

The `side` field accepts the values of `BORROW` and `LOAN`.

#### Order Types

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.

#### Order Staging or "Held" Orders (OMS function)

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.

#### Order Intent or Quote type

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.

#### IOI "Firm-Ups"

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.

#### Agreements Filtering

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.

#### Order Pricing

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.

#### Order Attribution

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.

### Order Entry

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.

### Workflows

#### Day-Limit Order with Partial- and Full 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.

##### Submit New Order

API Reference: [***OmsService/CreateOrder***](https://aurora-api-review.redoc.ly/tag/OmsService#operation/CreateOrder)

##### Order Created

API Reference: [***OmsEventsService/OrderCreated***](https://aurora-api-review.redoc.ly/tag/OmsEventsService#operation/OrderCreated)

##### Order Partial Fill

API Reference: [***OmsEventsService/OrderExecuted***](https://aurora-api-review.redoc.ly/tag/OmsEventsService#operation/OrderExecuted)

##### Order Fulfill

API Reference: [***OmsEventsService/OrderExecuted***](https://aurora-api-review.redoc.ly/tag/OmsEventsService#operation/OrderExecuted)

#### Day-Limit Order with Partial Fill and Expiry EOD

##### Submit New Order And Partial Fill

API Reference: [***OmsEventsService/OrderExecuted***](https://aurora-api-review.redoc.ly/tag/OmsEventsService#operation/OrderExecuted)

##### Order Expiry

API Reference: [***OmsEventsService/OrderExpired***](https://aurora-api-review.redoc.ly/tag/OmsEventsService#operation/OrderExpired)

##### Order is Rejected

##### Order Modification and Cancellation

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.

#### Cancel Order

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***](https://aurora-api-review.redoc.ly/tag/OmsService#operation/CancelOrder)

#### Order Canceled

API Reference: [***OmsEventsService/OrderCanceled***](https://aurora-api-review.redoc.ly/tag/OmsEventsService#operation/OrderCanceled)

#### Amend Order

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***](https://aurora-api-review.redoc.ly/tag/OmsService#operation/ModifyOrder)

#### Order Modified

API Reference: [***OmsEventsService/OrderModified***](https://aurora-api-review.redoc.ly/tag/OmsEventsService#operation/OrderModified)

#### Order Closed

API Reference: [***OmsEventsService/OrderClosed***](https://aurora-api-review.redoc.ly/tag/OmsEventsService#operation/OrderClosed)

#### Query Orders

API Reference: [***OmsService/ListOrders***](https://aurora-api-review.redoc.ly/tag/OmsService#operation/ListOrders)

API Reference: [***OmsService/GetOrder***](https://aurora-api-review.redoc.ly/tag/OmsService#operation/GetOrder)

#### Order Staging

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.

#### Moving Staged Order to Public Order Book

##### Stage Order

API Reference: [***OmsService/CreateOrder***](https://aurora-api-review.redoc.ly/tag/OmsService#operation/CreateOrder)

##### Move Order to Public Order Book

API Reference: [***OmsService/ModifyOrder***](https://aurora-api-review.redoc.ly/tag/OmsService#operation/ModifyOrder)

## Agreements Service

### Overview

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.

#### List Agreements

API Reference: [***AgreementService/ListAgreements***](https://aurora-api-review.redoc.ly/tag/AgreementService#operation/ListAgreements)

#### Approve Agreement

API Reference: [***AgreementService/ApproveAgreement***](https://aurora-api-review.redoc.ly/tag/AgreementService#operation/ApproveAgreement)

#### Cancel Agreement

API Reference: [***AgreementService/CancelAgreement***](https://aurora-api-review.redoc.ly/tag/AgreementService#operation/CancelAgreement)

#### Create Agreement

API Reference: [***AgreementService/CreateAgreement***](https://aurora-api-review.redoc.ly/tag/AgreementService#operation/CreateAgreement)

#### Get Agreement

API Reference: [***AgreementService/GetAgreement***](https://aurora-api-review.redoc.ly/tag/AgreementService#operation/GetAgreement)

#### Modify Agreement

API Reference: [***AgreementService/ModifyAgreement***](https://aurora-api-review.redoc.ly/tag/AgreementService#operation/ModifyAgreement)

#### Reject Agreement

API Reference: [***AgreementService/RejectAgreement***](https://aurora-api-review.redoc.ly/tag/AgreementService#operation/RejectAgreement)

## Instrument Service

### Overview

The Instrument Service allows you to retrieve a list of eligible securities (instruments) for trading.

#### List Instruments

API Reference: [***InstrumentService/ListCompanies***](https://aurora-api-review.redoc.ly/tag/InstrumentService#operation/ListInstruments)

## Execution Service

### Overview

The Execution Service allows you to retrieve and acknowledge executions.

### Workflows

#### Query Executions

API Reference: [***ExecutionService/ListExecutions***](https://aurora-api-review.redoc.ly/tag/ExecutionService#operation/ListExecutions)

#### Acknowledge Executions

API Reference: [***ExecutionService/AckExecutions***](https://aurora-api-review.redoc.ly/tag/ExecutionService#operation/AckExecutions)

#### Execution Occurred

API Reference: [***ExecutionEventsService/Execution***](https://aurora-api-review.redoc.ly/tag/ExecutionEventsService#operation/Execution)

## Order Book Market Data

### Overview

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.

### Workflows

#### Market Data Request to receive a Snapshot of 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.

##### Query Order Book

API Reference: [***VenueService/QueryOrderBookDetailed***](https://aurora-api-review.redoc.ly/tag/VenueService#operation/QueryOrderBookDetailed)

##### Order Added to Order Book

API Reference: [***VenueEventsService/OrderAdded***](https://aurora-api-review.redoc.ly/tag/VenueEventsService#operation/OrderAdded)

##### Order Removed from Order Book

API Reference: [***VenueEventsService/OrderRemoved***](https://aurora-api-review.redoc.ly/tag/VenueEventsService#operation/OrderRemoved)

## Manual Contract Booking & Confirmation

### Overview

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.

### Workflows

#### Lender proposes a new Manual Contract

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

- To set a fixed rebate on a manual contract booking, enter the rate into `rate` and set `benchmark` to empty.
- To set the rate a manual contract relative to a benchmark, set `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.

##### Submit a Contract Request 

API Reference: [***ContractRequestService/SubmitContractRequest***](https://aurora-api-review.redoc.ly/tag/ContractRequestService#operation/SubmitContractRequest)

##### Contract Request Opened

API Reference: [***ContractRequestEventsService/ContractRequestOpened***](https://aurora-api-review.redoc.ly/tag/ContractRequestEventsService#operation/ContractRequestOpened)

#### Borrower Rejects proposed Manual Contract

##### Decline a Contract Request

API Reference: [***ContractRequestService/DeclineContractRequest***](https://aurora-api-review.redoc.ly/tag/ContractRequestService#operation/DeclineContractRequest)

##### Contract Request Declined

API Reference: [***ContractRequestEventsService/ContractRequestDeclined***](https://aurora-api-review.redoc.ly/tag/ContractRequestEventsService#operation/ContractRequestDeclined)

#### Borrower Accepts proposed Manual Contract

##### Accept a Contract Request

API Reference: [***ContractRequestService/AcceptContractRequest***](https://aurora-api-review.redoc.ly/tag/ContractRequestService#operation/AcceptContractRequest)

##### Contract Request Accepted

API Reference: [***ContractRequestEventsService/ContractRequestAccepted***](https://aurora-api-review.redoc.ly/tag/ContractRequestEventsService#operation/ContractRequestAccepted)

##### Contract Request Accepted (Both Parties)

API Reference: [***ContractEventsService/ContractCreated***](https://aurora-api-review.redoc.ly/tag/ContractEventsService#operation/ContractCreated)

#### Auto-Matching Manual Contracts

##### Submit a Contract Request (One Party)

API Reference: [***ContractRequestService/SubmitContractRequest***](https://aurora-api-review.redoc.ly/tag/ContractRequestService#operation/SubmitContractRequest)

##### Submit a Contract Request (Other Party)

API Reference: [***ContractRequestService/SubmitContractRequest***](https://aurora-api-review.redoc.ly/tag/ContractRequestService#operation/SubmitContractRequest)

##### Contract Request Accepted (Both parties)

API Reference: [***ContractRequestEventsService/ContractRequestAccepted***](https://aurora-api-review.redoc.ly/tag/ContractRequestEventsService#operation/ContractRequestAccepted)

##### Contract Matched (Both parties)

API Reference: [***ContractEventsService/ContractCreated***](https://aurora-api-review.redoc.ly/tag/ContractEventsService#operation/ContractCreated)

#### Canceling an Proposed Manual Contract

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.

##### Canceling an Proposed Manual Contracts

API Reference: [***ContractRequestService/CancelContractRequest***](https://aurora-api-review.redoc.ly/tag/ContractRequestService#operation/CancelContractRequest)

##### Canceled an Proposed Manual Contract (Borrower)

API Reference: [***ContractRequestEventsService/ContractRequestCancelled***](https://aurora-api-review.redoc.ly/tag/ContractRequestEventsService#operation/ContractRequestCanceled)

#### Querying Unmatched Manual Contracts

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.

##### Query Unmatched Manual Contracts 

API Reference: [***ContractRequestService/QueryContractRequests***](https://aurora-api-review.redoc.ly/tag/ContractRequestService#operation/QueryContractRequests)

#### Expiry of Unmatched Manual Contracts

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

##### Expired Unmatched Manual Contracts

API Reference: [***ContractRequestEventsService/ContractRequestCanceled***](https://aurora-api-review.redoc.ly/tag/ContractRequestEventsService#operation/ContractRequestCanceled)

## Contract Management and Lifecycle

### Overview

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.

#### Aurora’s Messaging to Settlement and Clearing Providers

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.

#### Contract Settlement

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_id`

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

#### Message Identifiers - `request_id`

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

### Workflows

#### Contract Status Reports

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:

1. As response to the `ListContracts` service method,
2. Following the matching of a contract in the Aurora order book,
3. Following conformation (acceptance) of manual contracts entered into Aurora, and
4. Following a change to the current status of a contract.


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.

#### Query Contracts

Provides a list of contracts based on filter criteria.

API Reference: [***ContractsService/ListContracts***](https://aurora-api-review.redoc.ly/tag/ContractService#operation/ListContracts)

#### Query a Contract

Provides detailed info for a contract.

API Reference: [***ContractsService/GetContract***](https://aurora-api-review.redoc.ly/tag/ContractService#operation/GetContract)

#### Query History for a Contract

Provides the events that occurred for a contract.

API Reference: [***ContractsService/ListContractHistory***](https://aurora-api-review.redoc.ly/tag/ContractService#operation/ListContractHistory)

#### Matching of Contract in OMS

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***](https://aurora-api-review.redoc.ly/tag/ContractEventsService#operation/ContractCreated)

#### Manual Acceptance of a Contract

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***](https://aurora-api-review.redoc.ly/tag/ContractEventsService#operation/ContractCreated)

Example: gRPC websocket event with json payload

#### Contract Pending

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***](https://aurora-api-review.redoc.ly/tag/ContractEventsService#operation/ContractPending)

#### Contract Made

When a contract settles via the depository. The status is marked as “OPEN”.

API Reference: [***ContractEventsService/ContractMade***](https://aurora-api-review.redoc.ly/tag/ContractEventsService#operation/ContractMade)

#### Contract Dropped

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***](https://aurora-api-review.redoc.ly/tag/ContractEventsService#operation/ContractDropped)

#### Contract Rejected

API Reference: [***ContractEventsService/ContractRejected***](https://aurora-api-review.redoc.ly/tag/ContractEventsService#operation/ContractRejected)

#### Canceling a Pending Contract

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.

##### Cancel Pending Contract

API Reference: [***ContractsService/CancelContract***](https://aurora-api-review.redoc.ly/tag/ContractService#operation/CancelContract)

##### Cancel Pending Contract Accepted

API Reference: [***ContractEventsService/CancelContractAccepted***](https://aurora-api-review.redoc.ly/tag/ContractEventsService#operation/CancelContractAccepted)

##### Cancel Pending Contract Rejected

API Reference: [***ContractEventsService/CancelContractRejected***](https://aurora-api-review.redoc.ly/tag/ContractEventsService#operation/CancelContractRejected)

#### Daily Contract Rolls

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***](https://aurora-api-review.redoc.ly/tag/ContractEventsService#operation/ContractRolled)

#### Returning a Contract (Borrower)

##### Contract Return Instruction (Borrower)

API Reference: [***ContractService/ReturnContract***](https://aurora-api-review.redoc.ly/tag/ContractService#operation/ReturnContract)

##### Contract Return Executed

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***](https://aurora-api-review.redoc.ly/tag/ContractEventsService#operation/ContractReturnExecuted)

##### Contract Return Pending

API Reference: [***ContractEventsService/ContractReturnPending***](https://aurora-api-review.redoc.ly/tag/ContractEventsService#operation/ContractReturnPending)

##### Late Contract Return Pending Approval by Lender

API Reference: [***ContractEventsService/ContractReturnPendingLenderApproval***](https://aurora-api-review.redoc.ly/tag/ContractEventsService#operation/ContractReturnPendingLenderApproval)

##### Accept a Pending Contract Return (Lender)

API Reference: [***ContractService/AcceptAwaitingContractReturn***](https://aurora-api-review.redoc.ly/tag/ContractService#operation/AcceptAwaitingContractReturn)

##### Reject a Pending Contract Return (Lender)

API Reference: [***ContractService/RejectAwaitingContractReturn***](https://aurora-api-review.redoc.ly/tag/ContractService#operation/RejectAwaitingContractReturn)

##### Cancel a Pending Contract Return (Borrower)

API Reference: [***ContractService/CancelAwaitingContractReturn***](https://aurora-api-review.redoc.ly/tag/ContractService#operation/CancelAwaitingContractReturn)

##### Contract Return Rejected (Borrower)

API Reference: [***ContractEventsService/ContractReturnRejected***](https://aurora-api-review.redoc.ly/tag/ContractEventsService#operation/ContractReturnRejected)

##### Contract Return Failed

API Reference: [***ContractEventsService/ContractReturnFailed***](https://aurora-api-review.redoc.ly/tag/ContractEventsService#operation/ContractReturnFailed)

##### Canceling a Contract Return (Borrower)

API Reference: [***ContractService/CancelSinglePendingReturn***](https://aurora-api-review.redoc.ly/tag/ContractService#operation/CancelSinglePendingReturn)

##### Canceling All Returns on a Contract (Borrower)

API Reference: [***ContractService/CancelAllPendingReturns***](https://aurora-api-review.redoc.ly/tag/ContractService#operation/CancelAllPendingReturns)

##### Contract Return Cancel Accepted (Borrower)

API Reference: [***ContractEventsService/ContractReturnCancelAccepted***](https://aurora-api-review.redoc.ly/tag/ContractEventsService#operation/ContractReturnCancelAccepted)

##### Contract Return Cancel Rejected (Borrower)

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***](https://aurora-api-review.redoc.ly/tag/ContractEventsService#operation/ContractReturnCancelRejected)

##### Dropping Pending Contract Returns

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***](https://aurora-api-review.redoc.ly/tag/ContractEventsService#operation/ContractReturnDropped)

#### Late contract returns

This will occur only if the client has set a Return Cutoff time in Aurora.

##### Late Contract Return Approved (Borrower)

If the lender accepted the late contract return, the borrower is notified by emitting the `ContractReturnAcceptedByLender` event

API Reference: [***ContractEventsService/ContractReturnAcceptedByLender***](https://aurora-api-review.redoc.ly/tag/ContractEventsService#operation/ContractReturnAcceptedByLender)

##### Late Contract Return Rejected (Borrower)

If the lender rejected the late contract return, the borrower is notified by emitting the `ContractReturnRejectedByLender` event.

API Reference: [***ContractEventsService/ContractReturnRejectedByLender***](https://aurora-api-review.redoc.ly/tag/ContractEventsService#operation/ContractReturnRejectedByLender)

##### Cancel Late Contract Return (Borrower)

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***](https://aurora-api-review.redoc.ly/tag/ContractService#operation/CancelSinglePendingReturn)

##### Late Contract Return Canceled (Lender)

If the borrower cancels a late contract return the lender will be notified by emitting the `ContractReturnCanceledByBorrower` event.

API Reference: [***ContractEventsService/ContractReturnCanceledByBorrower***](https://aurora-api-review.redoc.ly/tag/ContractEventsService#operation/ContractReturnCanceledByBorrower)

#### Lender Contract Recall

##### Lender Contract Recall Initiation

API Reference: [***ContractService/RecallContract***](https://aurora-api-review.redoc.ly/tag/ContractService#operation/RecallContract)

##### Lender Contract Recall Rejected

API Reference: [***ContractEventsService/ContractRecallRejected***](https://aurora-api-review.redoc.ly/tag/ContractEventsService#operation/ContractRecallRejected)

##### Contract Recall Opened

In case of acceptance by the DTC both parties will be notified by Aurora by sending
the `ContractRecallOpened` service event.

API Reference: [***ContractEventsService/ContractRecallOpened***](https://aurora-api-review.redoc.ly/tag/ContractEventsService#operation/ContractRecallOpened)

#### Borrower returns stock in response to a Contract Recall

##### Borrower returns stock

API Reference: [***ContractService/ReturnContract***](https://aurora-api-review.redoc.ly/tag/ContractService#operation/ReturnContract)

##### Contract Recall Executed (Borrower)

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***](https://aurora-api-review.redoc.ly/tag/ContractEventsService#operation/ContractRecallExecuted)

#### Amending a Contract Recall (Lender Only)

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.

##### Increase quantity a Contract Recall (Lender Only)

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.

[Add Contract Recall](#lender-contract-recall-initiation)

##### Reduce quantity a Contract Recall (Lender Only)

Should the lender wish to reduce the quantity recalled, however, then they could either:

1. Cancel the recall (see Canceling a Contract Recall), and submit a new `RecallContractRequest` with the lower quantity, or
2. Amend the original contract recall message.


[Cancel Contract Recall](#cancel-contract-recall)

Notes:
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`.

#### Canceling a Contract Recall (Lender Only)

##### Cancel Contract Recall

API Reference: [***ContractService/CancelRecallContract***](https://aurora-api-review.redoc.ly/tag/ContractService#operation/CancelRecallContract)

##### Cancel All Recalls on a Contract

API Reference: [***ContractService/CancelAllRecalls***](https://aurora-api-review.redoc.ly/tag/ContractService#operation/CancelAllRecalls)

##### Contract Recall Canceled

API Reference: [***ContractEventsService/ContractRecallCanceled***](https://aurora-api-review.redoc.ly/tag/ContractEventsService#operation/ContractRecallCanceled)

##### Contract Recall Cancel Rejected

API Reference: [***ContractEventsService/ContractRecallCancelRejected***](https://aurora-api-review.redoc.ly/tag/ContractEventsService#operation/ContractRecallCancelRejected)

##### Contract Recall Updated

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***](https://aurora-api-review.redoc.ly/tag/ContractEventsService#operation/ContractRecallUpdated)

##### Querying Outstanding Contract Recalls

API Reference: [***ContractService/ListRecalls***](https://aurora-api-review.redoc.ly/tag/ContractService#operation/ListRecalls)

#### Unsuccessful entry of a Buy-in by the Lender

##### Contract Buy-in Instruction

API Reference: [***ContractService/BuyInContract***](https://aurora-api-review.redoc.ly/tag/ContractService#operation/BuyInContract)

##### Contract Buy-in Rejected

API Reference: [***ContractEventsService/ContractBuyInRejected***](https://aurora-api-review.redoc.ly/tag/ContractEventsService#operation/ContractBuyInRejected)

#### Successful entry of a (full) Buy-in by the Lender

##### Contract Buy-in Instruction

API Reference: [***ContractService/BuyInContract***](https://aurora-api-review.redoc.ly/tag/ContractService#operation/BuyInContract)

##### Contract Buy-in Accepted

API Reference: [***ContractEventsService/ContractBuyInAccepted***](https://aurora-api-review.redoc.ly/tag/ContractEventsService#operation/ContractBuyInAccepted)

##### Contract Buy-in Executed

API Reference: [***ContractEventsService/ContractBuyInExecuted***](https://aurora-api-review.redoc.ly/tag/ContractEventsService#operation/ContractBuyInExecuted)

#### Proposing a Contract Rebate Modification

##### Contract Rebate Rate Change Proposal

API Reference: [***ContractService/CreateRateModification***](https://aurora-api-review.redoc.ly/tag/ContractService#operation/CreateRateModification)

##### Contract Rebate Proposal Opened

API Reference: [***ContractEventsService/ContractRateModificationOpened***](https://aurora-api-review.redoc.ly/tag/ContractEventsService#operation/ContractRateModificationOpened)

#### Accepting a Contract Modification

API Reference: [***ContractService/AcceptRateModification***](https://aurora-api-review.redoc.ly/tag/ContractService#operation/AcceptRateModification)

#### Rejecting a Contract Modification

API Reference: [***ContractService/RejectRateModification***](https://aurora-api-review.redoc.ly/tag/ContractService#operation/RejectRateModification)

##### Contract Rebate Rate Modification Accepted

Whenever AURORA detects a change in the rebate of a Contract it will trigger
the `ContractRateModificationAccepted` service event.

API Reference: [***ContractEventsService/ContractRateModificationAccepted***](https://aurora-api-review.redoc.ly/tag/ContractEventsService#operation/ContractRateModificationAccepted)

##### Contract Rebate Rate Modification Executed

When both sides have agreed to the Rebate Rate (or Fee) change, Aurora will trigger
the `ContractRateModificationExecuted` service event.

API Reference: [***ContractEventsService/ContractRateModificationExecuted***](https://aurora-api-review.redoc.ly/tag/ContractEventsService#operation/ContractRateModificationExecuted)

##### Contract Rebate Rate Proposal Rejected

API Reference: [***ContractEventsService/ContractRateModificationRejected***](https://aurora-api-review.redoc.ly/tag/ContractEventsService#operation/ContractRateModificationRejected)

#### Auto Accepting Contract Rebate Rate Modifications

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.

#### Expiration of a Contract Modification

A contract modification proposed by a lender expires at the end of the day

##### Contract Rebate Rate Proposal Expired

API Reference: [***ContractEventsService/ContractRateModificationExpired***](https://aurora-api-review.redoc.ly/tag/ContractEventsService#operation/ContractRateModificationExpired)

#### Successful Cancellation of Contract Rebate Modification

##### Contract Rebate Proposal Canceled

API Reference: [***ContractEventsService/ContractRateModificationCanceled***](https://aurora-api-review.redoc.ly/tag/ContractEventsService#operation/ContractRateModificationCanceled)

#### Cancellation of Contract Rebate Modification

##### Cancel Contract Rate Modification

API Reference: [***ContractService/CancelRateModification***](https://aurora-api-review.redoc.ly/tag/ContractService#operation/CancelRateModification)

#### Automatic Cancellation of Contract Rebate Modification

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.

##### Contract Rebate Proposal AutoCanceled

API Reference: [***ContractEventsService/ContractRateModificationAutoCanceled***](https://aurora-api-review.redoc.ly/tag/ContractEventsService#operation/ContractRateModificationAutoCanceled)

#### Querying Outstanding Contract Rebate Modification Requests

##### Query Contract Rebate Modifications

API Reference: [***ContractService/ListRateModifications***](https://aurora-api-review.redoc.ly/tag/ContractService#operation/ListRateModifications)

# API Reference

The Aurora Services are split in two parts, *Methods* and *Events*.

### Methods

You can use *Methods* to submit to and query data from Aurora.

### Events

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](#unsolicited-messages-distribution)

### API Categories

Aurora offers services in the following categories:

| Category | Description | Methods | Events |
|  --- | --- | --- | --- |
| Login | Get authenticated and retrieve an *access token* | [Login API](/tag/LoginService) | - |
| Contracts | Contract Lifecycle events like Recalls and Buyins | [Contract API](/tag/ContractService) | [Contract Events](/tag/ContractEventsService) |
| Contract Requests | Propose and Respond to Contract Requests from your counterparties | [Contract Request API](/tag/ContractRequestService) | [Contract Request Events](/tag/ContractRequestEventsService) |
| Orders | Lend and Borrow Orders in the OMS system | [OMS API](/tag/OmsService) | [OMS Events](/tag/OmsEventsService) |
| Agreements | Order matching agreements in the OMS system | [Agreement API](/tag/AgreementService) |  |
| Venue | Query the Marketplace | [Venue API](/tag/VenueService) | [Venue Events](/tag/VenueEventsService) |
| Companies | Query for Counterparties | [Company API](/tag/CompanyService) |  |
| Instruments | Query eligible Instruments | [Instrument API](/tag/InstrumentService) |  |


### Authentication

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](/tag/LoginService) first.