Spec for Indicative margin API

[campbellssource]

Users have asked for something that tells them the margin requirement for an order before they place it. Typically an exchange will give you this information in a deal ticket, with or without a note that explains that this is a simulation with some caveats. Leverage and other values have been asked for but we've agreed that margin is the starting point.

There has been discussion of calculating this on the client using an API that expose the risk parameters but this ticket is to explore a dedicated API for providing a margin values by simulating a trade on the network in the current state.

Starting hypothesis: the API takes the same parameters as an order and does all the same things that placing the order would do but wouldn't actually place the order and it returns all the values that a order would e.g. margin balance, margin levels (initial margin and maintenance are the priority).

There are two options for the types of values returned. There is probably value in both.

• the new margin values for a given user
• the margin values for a hypothetical party who does not have any positions

@campbellssource prefers the first: The values returned should be the new values for the given trader. so If the trader is +10, and the simulated trade is -5 then the returned values should be a lower margin balance.

But this is for someone in the product team to decide, this ticket just contains my view.

[campbellssource]

Additional request 1. For each level could we also get an indication of where the market will have to be for me to have hit that level (with a given set of assumptions/disclaimers)

Additional request 2. For each level could we get how much collateral I will have had to have before I get to that level.

For example: If I have a 0 position, and place an order to Buy 10 at 1000 assuming a 16x leverage.

Level	Threshold (in terms of balance required)	Threshold (in terms of Market level)	Total collateral used
Release	192	1200	140
Initial	160	Current (1000)	160
Search	80	800	240
Maintenance	60	600	260

[cdm]

If the underlying Vega core data is constantly changing with every new trade or other event, will there need to be a sampling rate or similar for this kind of data and if so does that impact spec we write?

[campbellssource]

If the underlying Vega core data is constantly changing with every new trade or other event, will there need to be a sampling rate or similar for this kind of data and if so does that impact spec we write?

My intention is to help a user build a mental model of what these values mean and how they can use them. For this I think the values can be indicative assuming the order book doesn't change. The actual values are not that useful, because it will change. So in terms of a sampling rate I'd say it can be low/slow/corse (not sure the right term).

Here is an example of how it think the values will be used:

https://github.com/vegaprotocol/console/issues/4033 is the UI ticket for the job of implementing, I'll keep it upto date with latest thinking.

[cdm]

In a volatile/liquid market would that cause potential issues - we might need to signal with a warning stating that this projected balance figure could be dangerous to trust?

I'm not an experienced trader, so maybe the pro's learn to take such a projected figure with a pinch of salt.

[cdm]

Nice UI btw :)

[davidsiska-vega]

See also https://github.com/vegaprotocol/vega/issues/1797

[witgaw]

This ticket should be enough to provide the API for being able to display the margin requirements on a deal ticke: https://github.com/orgs/vegaprotocol/projects/22. An associated console ticket is required to plug it in from that end.

Also added myself a ticket in quant to look into efficient ways of approximating margin levels with prices: vegaprotocol/quant#7.

For Additional request 2 - isn't this just a difference between current margin account balance and the various margin levels? If so I think this is pretty much covered by the margin chart already in UI or can be covered with a simple difference if we want to display it numerically.
I'm not sure to what extent it would be useful just now given parties have no explicit control of their margin levels (protocol does it for them by appropriately transferring between margin and general accounts.

[campbellssource]

@witgaw

For Additional request 2 - isn't this just a difference between current margin account balance and the various margin levels? If so I think this is pretty much covered by the margin chart already in UI or can be covered with a simple difference if we want to display it numerically.

I think the data we need is the same as we currently get for an open position to show the chart. I'm just requesting it for the indicative margin API. (although it is probably a moment for implementation not spec)

I'm not sure to what extent it would be useful just now given parties have no explicit control of their margin levels (protocol does it for them by appropriately transferring between margin and general accounts.

I agree it may not be very useful day to day trading but I think it may be useful as a way of users building a mental model for how margining works on Vega.