Skip to main content

Streaming Positions, Groups and Aggregates

Stream Position Groups extends the capabilities offered by the Stream Positions endpoint. Unlike Stream Positions, which reports positions in a single list with each symbol represented independently, Stream Position Groups can organize related positions into multi-leg strategies, such as vertical spreads, butterflies, iron condors, and covered calls, or continue reporting them individually.

Who it's for​

Position grouping is primarily intended for accounts trading options. Positions can be grouped into strategies automatically, by orderbased or marginbased grouping, or by you, in custom mode. Futures accounts and accounts holding only equities can also use the endpoint to stream positions and retrieve aggregates by account or product root.

Stream Position Groups is particularly well suited for applications that visually display positions, such as portfolio dashboards that present positions and strategies in an organized view. In custom mode, you can use position grouping to perform operations such as creating a user interface that allows a user to move positions, including individual legs of a spread, from one group to another. For example, a long call and a short call could be grouped together to form a call vertical.

Terms used on this page​

TermMeaning
PositionOne instrument held in one account, such as 2 contracts of an AAPL call or 100 AAPL shares.
GroupTwo to four legs treated as one options strategy, such as a call vertical, iron condor or covered call. A group has its own name, side, quantity and totals.
LegA position, or part of one, inside a group. A group holds only the quantity of each leg that belongs to that strategy.
Ungrouped positionA position, or the part of one, that isn't in any group.
Product rootThe underlying symbol that positions share, such as NVDA for NVDA shares and NVDA options. Groups and aggregates are built per product root.
AggregateRolled-up totals for an account, or for one product root within an account. See Aggregates.
Automatic groupingGroups formed by TradeStation: orderbased (by the multi-leg order that filled the legs) or marginbased (by how the margin system pairs them).
Custom modeA stream opened with grouptype=custom. Groups start from your grouping modes, and you can create, update, split and merge them yourself.
Initial grouping modeIn custom mode, how existing positions are grouped when an account's groups are reset. Set with Update Position Grouping Mode.
Ongoing grouping modeIn custom mode, how new fills are grouped while a stream is running. Set with Update Position Grouping Mode.
Identical groupsGroups with exactly the same option symbols, in the same ratio and sign. In orderbased grouping, and in custom mode when the Ongoing grouping mode is orderbased, identical groups are combined into one group with summed quantities. This is called auto-merge.
Auto-mergeCombining identical groups automatically. It is on by default. Turn it off with automerge=false on an orderbased stream, or with the AutoMerge setting of Update Position Grouping Mode in custom mode.
Margin match IDThe ID the margin system gives a pairing of legs, such as SPY-2. It is the group ID in marginbased grouping.
DVP accountA delivery versus payment account.

Reading group names. GroupName shows the expiration as month and day, then the strikes, then the strategy, for example Feb09 190/195 Call Vertical (expiring 9 February, strikes 190 and 195). When the expiration is more than a year away, the year is added, for example Apr17'27. The same format is used by Get Spread Name.

Numbers and signs. Stream values, including quantities and prices, are sent as strings, such as "Quantity": "120". Quantities are negative for short positions and short groups. In grouping requests such as Create Position Group, Quantity is a number, also negative for short, such as "Quantity": -6.

What you can do with it​

A group has its own GroupName, LongShort (Long or Short), Quantity, and totals: MarketValue, TotalCost, UnrealizedProfitLoss, TodaysProfitLoss, Bid and Ask.

Choose how legs are grouped with grouptype. Each value is described in Grouping types.

grouptypeGrouping
ungrouped (default)No groups. Positions are reported individually in a Positions array, so the endpoint, configured in this manner, would behave in a manner similar to Stream Positions.
orderbasedLegs filled by the same multi-leg order form one group. The group ID is the order ID. Identical groups are combined unless you request the stream with automerge=false.
marginbasedLegs are grouped the way the margin system pairs them. Includes MarginEstimate (estimated margin requirement) and BuyingPowerImpactEstimate (estimated buying power reduction).
customYou create, update, split and merge groups yourself.

