Margin Service API - Use Cases

Create Portfolio

• Client submits required attributes for a portfolio

• Server validates request, including checks for uniqueness (name is unique)

• If the request is valid, an internal identifier and status are returned

• If the request is invalid, a status and error message/error code are returned

• Does not include transactions (trades)

Alter Transactions

• Allows transactions to be uploaded in bulk (multiple transactions in a single request)

• Supports a "mixed mode" allowing transactions to be created, updated, and deleted

• A valid portfolio identifier must be specified

• All transactions must be in a single portfolio

• Transactions being created must be specified with all the required attributes.

• Transactions being updated must have the attributes being updated and the system internal identifier

• Transactions being deleted must have the internal identifier of the transaction

• The sever will return a request identifier

Calculate Margin

• Client submits margin type (full, incremental)

• Client must submit portfolio identifier

• Client may submit additional (transient) transactions by value

• Client may submit transactions to exclude by identifier from the portfolio

• Client may submit additional portfolio by reference

• Client may submit transaction IDs by reference (allowed for their user)

• The server will queue up the request for execution

• If the portfolio does not exist, referenced transactions do not exist, or there are other errors an error message/code will be returned

• If the request is valid, then after the request is submitted to the risk engine for processing a request identifier and status are returned.

Get Calculate Margin Result

• Client submits margin request identifier

• Server returns the identifier, status, error (if applicable), and result (if available)

Alter Transactions

• Allows transactions to be uploaded in bulk (multiple transactions in a single request)

• Supports a "mixed mode" allowing transactions to be created, updated, and deleted

• A valid portfolio identifier must be specified

• All transactions must be in a single portfolio

• Transactions being created must be specified with all the required attributes

• Transactions being updated must have the attributes being updated and the system internal identifier

• Transactions being deleted must have the internal identifier of the transaction

• The sever will return a request identifier

Calculate Margin

• Client submits margin type (full, incremental)

• Client must submit portfolio identifier

• Client may submit additional (transient) transactions by value

• Client may submit transactions to exclude by identifier from the portfolio

• Client may submit additional portfolio by reference

• Client may submit transaction IDs by reference (allowed for their user)

• The server will queue up the request for execution

• If the portfolio does not exist, referenced transactions do not exist, or there are other errors an error message/code will be returned

• If the request is valid, then after the request is submitted to the risk engine for processing a request identifier and status are returned

Get Alter Transactions Result

• The client submits an identifier from the alter transactions request

• The server returns the overall status of the request, and results for all transactions if all have completed processing.

• The server will return an identifier (if available), status, and error message/error code (if applicable)

Get Calculate Margin Result

• Client submits margin request identifier

• Server returns the identifier, status, error (if applicable), and result (if available)

List Margins

• Client submits query criteria (portfolio ID, time range, etc.)

• Server returns identifier, status, error (if applicable), and result (if available) for all matching requests

• This is similar to the functionality in the MHQ Grid in the UI

List Portfolios

• Client can optionally submit search parameters (TBD)

• The server returns all portfolios matching the criteria

• Does not include transactions or other data

• Since this is querying local data, it is assumed that this can be returned synchronously

Update Portfolio

• Client submits an internal portfolio identifier and updated attributes

• If no portfolio is found with the identifier an error is returned

• If the user is not authorized to modify the portfolio an error is returned

• If the request is valid and successful, the internal identifier and status are returned

• Transactions must be submitted separately

Delete Portfolio

• Client submits an internal portfolio identifier

• If no portfolio is found with the identifier, an error is returned

• If the user is not authorized to delete the portfolio, an error is returned

• The server will delete the portfolio and all associated data (transactions, margins, etc.).  This is known as a "cascading delete"

List Transaction

• Client can optionally submit search criteria

• The server returns all portfolios matching the criteria

• Does not include transactions or other data

• The results of this request are returned synchronously

Get Transaction

• Client submits an internal transaction identifier

• If no transaction is found with the identifier, an error is returned

• If the user is not authorized to get the transaction, an error is returned

• If the transaction is found it is returned

Calculate Optimize

• Client must submit portfolio identifier

• The server will queue up the request for execution

• If the portfolio does not exist, referenced transactions do not exist, or there are other errors an error message/code will be returned

• If the request is valid, then after the request is submitted to the risk engine for processing a request identifier and status are returned.

Get Optimize Margin Result

• Client submits Optimize request identifier

• Server returns the identifier, status, error (if applicable), and result (if available)