Market & Sessions¶

The Market, also called the Internal Market or Local Energy Market (LEM), is arguably RECreation's most important tool. It generates transactions between members, using the information currently uploaded, for every available session (status OPEN).

Because it is computationally expensive, the Market is an independent module. It is also the first operation to run, which makes it the front line for error checking: most problems with a community's configuration surface here, and only rarely in the Settlement module that runs afterwards.

flowchart LR
    A[Community configuration<br/>and uploaded data] --> B[Market<br/>clearing]
    B -->|Transactions| C[Settlement]

What is a Session?¶

A Session corresponds to one Interval Settlement Period (ISP) — a 15-minute interval aligned with smart meter reading resolution and OMIE's market time granularity. Sessions are the atomic unit for market clearing and settlement.

Session Lifecycle¶

%%{init: {"themeVariables": {"fontSize": "16px"}, "flowchart": {"nodeSpacing": 60, "rankSpacing": 120, "curve": "basis"}}}%%
flowchart LR
    S(( )) -->|Session created| OPEN
    OPEN -->|Market clearing runs| CLEARED
    CLEARED -->|Settlement computed| SETTLED
    SETTLED --> E(( ))
    CLEARED -.->|Reset| OPEN
    SETTLED -.->|Reset| OPEN

Dashed arrows are resets: see When Sessions Reset.

When Sessions Reset¶

A CLEARED or SETTLED session goes back to OPEN whenever something it was computed from changes after the fact. RECreation does this automatically so that results never disagree with the data behind them. Only the sessions in the affected period are reset.

When a session resets:

• Its transactions, offers, allocations and settlement outputs are deleted.
• Calculated opportunity costs for those sessions are deleted too, and are calculated again at the next market run.
• Uploaded meter measurements and uploaded opportunity costs are kept.
• You must run market clearing, and then settlement, again for those dates.

Typical examples:

See Business Validity for how dated changes work and how a market run splits into windows when the structure changes part-way through.

Local Energy Market (LEM)¶

In the LEM, members with surplus energy (producers/prosumers) trade with members needing energy (consumers). The market clearing algorithm matches offers and determines:

• Who buys from whom
• The clearing price (€/kWh)
• The traded quantity (kWh)

Pricing¶

The internal trading price is derived from the community's market_rate:

Opportunity Costs¶

An opportunity cost is what a CPE would pay or earn if it dealt with its retailer instead of the community, for one 15-minute interval. Together the two values bound the internal price: a member would never buy locally above what the retailer charges, nor sell locally below what the retailer pays for surplus.

Market clearing needs an opportunity cost for every CPE and every interval, and it gets them in one of two ways:

• Calculated from contracts. When the CPE's contract has tariff values (retailer prices, grid-access tariffs and OMIE prices where indexed), the platform computes l_buy and l_sell itself. Nothing needs to be uploaded.
• Uploaded by the integrator. When retailer pricing cannot be shared (contract buy_type and sell_type set to NO_VALUES), upload the values with POST /opportunity_costs. The upload must cover every session and every CPE in the period being cleared; otherwise market clearing is refused with an error saying the uploaded opportunity costs do not cover all sessions and meters.

Uploaded values take precedence: if any are present for the period, the platform uses them instead of calculating its own. Calculated values are stored for reference and are overwritten the next time the market runs, whereas uploaded ones are kept.

Bilateral Prices¶

With a bilateral market rate, the price is not derived from the market: each provider → receiver member pair has a price agreed beforehand and supplied by the integrator. There are two ways to supply it. Which one is used depends on the community's market_rate:

Only the prices of the community's current market rate are used. Prices uploaded for the other mode are ignored.

Fixed Bilateral Prices¶

Fixed bilateral prices set one price (€/kWh) for a provider → receiver member pair, applied to every interval of the period it covers. They are dated:

• POST /bilateral-prices/fixed creates prices; GET /bilateral-prices/fixed lists them with their periods.
• PUT /bilateral-prices/fixed/{receiver_user_id}/{provider_user_id} sets a new price for [start_date, end_date], keeping the price outside that period.
• DELETE /bilateral-prices/fixed/{receiver_user_id}/{provider_user_id}?effective_at=YYYY-MM-DD removes the price from that day. Add &end_date=YYYY-MM-DD to remove only that period.

See Business Validity.

Per-Interval Bilateral Prices¶

Per-interval bilateral prices let the price of a provider → receiver pair change from one 15-minute interval to the next. They are a time series.

• POST /bilateral-prices uploads a list of rows. Processing runs in the background and the response returns a task_id to poll.
• GET /bilateral-prices/by_provider returns a provider's prices over a date range, and GET /bilateral-prices/pagination lists the rows with filters.
• Market clearing is refused unless every session being cleared has at least one provider → receiver price. If members may act as either producer or consumer in an interval, provide prices for all possible pairs.

Transactions¶

Each cleared trade generates a Transaction record with:

Transaction Types¶