Choose totals with aggregates. With aggregates=accountandproductroot, each account gets its own aggregate, and each product root in it (for example NVDA) gets its own totals, covering its shares, groups and single options. With aggregates=account, you get totals for each account.

In custom mode, you can change how positions are grouped. If you legged into a spread with separate orders, orderbased grouping won't group those legs. You can create a group from them, update a group to change its legs and quantities, split a group to manage its parts separately, or merge groups into one. Custom groups can include shares, so you can group shares and a short call as a covered call. These calls don't need a custom-mode stream to be open.

To name a strategy before you trade it, use Get Spread Name. It takes two to four legs and returns the group's name, side and quantity.

Limits. A group is one strategy on one product root. Every group has 2 to 4 legs, including groups created by a split. A group you create or merge must use positions from one account and one product root, and can't include futures. Grouping modes don't apply to futures accounts, and the grouping endpoints return an error for a futures account. For a wider view, use aggregates.

Example messages​

These examples are based on the API reference. They show what each kind of message looks like. They come from different stream types, so the IDs don't carry over from one to the next. Values are for illustration only, and some fields are left out.

Request. Send requests to https://api.tradestation.com, with a bearer token that has the ReadAccount scope (see Authentication and Scopes). The same host and scope apply to all the position grouping endpoints. Pass up to 25 Cash, Margin, Futures or DVP account IDs, comma-separated. This one opens a stream for one account with orderbased grouping:

GET https://api.tradestation.com/v3/brokerage/stream/accounts/123456789/positiongroups?grouptype=orderbased

Snapshot (orderbased). The stream starts with a snapshot of everything you hold, one per account. Here, an NVDA call vertical opened in one order:

{
"Groups": [
{
"GroupID": "289397100",
"GroupName": "Feb09 190/195 Call Vertical",
"AccountID": "123456789",
"LongShort": "Long",
"Quantity": "120",
"Underlying": "NVDA",
"MarketValue": "26880",
"TotalCost": "27360",
"UnrealizedProfitLoss": "-480",
"Bid": "2.14",
"Ask": "2.28",
"Positions": [
{
"PositionID": "66258592",
"Symbol": "NVDA 260209C190",
"LongShort": "Long",
"Quantity": "120",
"MarketValue": "61200",
"TotalCost": "61200",
"MultiGroupAvgPrice": false
},
{
"PositionID": "66258593",
"Symbol": "NVDA 260209C195",
"LongShort": "Short",
"Quantity": "-120",
"MarketValue": "-34320",
"TotalCost": "-33840",
"MultiGroupAvgPrice": false
}
]
}
]
}

The group ID is the order ID. A quantity of 120 means 120 verticals, made from legs of +120 and −120.

End of snapshot. Sent when every account's snapshot has been sent:

{ "StreamStatus": "EndSnapshot" }

Group update. After the snapshot, you only receive changes. An update carries the IDs and the fields that changed. A field that isn't included hasn't changed; it isn't zero or empty.

{
"Groups": [
{
"GroupID": "grp-a",
"MarketValue": "480.00",
"Bid": "0.42",
"Ask": "0.52",
"Positions": [
{ "PositionID": "pos-2", "Bid": "1.27", "Ask": "1.43" }
]
}
]
}

Heartbeat. If nothing changes for 5 seconds, a heartbeat arrives:

{ "Heartbeat": 5, "Timestamp": "2025-01-06T10:32:00Z" }

Group removed. A removed group is sent once with Deleted: true. Each of its legs comes with a Status that says what happened to it (see When a group goes away):

{
"Groups": [
{
"GroupID": "grp-a",
"Deleted": true,
"Positions": [
{ "PositionID": "pos-1", "Status": "Closed" },
{ "PositionID": "pos-2", "Status": "Closed" }
]
}
]
}

Account errors. Account errors are sent as messages inside the stream, so the stream keeps running for the other accounts.

If some of the requested accounts are invalid, the stream opens and sends one message for each invalid account, then streams the valid ones. The message is Invalid account ID(s). or, for an inactive or unsupported account, Request not supported for account type. If none of the accounts are valid, the request fails with status 403 and the same messages.

