Skip to content
X4 Modding Wiki

Trade

A Trade is either a buy/sell offer at a Station, or an active trade order between buyer and seller. Trades are the unit of station economy — every Trade subscription update is a list of trades; every trade-completed event references a trade.

Inheritance: None — trade is its own root datatype. Trade is a transient operation entity, not a physical object.

Properties

Section titled “Properties”

The trade datatype has ~50 properties; group by concern.

Identity

Section titled “Identity”
PropertyTypeDescription
.existsboolTrade exists
.availableboolExists AND is available (not blocked)
.isofferboolBuy or sell offer at a station
.isorderboolActive trade deal between buyer/seller
.isbuyofferboolBuy offer at a station
.issellofferboolSell offer at a station
.warewareWhat’s being traded

Parties

Section titled “Parties”
PropertyTypeDescription
.buyercontainerBuyer if defined
.sellercontainerSeller if defined
.ownercontainerOwner (seller for sellOffer; buyer for buyOffer)
.exchangepartner.{container}containerOther party — for ship-to-ship the “other” container

Quantities

Section titled “Quantities”
PropertyTypeDescription
.amountintTrade amount
.desiredamountintWhat’s wanted (may exceed affordable)
.offeramountintTrade amount + reserved amounts
.minamountintMinimum trade
.transferredamountintWares already moved
.destroyedamountintWares destroyed (e.g. drone-shot transport)
.volume / .offervolume / .minvolumeintVolumes (mirrors amounts)

Pricing

Section titled “Pricing”
PropertyTypeDescription
.pricemoneyTotal price for amount
.unitpricemoneyPer-unit price
.minpricemoneyTotal for minimum amount
.relativepricefloat-1.0..+1.0 between min and max
.quantityfactorfloatcurrent/average price ratio
.hasdynamicpriceboolTrue if price not fixed (player-set)
.stocklevelfloatamount / target (signed by buy/sell)
.ispricelocked.{container}boolPrice locked on partner’s side

Special trade types

Section titled “Special trade types”
PropertyTypeDescription
.bundleboolConvert ammo/units → wares on transfer
.unbundleboolConvert ware → ammo/units on transfer
.iswareexchangeboolWare/crew exchange (not normal trade)
.isshiptoshipboolBoth partners are ships
.iscrewexchangeboolCrew movement trade
.isbuyerpassive / .issellerpassiveboolStationary party in S2S

Free flags (mission rewards)

Section titled “Free flags (mission rewards)”
PropertyTypeDescription
.buyfreeboolBuyer doesn’t actually pay
.sellfreeboolSeller doesn’t receive
.buyfree.{object} / .sellfree.{object}boolPer-object overrides
.ismissionboolTrade spawned by a mission cue
.missioncuecueThe spawning mission cue

Restrictions

Section titled “Restrictions”
PropertyTypeDescription
.restriction.factionslistFaction whitelist (empty = unrestricted)
.restriction.invertedboolList acts as blacklist instead
.cantradewith.{container}boolSpecific container allowed

Linkage

Section titled “Linkage”
PropertyTypeDescription
.tradeoffertradeSource offer this order derived from

Common patterns

Section titled “Common patterns”

”Watch player-relevant trades complete”

Section titled “”Watch player-relevant trades complete””

See Ware → Events for the canonical pattern with event_trade_completed.

”Filter offers vs orders"

Section titled “”Filter offers vs orders"”
<do_if value="$trade.isoffer">
    <!-- it's a posted offer at a station -->
</do_if>
<do_elseif value="$trade.isorder">
    <!-- it's an active deal in progress -->
</do_elseif>

"Read player’s pending trade volume”

Section titled “"Read player’s pending trade volume””
<set_value name="$total" exact="0"/>
<do_for_each name="$trade" in="player.ship.tradeorders">
    <set_value name="$total"
        operation="add"
        exact="$trade.volume"/>
</do_for_each>

Common gotchas

Section titled “Common gotchas”
  • ⚠ .amount vs .desiredamount vs .offeramount — three different quantities: actual current amount, what the buyer wants (regardless of affordability), and amount-plus-reservations. Don’t conflate.
  • ⚠ .bundle / .unbundle change content type on transfer. A bundle trade converts ammo/units into wares; unbundle does the reverse. Check before assuming “wares in = wares out”.
  • ⚠ Free trades still transfer wares. .buyfree=true means the buyer pays nothing; the wares still move. Use for mission-reward trades that don’t drain the treasury.
  • ⚠ Restriction list is a whitelist by default. .restriction.inverted=true flips it to a blacklist. Read both fields to interpret correctly.
  • ⚠ Ship-to-ship trades have one stationary party. .isbuyerpassive / .issellerpassive mark which side waits. Used for mining-ship-to-trader exchanges.
Section titled “Related”