{ "Error": "Forbidden", "Message": "Invalid account ID(s).", "AccountID": "123456789" }

If an account fails before every account's snapshot has been sent, the stream sends this for that account, drops it, and continues with the others:

{
"Error": "Internal Server Error",
"Message": "Stream ended unexpectedly for account 123456789",
"AccountID": "123456789"
}

If an error occurs after the snapshot is complete, the stream sends the error and closes. Reconnect to start again with a fresh snapshot.

Create a group (custom mode). Send the account and two to four positions with the quantity of each to put in the group:

{
"AccountID": "987654321",
"Positions": [
{ "PositionID": "000001", "Quantity": -6 },
{ "PositionID": "000002", "Quantity": 6 }
]
}

The response's GroupID is the ID the group will have in the stream:

{ "AccountID": "987654321", "GroupID": "67c223dfb791f17d038ae5c2" }

What to do with the response​

  • Store positions, groups and aggregates keyed by their IDs (AccountID, PositionID, GroupID, AggregateID). Store a leg by group ID and position ID, because the same position can be in more than one place.
  • After EndSnapshot, apply each update by changing only the fields it contains. Don't clear a field because it's missing.
  • Remove groups and aggregates sent with Deleted: true.
  • Remove positions sent with status Closed. Positions don't carry Deleted.
  • When MultiGroupAvgPrice is true, the position is held in more than one place. Its average price and P/L are averaged across lots. Add up its quantities across places to get the account total.

Worked examples of each case are in Reference → Examples.

Reconnecting​

If you miss 3 heartbeats in a row without receiving any update, reconnect. A new stream always starts with a fresh snapshot, so replace what you've stored with it.

How your trading changes what you see​

With orderbased grouping:

  • Opening a spread in one order creates a group.
  • Buying the same spread again combines it into the group you already hold. The group keeps its ID. With automerge=false, the new order gets its own group instead.
  • Closing part of a combined group takes quantity from the oldest order first (FIFO). The group may be deleted and replaced by a new one with a different ID, which is expected.
  • Selling part of a leg, or a whole leg, updates the group as long as two legs remain. A partial close can change a group's shape, not only its quantity, so always read its current legs.
  • When only one leg is left, the group is deleted and the remaining leg is sent as an ungrouped position with status Ungrouped.

In custom mode, changing the Initial grouping mode resets the account's groups, including ones you created. Any running custom-mode stream receives a GoAway status, then the connection closes, so start a new one. The new stream regroups existing positions using the new mode. The Ongoing grouping mode controls how new fills are grouped. When it's set to orderbased, identical groups combine, including groups you created yourself. To stop this, set AutoMerge to false with Update Position Grouping Mode. The change applies to groups formed after it, without resetting groups or closing the stream.

When a group goes away​

The Status on each of the group's legs depends on why the group was removed:

What happenedStatus of the group's legs
The group went down to one legClosed for each removed leg. The last one is Ungrouped.
The whole group was closed at onceClosed
The group was dissolved (custom mode or marginbased)Ungrouped
The group was dissolved and a new one appeared in the same message (marginbased)Regrouped
The group was combined into another (orderbased)Regrouped

A position can also arrive with status Grouped, when quantity moves from the ungrouped list into one or more groups. All four statuses are listed in Positions in more than one place.


Reference​

Endpoints​

APIWhat it does
Stream Position GroupsStreams real-time positions for up to 25 Cash, Margin, Futures or DVP accounts at once. Positions can be organized into groups and rolled up into account and product root totals.
Get Spread NameTakes two to four legs and returns the group's name, side and quantity.
Get Position Grouping ModeReturns your current Initial and Ongoing grouping modes and AutoMerge setting for custom mode.
Update Position Grouping ModeSets the Initial and/or Ongoing grouping mode and/or the AutoMerge setting for custom mode.
Create Position GroupCreates a group from two to four positions and quantities in one account, in custom mode.
Update Position GroupUpdates the legs and quantities in an existing group, in custom mode.
Delete Position GroupRemoves a group and ungroups all of its legs and quantities, in custom mode.
Split Position GroupDivides a group into two or more groups, in custom mode. Any legs or quantity you don't allocate go into one additional new group.
Merge Position GroupsCombines groups into a single group with summed quantities, in custom mode.

1. Stream lifecycle​

  1. Initial snapshots. When the stream starts, all existing open positions are returned with complete field data. One snapshot message is returned for each account.
  2. End of snapshot. After every account completes its snapshot, a message with StreamStatus: "EndSnapshot" is sent. All later messages are real-time updates.
  3. Incremental updates. Updates contain changes only: the IDs plus any field that changed since the last update. A field that is absent from an update is unchanged. It is not null and not zero.
  4. Removals and status. A group or aggregate that is removed is sent once with Deleted: true and never again. For positions, the Status field reports what happened (see Positions in more than one place).
  5. Heartbeats. Sent when the stream has been idle for 5 seconds, to show that it is still alive.

2. What is a group?​

A group is two to four legs treated as one options strategy, such as a vertical, butterfly, iron condor, calendar, or covered call (shares plus a short call). Terms are defined in Terms used on this page.

For example, a position could be 2 contracts of AAPL 261218C200 (the AAPL call expiring 18 December 2026 with a strike of 200). If it is in a call vertical, that group holds it as a leg, with only the quantity that belongs to the vertical.

What a group gives you. Instead of reading each leg separately, you get values for the whole strategy:

  • Quantity: how many of the strategy you hold: the greatest common divisor of the leg quantities. Legs of +2 / −2 calls are 2 verticals.
  • GroupName: for example Dec20 100/105 Call Vertical. If the legs no longer match any named strategy, the strategy part of the name becomes Custom.
  • LongShort: Long or Short, set by a formula for each strategy. For a Custom group, it is set by the group's market value.
  • Totals: MarketValue, TotalCost, UnrealizedProfitLoss, TodaysProfitLoss, AveragePrice, Bid and Ask.

Rules

  • A group has 2 to 4 legs. A single position never forms a group.
  • The same position can be in several places at once, for example 3 contracts in a vertical and 2 in a butterfly. Each place holds only its own quantity, and MultiGroupAvgPrice is true on each.
  • Groups change over time. They can be combined when identical, be split after a partial close, or be deleted when only one leg remains, in which case the leftover leg becomes an ungrouped position.

3. Grouping types (grouptype)​

ValueWho decides the groupsGroup IDIdentical groups combined?
ungrouped (default)No groupingn/an/a
orderbasedThe multi-leg order that filled the legsThe order IDYes, unless automerge=false
marginbasedThe margin system's pairingThe margin match IDNo. The margin system doesn't produce identical groups.
customYour Initial and Ongoing grouping modes, plus any groups you create, update, split or mergeBased on configuration: the order ID or margin match ID for groups formed by the grouping modes, or an opaque system-generated ID for groups you createYes, when the Ongoing grouping mode is orderbased and AutoMerge is true

ungrouped​

Returns a list of positions only, with no groups. This is similar to the existing Stream Positions endpoint.

orderbased​

Groups positions as they were entered, as a multi-leg order.

  • Positions filled by the same multi-leg order form one group, and the group ID is the order ID.
  • An order that touched only one position does not form a group; it is an ungrouped position.
  • Identical groups are combined into one group with summed quantities. Two 1x1 call verticals on the same strikes, bought in separate orders, appear as one group of quantity 2. A 1x1 and a 1x2 on the same strikes are not identical, so they are not combined. To keep each order's group separate, request the stream with automerge=false.
  • A combined group is split back into its original groups when their ratios and compositions no longer match, for example after part of it is closed.

marginbased​

Groups positions by how the margin system pairs them, to minimize margin. Includes MarginEstimate and BuyingPowerImpactEstimate.

  • Groups come from the margin system's pairing, not from the order. The group ID is the margin match ID (for example SPY-2).
  • Grouped positions carry their pairing's buying power impact and margin requirement. Ungrouped positions report zero for these, except futures and futures options, which keep their own values.

custom​

Groups positions using your grouping modes, and lets you manage groups directly.

  • Initial grouping mode (ungrouped, marginbased or orderbased) sets how existing positions are grouped when the account's groups are reset. Changing it resets existing groups. Any custom-mode stream that is running receives a GoAway status, then the connection closes, and must be restarted.
  • Ongoing grouping mode (ungrouped or orderbased) sets how new fills are grouped while the stream is running.
  • Both modes default to orderbased.
  • Identical groups are combined when the Ongoing grouping mode is orderbased. To turn this off, set AutoMerge to false with Update Position Grouping Mode. It is a user setting, not a query parameter, and running custom-mode streams apply it to groups formed after the change. Groups formed while it is off are not combined later if it is turned back on.

4. Aggregates (aggregates)​

When aggregates is specified, responses include rolled-up totals (MarketValue, UnrealizedProfitLoss, TodaysProfitLoss, and others) along with positions.

ValueDescription
accountOne aggregate per account containing all positions. Positions can also be grouped inside the aggregate, depending on grouptype.
accountandproductrootOne aggregate per account, containing one aggregate per product root, each with its positions and groups.

Incremental updates for streams with aggregates include changes to aggregate totals and to position fields.

Rules

  • Totals. MarketValue, UnrealizedProfitLoss, TodaysProfitLoss, TotalCost, MarginEstimate and BuyingPowerImpactEstimate are the sum of the same values from the items inside the aggregate. If any item is missing a value, the aggregate's total is omitted. It is not shown as a partial sum.
  • Percentages. An aggregate's UnrealizedProfitLossPercent is its own UnrealizedProfitLoss divided by the absolute value of its own TotalCost, times 100. It is never added or averaged from the items inside. If the aggregate holds exactly one item, it shows that item's percentage.
  • Fields shown for a single item only. These appear on a product root aggregate only while it qualifies. They are copied from the item inside it, and cleared when the aggregate stops qualifying.
    • P/L per quantity: when the product root holds exactly one group and no ungrouped positions, or exactly one ungrouped position and no groups.
    • BidSize, AskSize, LastSize and LastVenue: only when the product root holds exactly one ungrouped position and no groups.

Example: request and response

Request one account with orderbased grouping and both aggregate levels:

grouptype=orderbased&aggregates=accountandproductroot

The table shows each level of the response, indented to show what sits inside what, and what each level holds.

LevelHoldsMarketValueTotalCostUnrealizedProfitLossUnrealizedProfitLossPercent
Account aggregateAAPL aggregate, MSFT aggregate2,0251,8801457.713
  ↳ AAPL aggregate (product root)G1, P11,6251,5001258.333
      ↳ Group G1 (AAPL call vertical)Its legs1,1001,00010010.000
      ↳ Position P1 (100 AAPL shares)Ungrouped; nothing inside525500255.000
  ↳ MSFT aggregate (product root)P2400380205.263
      ↳ Position P2 (10 MSFT shares)Ungrouped; nothing inside400380205.263

5. Positions in more than one place​

A position can be in a group and ungrouped, or in several groups, at the same time. Each instance carries only the quantity held there.

  • MultiGroupAvgPrice is true on a position whose quantity is spread across two or more places. Add up all instances to get the account quantity.
  • Track a leg inside a group by group ID and position ID, separately from the same position elsewhere.
  • A position that is removed from one place is sent with a status that says where its quantity went:
StatusMeaning
GroupedMoved from ungrouped into one or more groups
UngroupedRemoved from a group and now ungrouped
RegroupedRemoved from this group, still in other groups
ClosedThe quantity held here was closed

Example. You buy a 3-lot call vertical, then a 2-lot butterfly that shares one of its calls. That call appears as 3 in the vertical and 2 in the butterfly, both with MultiGroupAvgPrice: true. The account quantity is 5.


6. Examples​

All three scenarios use orderbased grouping, so the group ID is the order ID. Order IDs are illustrative.

Scenario: buying the same spread twice and closing in parts​

This scenario uses the default, automerge=true. An iron condor here is long 1 Dec20 90 put, short 1 Dec20 95 put, short 1 Dec20 105 call and long 1 Dec20 110 call. The orders are: order A (first buy), order B (second buy), order C (the first sell) and order D (the second sell).

StepEventWhat the stream sends
1Buy 1 iron condor (order A)One group is created with group ID = order A: quantity 1, four legs at +1 / −1 / −1 / +1.
2Buy 1 more of the same iron condor (order B)The two groups are identical, so they are combined. The combined group keeps group ID = order A: quantity 2, each leg doubled. The group for order B is absorbed into it and is not kept as a separate group.
3Sell 1 iron condor (order C)The oldest order is closed first, so the combined group is split back into its source groups. The group for order A is sent with Deleted: true, and its legs have status Regrouped. The group for order B is sent as its own new group: group ID = order B, quantity 1 and legs at +1 / −1 / −1 / +1.
4Sell the other iron condor (order D)The group for order B is sent with Deleted: true. No group is created, and its legs have status Closed.

What developers should do

  • Step 2: the four leg positions each go from quantity 1 to 2. Update the stored group (order A) with the new quantity and leg quantities.
  • Step 3: each leg position's quantity falls from 2 to 1. The positions stay open. Group A arrives with Deleted: true, and the Regrouped status tells you its legs now sit in the new group (order B). Remove group A from your state and add group B. Do not record a new trade, and do not add to your leg quantities. They fell from 2 to 1.
  • Step 4: the four leg positions are fully closed and have status Closed. When group B arrives with Deleted: true, remove it, and remove the four closed positions.

Scenario: a position that is ungrouped and in more than one group​

A call vertical here is long 1 Dec20 100 call and short 1 Dec20 105 call.

StepEventWhat the stream sends
1Buy 3 Dec20 100 calls (order A, a single-leg order)One ungrouped position: 100 call, quantity 3. No group is created.
2Buy 2 call verticals (order B: long 2 Dec20 100 calls, short 2 Dec20 105 calls)One group is created with group ID = order B: quantity 2, legs +2 / −2. The 100 call is now held in two places: 2 in group B and 3 ungrouped. Both instances have MultiGroupAvgPrice: true.
3Buy 1 call vertical at a different short strike (order C: long 1 Dec20 100 call, short 1 Dec20 110 call)A second group is created with group ID = order C: quantity 1, legs +1 / −1. The 100 call is now held in three places: 3 ungrouped, 2 in group B and 1 in group C. Each instance has MultiGroupAvgPrice: true.

What developers should do

  • Store each instance of a position separately, keyed by group ID and position ID. Keep the ungrouped instance as its own entry without a group ID.
  • Do not merge the instances into one record. Add them together only when you need the account quantity.
  • Use MultiGroupAvgPrice to recognize that a position is held in more than one place, and display it accordingly.

Scenario: a group is updated when legs are sold​

A call butterfly here is long 1 Dec20 95 call, short 2 Dec20 100 calls and long 1 Dec20 105 call.

StepEventWhat the stream sends
1Buy 2 call butterflies (order A)One group is created with group ID = order A: quantity 2, legs +2 / −4 / +2.
2Sell 1 of the 95 calls (part of one leg)The group remains and is updated. The 95 call leg's quantity goes down to +1; the other legs are unchanged. The legs (+1 / −4 / +2) no longer match a butterfly, so the strategy part of GroupName becomes Custom, Quantity is recalculated as the greatest common divisor of the leg quantities (here, 1), and LongShort is set by the group's market value.
3Sell the other 95 call (the rest of that leg)The 95 call leg is removed from the group and has status Closed. The group remains and is updated with its two remaining legs: short 4 100 calls and long 2 105 calls.
4Sell the 105 calls (a second whole leg)Only one leg is left, so the group is sent with Deleted: true. The remaining short 100 call position is sent as an ungrouped position with status Ungrouped.

What developers should do

  • Steps 2 and 3: update the stored group (order A) in place. In step 3, drop the leg with status Closed from the group's legs.
  • Step 4: when the group arrives with Deleted: true, remove it. Add the remaining leg to your ungrouped positions.
  • Recalculate anything you derive from the legs (such as quantity or shape) each time. Do not assume the legs you saw earlier are still in the group.

7. Closing positions and groups​

The same rules apply to every group, in both orderbased and custom mode:

  • Closing part of a leg lowers that leg's quantity. The group stays.
  • Closing a whole leg removes that leg from the group. The group stays as long as at least two legs remain.
  • When only one leg is left, the group is sent with Deleted: true. The closed legs have status Closed, and the remaining leg is sent as an ungrouped position with status Ungrouped.
  • When every leg is closed, the group is sent with Deleted: true and every leg has status Closed.
  • Group IDs are not permanent. When groups are combined or split, a group can be deleted and replaced by another. Treat a Deleted: true group followed by a new group as normal behavior.

What differs between the two is how the service decides which group or ungrouped position a closing order reduces, when the same position is held in more than one place.

orderbased: by order​

Quantity is tracked per order. Each group holds the quantity filled by the order that created it, and a position's ungrouped quantity is also tracked by the orders that filled it.

  • A close reduces whichever orders TradeStation's position records show as reduced. Quantity comes off the oldest order first (FIFO), so which group shrinks depends on the order in which the orders were entered.
  • A combined group is split back into its original groups when their ratios and compositions no longer match, for example after part of it is closed.

Custom mode: by the shape of the closing order​

A closing order is matched against all the groups and ungrouped positions that hold its legs, in this order of preference:

  1. A group with exactly the same legs as the closing order. If more than one matches, the group with the smallest quantity is reduced first, then the oldest.
  2. Otherwise, the closest fit: the group or ungrouped position with the fewest legs that holds a leg being closed. An ungrouped position counts as one leg, so it is reduced before any group. If several have the same number of legs, it prefers one the order closes completely, then the one where it closes the most legs, then the oldest.
  3. Any quantity left over moves on to the next group or ungrouped position, using the same rules, until the whole close is applied.

Age is when the group was first created on the stream. Merging groups keeps the age of the oldest group in the merge.

Example: one position held in several places, closed in parts​

Custom mode. You hold the Dec20 100 call in three places: 10 ungrouped, 5 in call vertical G1 (long 5 Dec20 100 calls, short 5 Dec20 105 calls), and 5 in call vertical G2 (long 5 Dec20 100 calls, short 5 Dec20 110 calls). G1 was created before G2. You sell the 100 calls with single-leg orders.

StepEventWhere the quantity comes fromWhat the stream sends
1Sell 12 Dec20 100 callsThe ungrouped position has the fewest legs, so its 10 are closed first. The other 2 come from a group. G1 and G2 have the same number of legs and neither is closed completely, so the older one, G1, is reduced.The ungrouped 100 call is removed with status Closed. G1 is updated: the 100 call leg goes from 5 to 3; the 105 call leg is unchanged. G2 is unchanged.
2Sell 3 more Dec20 100 callsG1 and G2 still have the same number of legs, but this order closes G1's 100 call leg completely, so G1 is chosen.G1 has only one leg left, so it is sent with Deleted: true. Its 100 call leg has status Closed, and the short 105 calls are sent as an ungrouped position with status Ungrouped. G2 is unchanged.

Example: identical groups with different quantities, closed in parts​

Custom mode. You hold two identical call verticals, each long the Dec20 100 call and short the Dec20 105 call: G1 with quantity 10, created first, and G2 with quantity 5. Identical groups like these can exist side by side when you create or split groups yourself, or when AutoMerge is off. You close verticals with multi-leg orders.

StepEventWhere the quantity comes fromWhat the stream sends
1Sell 3 call verticalsBoth groups have exactly the same legs as the order, so the group with the smaller quantity, G2, is reduced.G2 is updated: quantity 2, legs +2 / −2. G1 is unchanged.
2Sell 4 call verticalsG2 is still the smaller exact match, so it absorbs the first 2 and closes. The remaining 2 move on to the next exact match, G1.G2 is sent with Deleted: true and both its legs have status Closed. G1 is updated: quantity 8, legs +8 / −8.

Age only decides between groups that tie on everything else. If G1 and G2 had the same quantity in step 1, the older group, G1, would have been reduced.