openapi: 3.0.0
info:
  title: Otark Green SPOT API
  description: "Handels-API für Green-SPOT-Teilnehmer auf der Otark-Plattform: Preise, Day-ahead-Gebote, Zuschläge, Positionen je Stunde, Granular Matching, Granular Aftermarket, Sicherheiten und Abrechnungen."
  version: "1.0.0"
  contact: {}
servers:
  - url: https://api.otark.com
    description: Produktion
tags:
  - name: Prices
    description: Veröffentlichte Marktpreise je Liefertag und Stunde — p_bundle, p_grey und der Zertifikatpreis p_hc, jede Stunde mit ihren vier Viertelstundenwerten
  - name: Day-ahead bids
    description: Day-ahead-Gebote je Portfolio und Viertelstunde abgeben, ändern und bis zur Gate Closure zurückziehen
  - name: Awards
    description: Clearing-Ergebnisse — bezuschlagte Mengen und Preise je Liefertag und Stunde
  - name: Coverage
    description: "Die Position Pos(h) je Liefertag und Stunde, genettet über alle Anlagen und die vier Viertelstunden der Stunde"
  - name: Granular Matching
    description: "Kontinuierlicher Handel von Ansprüchen auf HC je Tupel (Liefertag, Stunde) im anonymen Orderbuch, allein zur Glattstellung (Phase 3)"
  - name: Granular Aftermarket
    description: "Marktplatz für ausgestellte HC in ganzen MWh (Phase 4): Inserate, Sofortkauf und Gegenangebote"
  - name: Collateral
    description: Hinterlegte Sicherheit, Sicherheitenbedarf und freies Limit (nur lesend)
  - name: Settlement
    description: "Abrechnungstage und ihre Positionen (nur lesend)"
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
  parameters:
    AfterParam:
      name: after
      in: query
      description: Cursor für die nächste Seite — den Wert `next_cursor` aus der vorherigen Antwort übergeben
      schema:
        type: string
        example: bid_a1b2c3d4
    LimitParam:
      name: limit
      in: query
      description: Höchstzahl der Einträge pro Seite
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10
    DeliveryDateParam:
      name: delivery_date
      in: query
      description: Nach Liefertag filtern (YYYY-MM-DD)
      schema:
        type: string
        format: date
        example: "2026-03-18"
    HourParam:
      name: hour
      in: query
      description: Nach der Stunde des Liefertags filtern (1–24 wie bei EPEX; Stunde 14 = 13:00–14:00 Uhr Europe/Berlin). Tage der Zeitumstellung folgen der EPEX-Konvention — 23 Stunden bei der Umstellung auf Sommerzeit (Stunde 3 entfällt), 25 bei der Umstellung auf Winterzeit (Stunde 3 doppelt als 3A/3B, unterschieden über `hour_suffix`).
      schema:
        type: integer
        minimum: 1
        maximum: 24
        example: 14
    HourSuffixParam:
      name: hour_suffix
      in: query
      description: Unterscheidet die doppelte Stunde 3 am 25-Stunden-Tag der Umstellung auf Winterzeit — `A` (noch MESZ) oder `B` (schon MEZ). Nur zusammen mit `hour=3` an diesem Liefertag sinnvoll.
      schema:
        type: string
        enum:
          - A
          - B
  headers:
    X-RateLimit-Limit:
      description: Höchstzahl der Anfragen je Zeitfenster
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Verbleibende Anfragen im laufenden Zeitfenster
      schema:
        type: integer
    X-RateLimit-Reset:
      description: Sekunden, bis das Zeitfenster der Ratenbegrenzung zurückgesetzt wird
      schema:
        type: integer
  schemas:
    Pagination:
      type: object
      properties:
        limit:
          type: integer
          description: Höchstzahl der Einträge pro Seite
          example: 10
        has_more:
          type: boolean
          description: Ob nach dem letzten gelieferten Eintrag weitere Einträge folgen
          example: true
        next_cursor:
          type: string
          nullable: true
          description: Cursor, der als Query-Parameter `after` übergeben wird, um die nächste Seite abzurufen. Null, wenn keine weiteren Seiten folgen.
          example: bid_x9y8z7w6
      required:
        - limit
        - has_more
        - next_cursor
    Problem:
      type: object
      description: Fehlerantwort nach [RFC 9457 — Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc9457).
      properties:
        type:
          type: string
          format: uri
          description: Absolute URI, die die Fehlerklasse bezeichnet
          example: https://api.otark.com/errors/gate_closed
        title:
          type: string
          description: Kurze, lesbare Bezeichnung (bei gleicher Fehlerklasse unverändert)
          example: Gate Closure Passed
        status:
          type: integer
          description: HTTP-Statuscode
          example: 409
        detail:
          type: string
          description: Lesbare Erläuterung dieses konkreten Falls
          example: The day-ahead gate for delivery day 2026-03-18 closed at 10:30 Europe/Berlin. Bids can no longer be changed or withdrawn.
        instance:
          type: string
          description: URI, die die konkrete Anfrage bezeichnet
          example: /v1/bids/bid_a1b2c3d4
        errors:
          type: array
          description: Feldbezogene Validierungsfehler (nur bei fehlgeschlagener Validierung)
          items:
            $ref: "#/components/schemas/ProblemFieldError"
      required:
        - type
        - title
        - status
    ProblemFieldError:
      type: object
      description: Ein einzelner feldbezogener Validierungsfehler
      properties:
        field:
          type: string
          description: JSON-Pfad des Feldes, das den Fehler ausgelöst hat
          example: quantity
        code:
          type: string
          description: "Maschinenlesbarer Fehlercode: `unknown_field`, `read_only_field`, `required`, `invalid_type`, `invalid_enum_value`, `invalid_format`, `invalid_literal`, `value_too_small`, `value_too_large` oder `validation_failed`"
          example: invalid_type
        message:
          type: string
          description: Lesbare Beschreibung des Fehlers
          example: Expected number, received string
      required:
        - code
        - message
    QuarterHourPrice:
      type: object
      description: Die veröffentlichten Preise und die geräumte Menge einer Viertelstunde. Alle Preise in EUR/MWh.
      properties:
        quarter_hour:
          type: integer
          minimum: 1
          maximum: 100
          description: Viertelstunde des Liefertags (1–96, an Umstellungstagen bis 100). Die Viertelstunden 53–56 bilden Stunde 14.
          example: 53
        p_bundle:
          type: number
          nullable: true
          description: Green-SPOT-Clearingpreis der Viertelstunde in EUR/MWh, aus der Day-ahead-Auktion. Null vor der ersten Veröffentlichung um 11:00 Uhr an D−1 und für Viertelstunden ohne geräumte Menge.
          example: 83.00
        p_grey:
          type: number
          nullable: true
          description: "Graustrompreis der Viertelstunde in EUR/MWh: der Day-ahead-Preis der EPEX SPOT DE/LU derselben Viertelstunde. Null bis zur zweiten Veröffentlichung um 15:00 Uhr an D−1. Bleibt das EPEX-Ergebnis bis 20:00 Uhr aus, steht hier der aus dem Ersatz-Spread abgeleitete Graustrompreis."
          example: 82.00
        spread:
          type: number
          nullable: true
          description: "p_bundle − p_grey der Viertelstunde in EUR/MWh; er kann negativ sein. Null, solange einer der beiden Werte fehlt."
          example: 1.00
        p_qhc:
          type: number
          nullable: true
          description: "Zertifikatpreis P_QHC der Viertelstunde in EUR/MWh: gleich dem Spread, ohne Preisboden, kann also negativ sein. Null, solange der Spread fehlt."
          example: 1.00
        q_cleared:
          type: number
          nullable: true
          description: Auf Green SPOT geräumte Menge dieser Viertelstunde in MWh (drei Nachkommastellen) — das Gewicht, mit dem p_qhc in p_hc eingeht. Null vor der ersten Veröffentlichung um 11:00 Uhr an D−1; 0 für eine Viertelstunde ohne geräumte Menge.
          example: 10.000
      required:
        - quarter_hour
        - p_bundle
        - p_grey
        - spread
        - p_qhc
        - q_cleared
    HourlyPrice:
      type: object
      description: Die veröffentlichten Preise einer Stunde eines Liefertags samt der vier Viertelstunden, aus denen sie aggregiert sind. Alle Preise in EUR/MWh.
      properties:
        delivery_date:
          type: string
          format: date
          description: Liefertag (YYYY-MM-DD)
          example: "2026-03-18"
        hour:
          type: integer
          minimum: 1
          maximum: 24
          description: Stunde des Liefertags, 1–24 wie bei EPEX (Stunde 14 = 13:00–14:00 Uhr Europe/Berlin). Am 25-Stunden-Tag der Umstellung auf Winterzeit tritt Stunde 3 zweimal auf — unterschieden durch `hour_suffix`.
          example: 14
        hour_suffix:
          type: string
          nullable: true
          description: "`A` (noch MESZ) oder `B` (schon MEZ) für die doppelte Stunde 3 am 25-Stunden-Tag der Umstellung auf Winterzeit; bei allen anderen Stunden null. (D, 3A) und (D, 3B) sind zwei eigene, nicht fungible Produkte."
          enum:
            - A
            - B
          example: null
        p_bundle:
          type: number
          nullable: true
          description: Green-SPOT-Clearingpreis der Stunde in EUR/MWh — die mengengewichtete Aggregation der Viertelstunden-Clearingpreise auf die Stunde. Null vor der ersten Veröffentlichung um 11:00 Uhr an D−1 und für Stunden ohne geräumte Menge.
          example: 85.00
        p_grey:
          type: number
          nullable: true
          description: "Graustrompreis der Stunde in EUR/MWh: der Day-ahead-Preis der EPEX SPOT DE/LU, mit denselben Gewichten wie p_bundle auf die Stunde aggregiert. Null bis zur zweiten Veröffentlichung um 15:00 Uhr an D−1."
          example: 80.00
        spread:
          type: number
          nullable: true
          description: p_bundle − p_grey in EUR/MWh. Null, solange einer der beiden Werte fehlt.
          example: 5.00
        p_hc:
          type: number
          nullable: true
          description: "Zertifikatpreis P_HC der Stunde in EUR/MWh: das mit der geräumten Menge je Viertelstunde gewichtete Mittel der vier P_QHC dieser Stunde, kaufmännisch auf zwei Nachkommastellen gerundet und aus `quarter_hours` nachrechenbar; er kann negativ sein. Null vor der zweiten Veröffentlichung um 15:00 Uhr an D−1 und für eine Stunde ohne geräumte Menge. Einmal veröffentlicht, steht er für den gesamten Lebenszyklus des Liefertags fest. Er geht als P_HC,DA(h) in den Referenzpreis P_ref(h) ein."
          example: 5.00
        p_hc_source:
          type: string
          nullable: true
          description: "Wie p_hc bestimmt wurde: `spread` für jede Stunde mit geräumter Menge. Für eine Stunde ohne geräumte Menge sind p_hc und p_hc_source null."
          enum:
            - spread
          example: spread
        quarter_hours:
          type: array
          description: Die vier Viertelstunden, aus denen die Stunde aggregiert ist, je mit eigenen Preisen und eigener geräumter Menge — die Eingangsgrößen von p_bundle, p_grey und p_hc. Vor der ersten Veröffentlichung um 11:00 Uhr an D−1 leer.
          items:
            $ref: "#/components/schemas/QuarterHourPrice"
        published_at:
          type: string
          format: date-time
          nullable: true
          description: ISO-8601-Zeitstempel der zweiten Veröffentlichung, mit der p_hc feststand (15:00 Uhr Europe/Berlin an D−1). Vor der Veröffentlichung null.
          example: "2026-03-17T14:00:00Z"
      required:
        - delivery_date
        - hour
        - hour_suffix
        - p_bundle
        - p_grey
        - spread
        - p_hc
        - p_hc_source
        - quarter_hours
        - published_at
    DayPrices:
      type: object
      properties:
        delivery_date:
          type: string
          format: date
          description: Liefertag (YYYY-MM-DD)
          example: "2026-03-18"
        hours:
          type: array
          description: Ein Eintrag je Stunde des Liefertags — 24 an einem gewöhnlichen Tag, 23 bei der Umstellung auf Sommerzeit (Stunde 3 entfällt), 25 bei der Umstellung auf Winterzeit (Stunde 3 als 3A und 3B)
          items:
            $ref: "#/components/schemas/HourlyPrice"
      required:
        - delivery_date
        - hours
    Bid:
      type: object
      description: Ein Day-ahead-Gebot für eine Viertelstunde eines Liefertags. Geboten wird auf beiden Marktseiten je Portfolio.
      properties:
        id:
          type: string
          description: Eindeutige Kennung des Gebots
          example: bid_a1b2c3d4
        direction:
          type: string
          description: Richtung des Gebots
          enum:
            - buy
            - sell
          example: sell
        portfolio_id:
          type: string
          description: Portfolio, für das das Gebot abgegeben wurde — bei Verkaufsgeboten das Anlagenportfolio des Verkäufers, bei Kaufgeboten das Messstellenportfolio des Käufers
          example: portfolio_w1n2o3r4
        delivery_date:
          type: string
          format: date
          description: Liefertag (YYYY-MM-DD)
          example: "2026-03-18"
        quarter_hour:
          type: integer
          minimum: 1
          maximum: 100
          description: Viertelstunde des Liefertags (1–96, an Tagen der Zeitumstellung bis 100). Die Viertelstunden 53–56 bilden Stunde 14.
          example: 54
        quantity:
          type: number
          description: Gebotsmenge in MWh für die Viertelstunde (3 Nachkommastellen). Das Regelwerk nennt Mindestmenge und Schrittweite im Day-ahead in MW — 0,1 MW je Gebot, in Schritten von 0,1 MW —, was je Viertelstunde Vielfachen von 0,025 MWh entspricht; Mengen außerhalb dieses Rasters werden zurückgewiesen.
          example: 6.000
        price_limit:
          type: number
          description: Limitpreis in EUR/MWh (2 Nachkommastellen)
          example: 80.00
        status:
          type: string
          description: "`open` bis zur Gate Closure (änderbar und zurückziehbar), `binding` ab der Gate Closure (unwiderruflich), `withdrawn`, wenn es vor der Gate Closure zurückgezogen wurde"
          enum:
            - open
            - binding
            - withdrawn
          example: open
        created_at:
          type: string
          format: date-time
          description: ISO-8601-Zeitstempel der Anlage
          example: "2026-03-17T08:15:00Z"
      required:
        - id
        - direction
        - portfolio_id
        - delivery_date
        - quarter_hour
        - quantity
        - price_limit
        - status
        - created_at
    BidCreate:
      type: object
      description: Ein neues Day-ahead-Gebot. `portfolio_id` benennt das Portfolio, für das geboten wird — bei Verkaufsgeboten ein Anlagenportfolio, bei Kaufgeboten ein Messstellenportfolio.
      properties:
        direction:
          type: string
          description: Richtung des Gebots
          enum:
            - buy
            - sell
          example: sell
        portfolio_id:
          type: string
          description: Portfolio, für das geboten wird
          example: portfolio_w1n2o3r4
        delivery_date:
          type: string
          format: date
          description: Liefertag (YYYY-MM-DD)
          example: "2026-03-18"
        quarter_hour:
          type: integer
          minimum: 1
          maximum: 100
          description: Viertelstunde des Liefertags (1–96, an Tagen der Zeitumstellung bis 100)
          example: 54
        quantity:
          type: number
          description: Gebotsmenge in MWh für die Viertelstunde (3 Nachkommastellen). Das Regelwerk nennt Mindestmenge und Schrittweite im Day-ahead in MW — 0,1 MW je Gebot, in Schritten von 0,1 MW —, was je Viertelstunde Vielfachen von 0,025 MWh entspricht; Mengen außerhalb dieses Rasters werden zurückgewiesen.
          example: 6.000
        price_limit:
          type: number
          description: Limitpreis in EUR/MWh (2 Nachkommastellen)
          example: 80.00
      required:
        - direction
        - delivery_date
        - quarter_hour
        - quantity
        - price_limit
    BidUpdate:
      type: object
      description: Änderungen an einem offenen Gebot. Richtung, Portfolio und das Tupel (Liefertag, Viertelstunde) stehen fest — um sie zu ändern, ziehen Sie das Gebot zurück und geben ein neues ab.
      properties:
        quantity:
          type: number
          description: Neue Gebotsmenge in MWh (3 Nachkommastellen) — wie beim ursprünglichen Gebot ein Vielfaches von 0,025 MWh je Viertelstunde (Schritte von 0,1 MW)
          example: 5.000
        price_limit:
          type: number
          description: Neuer Limitpreis in EUR/MWh (2 Nachkommastellen)
          example: 80.00
    BidList:
      type: object
      properties:
        bids:
          type: array
          description: Liste der Gebote
          items:
            $ref: "#/components/schemas/Bid"
        pagination:
          $ref: "#/components/schemas/Pagination"
      required:
        - bids
        - pagination
    AwardQuarterHour:
      type: object
      description: Die bezuschlagte Menge und der Clearingpreis einer Viertelstunde
      properties:
        quarter_hour:
          type: integer
          minimum: 1
          maximum: 100
          description: Viertelstunde des Liefertags (1–96, an Tagen der Zeitumstellung bis 100)
          example: 53
        quantity:
          type: number
          description: Bezuschlagte Menge in MWh (3 Nachkommastellen)
          example: 4.000
        price:
          type: number
          description: Clearingpreis p_bundle der Viertelstunde in EUR/MWh
          example: 83.00
      required:
        - quarter_hour
        - quantity
        - price
    Award:
      type: object
      description: "Die Day-ahead-Zuschläge eines Portfolios für eine Stunde eines Liefertags, zusammengefasst aus den Viertelstundenzuschlägen. Das Tupel jedes Zuschlags ist (Liefertag, Viertelstunde): Lieferverpflichtung und Kaufpreis entstehen je Viertelstunde und stehen in `quarter_hours`. Ein HC der Stunde erfüllt die Pflicht aus jeder Viertelstunde dieser Stunde."
      properties:
        id:
          type: string
          description: Eindeutige Kennung des Zuschlags
          example: awd_c3d4e5f6
        direction:
          type: string
          description: Seite des Zuschlags aus Sicht des Aufrufers
          enum:
            - buy
            - sell
          example: sell
        portfolio_id:
          type: string
          description: Bezuschlagtes Portfolio — bei Verkaufszuschlägen das Anlagenportfolio des Verkäufers, bei Kaufzuschlägen das Messstellenportfolio des Käufers
          example: portfolio_w1n2o3r4
        delivery_date:
          type: string
          format: date
          description: Liefertag (YYYY-MM-DD)
          example: "2026-03-18"
        hour:
          type: integer
          minimum: 1
          maximum: 24
          description: Stunde des Liefertags, 1–24 wie bei EPEX (Stunde 14 = 13:00–14:00 Uhr Europe/Berlin). Am 25-Stunden-Tag der Umstellung auf Winterzeit tritt Stunde 3 zweimal auf — unterschieden durch `hour_suffix`.
          example: 14
        hour_suffix:
          type: string
          nullable: true
          description: "`A` (noch MESZ) oder `B` (schon MEZ) für die doppelte Stunde 3 am 25-Stunden-Tag der Umstellung auf Winterzeit; bei allen anderen Stunden null"
          enum:
            - A
            - B
          example: null
        quantity:
          type: number
          description: Stundensumme des Zuschlags Q_award(h) in MWh — die Summe der vier Viertelstundenzuschläge (3 Nachkommastellen)
          example: 20.000
        price:
          type: number
          description: "Stunden-Clearingpreis p_bundle(h) in EUR/MWh, mit der marktweit geräumten Menge je Viertelstunde gewichtet. Der Kaufpreis rechnet je Viertelstunde aus `quarter_hours`, nicht als quantity × price."
          example: 85.00
        quarter_hours:
          type: array
          description: Die Viertelstundenzuschläge, aus denen die Stunde besteht
          items:
            $ref: "#/components/schemas/AwardQuarterHour"
        awarded_at:
          type: string
          format: date-time
          description: ISO-8601-Zeitstempel der ersten Veröffentlichung (11:00 Uhr Europe/Berlin an D−1)
          example: "2026-03-17T10:00:00Z"
      required:
        - id
        - direction
        - portfolio_id
        - delivery_date
        - hour
        - hour_suffix
        - quantity
        - price
        - quarter_hours
        - awarded_at
    AwardList:
      type: object
      properties:
        awards:
          type: array
          description: Liste der Zuschläge
          items:
            $ref: "#/components/schemas/Award"
        pagination:
          $ref: "#/components/schemas/Pagination"
      required:
        - awards
        - pagination
    CoveragePosition:
      type: object
      description: "Die Position Pos(h) eines Teilnehmers für ein Tupel (Liefertag, Stunde), genettet über alle Portfolios, Anlagen, Technologien und die vier Viertelstunden der Stunde. Alle Mengen in MWh: Pos(h) = q_metered − (q_sold − q_bought); negativ heißt short, positiv long. Die API rechnet sie mit jedem Eingang abrechnungsrelevanter Messwerte und nach jedem Geschäft neu."
      properties:
        delivery_date:
          type: string
          format: date
          description: Liefertag (YYYY-MM-DD)
          example: "2026-03-18"
        hour:
          type: integer
          minimum: 1
          maximum: 24
          description: Stunde des Liefertags, 1–24 wie bei EPEX (Stunde 14 = 13:00–14:00 Uhr Europe/Berlin). Am 25-Stunden-Tag der Umstellung auf Winterzeit tritt Stunde 3 zweimal auf — 3A und 3B werden getrennt genettet, ein Überschuss in der einen deckt nie eine Lücke in der anderen.
          example: 14
        hour_suffix:
          type: string
          nullable: true
          description: "`A` (noch MESZ) oder `B` (schon MEZ) für die doppelte Stunde 3 am 25-Stunden-Tag der Umstellung auf Winterzeit; bei allen anderen Stunden null"
          enum:
            - A
            - B
          example: null
        q_award:
          type: number
          description: "Sollmenge Q_award der Stunde in MWh: im Day-ahead zugeschlagene und im Intraday verkaufte Liefermenge, Summe der Viertelstunden. Sie ist in q_sold enthalten."
          example: 20.000
        q_metered:
          type: number
          description: "Abrechnungsrelevante Messwerte des MSB der Stunde in MWh über alle Anlagen des Teilnehmers, je Viertelstunde auf volle kWh abgerundet, ab dem Korrekturschluss am 20. des Folgemonats eingefroren. Gemeldete oder vorläufige Werte gehen nie in diese Zahl ein."
          example: 16.000
        q_bought:
          type: number
          description: "Summe aller Käufe der Stunde in MWh über Day-ahead, Intraday, Granular Matching und Aftermarket (Q_bought(h))"
          example: 3.000
        q_sold:
          type: number
          description: "Summe aller Verkäufe der Stunde in MWh über Day-ahead, Intraday, Granular Matching und Aftermarket (Q_sold(h)), einschließlich q_award"
          example: 20.000
        q_gap:
          type: number
          description: "Short-Menge max(0; −Pos(h)) in MWh, nie negativ. Bis zu dieser Menge darf der Teilnehmer im Granular Matching kaufen; das letzte gekaufte Los darf die Position auf höchstens +0,025 MWh heben. Offene Kauforders vermindern das Feld nicht; die API rechnet sie bei der Prüfung jeder neuen Kauforder auf die Grenze mit. Zum Ende des GM-Fensters ist die Short-Menge die Fehlmenge F(h), die OES auf Basis der eingefrorenen Messwerte feststellt."
          example: 1.000
        free_position:
          type: number
          description: "Long-Menge max(0; Pos(h)) in MWh, vermindert um die eigenen offenen Verkaufsorders im Granular Matching und die auf dem Aftermarket inserierten HC derselben Stunde: bis zu dieser Menge darf der Teilnehmer im Granular Matching verkaufen. Verkaufsorders darüber hinaus weist die API zurück."
          example: 0.000
        matching_opens_at:
          type: string
          format: date-time
          description: "ISO-8601-Zeitstempel, zu dem das Granular Matching für diesen Liefertag öffnet (D+1, 15:00 Uhr Europe/Berlin)"
          example: "2026-03-19T14:00:00Z"
        final_gate_at:
          type: string
          format: date-time
          description: "ISO-8601-Zeitstempel des Endes des GM-Fensters dieses Liefertags: Ablauf des letzten Kalendertags des Folgemonats (24:00 Uhr Europe/Berlin), bei einer Störung des Marktbetriebs um deren Dauer später. Zu diesem Zeitpunkt stellt OES die Fehlmenge F(h) fest."
          example: "2026-04-30T22:00:00Z"
      required:
        - delivery_date
        - hour
        - hour_suffix
        - q_award
        - q_metered
        - q_bought
        - q_sold
        - q_gap
        - free_position
        - matching_opens_at
        - final_gate_at
    CoverageList:
      type: object
      properties:
        positions:
          type: array
          description: Liste der Positionen
          items:
            $ref: "#/components/schemas/CoveragePosition"
        pagination:
          $ref: "#/components/schemas/Pagination"
      required:
        - positions
        - pagination
    Order:
      type: object
      description: "Eine Limit-Order im anonymen Orderbuch des Granular Matching. Gehandelt werden Ansprüche auf HC je Tupel (Liefertag, Stunde); Gegenpartei jedes Abschlusses ist OES."
      properties:
        id:
          type: string
          description: Eindeutige Kennung der Order
          example: ord_g7h8i9j0
        side:
          type: string
          description: Seite der Order
          enum:
            - buy
            - sell
          example: buy
        delivery_date:
          type: string
          format: date
          description: Liefertag des gehandelten Tupels (YYYY-MM-DD)
          example: "2026-03-18"
        hour:
          type: integer
          minimum: 1
          maximum: 24
          description: Stunde des gehandelten Tupels, 1–24 wie bei EPEX (Stunde 14 = 13:00–14:00 Uhr Europe/Berlin). Am 25-Stunden-Tag der Umstellung auf Winterzeit sind (D, 3A) und (D, 3B) zwei eigene, nicht fungible Produkte mit eigenen Orderbüchern — unterschieden durch `hour_suffix`.
          example: 14
        hour_suffix:
          type: string
          nullable: true
          description: "`A` (noch MESZ) oder `B` (schon MEZ) für die doppelte Stunde 3 am 25-Stunden-Tag der Umstellung auf Winterzeit; bei allen anderen Stunden null"
          enum:
            - A
            - B
          example: null
        quantity:
          type: number
          description: Ursprüngliche Ordermenge in MWh (3 Nachkommastellen)
          example: 4.000
        quantity_open:
          type: number
          description: Nicht ausgeführter Rest in MWh. Eine Teilausführung ist stets zulässig — der Rest bleibt im Orderbuch.
          example: 1.000
        price_limit:
          type: number
          minimum: 0
          description: "Limitpreis in EUR/MWh (2 Nachkommastellen), zwischen 0,00 und 1.000 EUR/MWh"
          example: 5.60
        status:
          type: string
          description: "`open`, solange ein Rest im Orderbuch liegt, `filled` bei vollständiger Ausführung, `cancelled` beim Löschen"
          enum:
            - open
            - filled
            - cancelled
          example: open
        created_at:
          type: string
          format: date-time
          description: ISO-8601-Zeitstempel der Anlage
          example: "2026-03-20T09:03:00Z"
      required:
        - id
        - side
        - delivery_date
        - hour
        - hour_suffix
        - quantity
        - quantity_open
        - price_limit
        - status
        - created_at
    OrderCreate:
      type: object
      description: Eine neue Limit-Order für das Granular Matching
      properties:
        side:
          type: string
          description: Seite der Order
          enum:
            - buy
            - sell
          example: buy
        delivery_date:
          type: string
          format: date
          description: Liefertag des Tupels (YYYY-MM-DD)
          example: "2026-03-18"
        hour:
          type: integer
          minimum: 1
          maximum: 24
          description: Stunde des Tupels (1–24 wie bei EPEX)
          example: 14
        hour_suffix:
          type: string
          description: Erforderlich, um Stunde 3 am 25-Stunden-Tag der Umstellung auf Winterzeit anzusprechen — `A` (noch MESZ) oder `B` (schon MEZ); bei allen anderen Stunden entfällt die Angabe
          enum:
            - A
            - B
        quantity:
          type: number
          description: "Ordermenge in MWh, ein Vielfaches von 0,025 MWh"
          example: 4.000
        price_limit:
          type: number
          minimum: 0
          description: "Limitpreis in EUR/MWh (2 Nachkommastellen), zwischen 0,00 und 1.000 EUR/MWh; ein Limit außerhalb weist die API zurück"
          example: 5.60
      required:
        - side
        - delivery_date
        - hour
        - quantity
        - price_limit
    OrderUpdate:
      type: object
      description: Änderungen an einer offenen Order. Seite und das Tupel (Liefertag, Stunde) stehen fest — um sie zu ändern, löschen Sie die Order und geben eine neue auf.
      properties:
        quantity:
          type: number
          description: Neue Ordermenge in MWh (3 Nachkommastellen) — mindestens die bereits ausgeführte Menge
          example: 3.000
        price_limit:
          type: number
          minimum: 0
          description: Neuer Limitpreis in EUR/MWh (2 Nachkommastellen)
          example: 5.50
    OrderList:
      type: object
      properties:
        orders:
          type: array
          description: Liste der Orders
          items:
            $ref: "#/components/schemas/Order"
        pagination:
          $ref: "#/components/schemas/Pagination"
      required:
        - orders
        - pagination
    Trade:
      type: object
      description: "Ein Abschluss des Aufrufers im Granular Matching. Die Otark GmbH veröffentlicht jeden Abschluss sofort mit Preis und Menge, ohne die Beteiligten."
      properties:
        id:
          type: string
          description: Eindeutige Kennung des Geschäfts
          example: trd_k1l2m3n4
        order_id:
          type: string
          description: Die Order des Aufrufers, gegen die dieses Geschäft ausgeführt wurde
          example: ord_g7h8i9j0
        side:
          type: string
          description: Seite des Geschäfts aus Sicht des Aufrufers
          enum:
            - buy
            - sell
          example: buy
        delivery_date:
          type: string
          format: date
          description: Liefertag des gehandelten Tupels (YYYY-MM-DD)
          example: "2026-03-18"
        hour:
          type: integer
          minimum: 1
          maximum: 24
          description: Stunde des gehandelten Tupels (1–24 wie bei EPEX)
          example: 14
        hour_suffix:
          type: string
          nullable: true
          description: "`A` (noch MESZ) oder `B` (schon MEZ) für die doppelte Stunde 3 am 25-Stunden-Tag der Umstellung auf Winterzeit; bei allen anderen Stunden null"
          enum:
            - A
            - B
          example: null
        quantity:
          type: number
          description: Ausgeführte Menge in MWh (3 Nachkommastellen)
          example: 2.000
        price:
          type: number
          description: Ausführungspreis in EUR/MWh
          example: 5.40
        amount:
          type: number
          description: Betrag des Geschäfts in EUR (Menge × Preis)
          example: 10.80
        executed_at:
          type: string
          format: date-time
          description: ISO-8601-Zeitstempel der Ausführung
          example: "2026-03-20T09:03:00Z"
      required:
        - id
        - order_id
        - side
        - delivery_date
        - hour
        - hour_suffix
        - quantity
        - price
        - amount
        - executed_at
    TradeList:
      type: object
      properties:
        trades:
          type: array
          description: Liste der Geschäfte
          items:
            $ref: "#/components/schemas/Trade"
        pagination:
          $ref: "#/components/schemas/Pagination"
      required:
        - trades
        - pagination
    Listing:
      type: object
      description: "Ein Inserat auf dem Granular Aftermarket. Gehandelt werden ausgestellte HC in ganzen MWh (1 MWh = 1 HKN). Inserate sind anonym: Der Markt sieht Liefertag, Stunde, Menge und Preis, nie den Inserenten."
      properties:
        id:
          type: string
          description: Eindeutige Kennung des Inserats
          example: lst_p5q6r7s8
        side:
          type: string
          description: Seite des Inserats
          enum:
            - buy
            - sell
          example: sell
        delivery_date:
          type: string
          format: date
          description: Liefertag der GC (YYYY-MM-DD)
          example: "2026-03-18"
        hour:
          type: integer
          minimum: 1
          maximum: 24
          description: Stunde des Liefertags (1–24 wie bei EPEX)
          example: 14
        hour_suffix:
          type: string
          nullable: true
          description: "`A` (noch MESZ) oder `B` (schon MEZ) für die doppelte Stunde 3 am 25-Stunden-Tag der Umstellung auf Winterzeit; bei allen anderen Stunden null"
          enum:
            - A
            - B
          example: null
        quantity:
          type: integer
          minimum: 1
          description: Inserierte Menge in ganzen MWh
          example: 10
        quantity_open:
          type: integer
          description: Verbleibende, nicht angenommene Menge in ganzen MWh
          example: 2
        price:
          type: number
          minimum: 0
          description: Inseratspreis in EUR/MWh (2 Nachkommastellen, Pflichtangabe, Boden bei 0,00)
          example: 5.50
        allow_partial:
          type: boolean
          description: Ob der Inserent die unmittelbare Annahme von Teilmengen in ganzen MWh zulässt. Ohne diese Option umfasst die unmittelbare Annahme allein die volle offene Menge; kleinere Mengen verlangen dann ein Gegenangebot.
          example: false
        status:
          type: string
          description: "`open`, solange es angeboten ist, `completed` bei vollständiger Annahme, `withdrawn`, wenn der Inserent es gelöscht hat, `expired`, wenn es mit dem Board-Schluss erloschen ist"
          enum:
            - open
            - completed
            - withdrawn
            - expired
          example: open
        expires_on:
          type: string
          format: date
          description: "Tag, an dem das Inserat spätestens erlischt: der Board-Schluss, 10 Monate nach Ende des Erzeugungsmonats"
          example: "2027-01-31"
        counter_offers:
          type: array
          description: Die Gegenangebote auf dieses Inserat (nur vorhanden bei `include_counter_offers=true` — bei eigenen Inseraten die eingegangenen Gegenangebote, bei fremden nur die eigenen des Aufrufers)
          items:
            $ref: "#/components/schemas/CounterOffer"
        created_at:
          type: string
          format: date-time
          description: ISO-8601-Zeitstempel der Anlage
          example: "2026-04-22T09:00:00Z"
      required:
        - id
        - side
        - delivery_date
        - hour
        - hour_suffix
        - quantity
        - quantity_open
        - price
        - allow_partial
        - status
        - expires_on
        - created_at
    ListingCreate:
      type: object
      description: Ein neues Inserat auf dem Granular Aftermarket
      properties:
        side:
          type: string
          description: Seite des Inserats
          enum:
            - buy
            - sell
          example: sell
        delivery_date:
          type: string
          format: date
          description: Liefertag der GC (YYYY-MM-DD)
          example: "2026-03-18"
        hour:
          type: integer
          minimum: 1
          maximum: 24
          description: Stunde des Liefertags (1–24 wie bei EPEX)
          example: 14
        hour_suffix:
          type: string
          description: Erforderlich, um Stunde 3 am 25-Stunden-Tag der Umstellung auf Winterzeit anzusprechen — `A` (noch MESZ) oder `B` (schon MEZ); bei allen anderen Stunden entfällt die Angabe
          enum:
            - A
            - B
        quantity:
          type: integer
          minimum: 1
          description: Menge in ganzen MWh
          example: 10
        price:
          type: number
          minimum: 0
          description: Preis in EUR/MWh (2 Nachkommastellen, Pflichtangabe, Boden bei 0,00)
          example: 5.50
        allow_partial:
          type: boolean
          description: Die unmittelbare Annahme von Teilmengen zulassen (Voreinstellung false)
          default: false
          example: false
      required:
        - side
        - delivery_date
        - hour
        - quantity
        - price
    ListingUpdate:
      type: object
      description: Änderungen an einem offenen Inserat. Seite und das Tupel (Liefertag, Stunde) stehen fest — um sie zu ändern, löschen Sie das Inserat und legen ein neues an.
      properties:
        quantity:
          type: integer
          minimum: 1
          description: Neue Menge in ganzen MWh
          example: 8
        price:
          type: number
          minimum: 0
          description: Neuer Preis in EUR/MWh (2 Nachkommastellen, Boden bei 0,00)
          example: 5.40
        allow_partial:
          type: boolean
          description: Die unmittelbare Annahme von Teilmengen zulassen
          example: true
    ListingList:
      type: object
      properties:
        listings:
          type: array
          description: Liste der Inserate
          items:
            $ref: "#/components/schemas/Listing"
        pagination:
          $ref: "#/components/schemas/Pagination"
      required:
        - listings
        - pagination
    ListingAccept:
      type: object
      description: Annahme eines Inserats zu seinem Preis
      properties:
        quantity:
          type: integer
          minimum: 1
          description: Anzunehmende Menge in ganzen MWh. Bleibt die Angabe weg, wird die volle offene Menge angenommen; eine Teilmenge ist nur zulässig, wenn der Inserent `allow_partial` gesetzt hat.
          example: 2
    CounterOffer:
      type: object
      description: Ein Gegenangebot auf ein Inserat, mit anderem Preis, kleinerer Menge oder beidem. Es bindet den Anbietenden 72 Stunden und erlischt danach von selbst.
      properties:
        id:
          type: string
          description: Eindeutige Kennung des Gegenangebots
          example: cof_t9u0v1w2
        listing_id:
          type: string
          description: Das Inserat, auf das sich das Gegenangebot bezieht
          example: lst_p5q6r7s8
        quantity:
          type: integer
          minimum: 1
          description: Angebotene Menge in ganzen MWh (höchstens die offene Menge des Inserats)
          example: 8
        price:
          type: number
          minimum: 0
          description: Angebotener Preis in EUR/MWh (2 Nachkommastellen)
          example: 5.20
        status:
          type: string
          description: "`open` innerhalb der Bindefrist, `accepted` durch den Inserenten, `rejected` automatisch, sobald es nicht mehr zum Inserat passt, `expired` nach Ablauf der Bindefrist"
          enum:
            - open
            - accepted
            - rejected
            - expired
          example: open
        binds_until:
          type: string
          format: date-time
          description: ISO-8601-Ende der 72-stündigen Bindefrist
          example: "2026-04-25T09:30:00Z"
        created_at:
          type: string
          format: date-time
          description: ISO-8601-Zeitstempel der Anlage
          example: "2026-04-22T09:30:00Z"
      required:
        - id
        - listing_id
        - quantity
        - price
        - status
        - binds_until
        - created_at
    CounterOfferCreate:
      type: object
      description: Ein neues Gegenangebot auf ein Inserat
      properties:
        quantity:
          type: integer
          minimum: 1
          description: Menge in ganzen MWh — höchstens die offene Menge des Inserats
          example: 8
        price:
          type: number
          minimum: 0
          description: Preis in EUR/MWh (2 Nachkommastellen)
          example: 5.20
      required:
        - quantity
        - price
    BoardTrade:
      type: object
      description: "Ein Geschäft auf dem Granular Aftermarket, Zug um Zug abgewickelt: OES rechnet es am Tag nach dem Handelstag (TD+1) ab und zieht den Kaufpreis an TD+2 per Lastschrift beim Käufer ein. Erst nach dem festgestellten Geldeingang (TD+5) überträgt OES HC und HKN auf das GCR-Konto und das benannte HKNR-Konto des Käufers und überweist den Kaufpreis am Bankarbeitstag danach (TD+6) an den Verkäufer. Scheitert der Einzug, entfällt das Geschäft mit Ablauf der Frist nach Rückgabe der Lastschrift, und der Verkäufer kann die HC erneut anbieten."
      properties:
        id:
          type: string
          description: Eindeutige Kennung des Geschäfts
          example: btr_x3y4z5a6
        listing_id:
          type: string
          description: Das Inserat, über das das Geschäft zustande gekommen ist
          example: lst_p5q6r7s8
        counter_offer_id:
          type: string
          nullable: true
          description: Das angenommene Gegenangebot (bei unmittelbarer Annahme null)
          example: cof_t9u0v1w2
        side:
          type: string
          description: Seite des Geschäfts aus Sicht des Aufrufers
          enum:
            - buy
            - sell
          example: sell
        delivery_date:
          type: string
          format: date
          description: Liefertag der GC (YYYY-MM-DD)
          example: "2026-03-18"
        hour:
          type: integer
          minimum: 1
          maximum: 24
          description: Stunde des Liefertags (1–24 wie bei EPEX)
          example: 14
        hour_suffix:
          type: string
          nullable: true
          description: "`A` (noch MESZ) oder `B` (schon MEZ) für die doppelte Stunde 3 am 25-Stunden-Tag der Umstellung auf Winterzeit; bei allen anderen Stunden null"
          enum:
            - A
            - B
          example: null
        quantity:
          type: integer
          description: Gehandelte Menge in ganzen MWh
          example: 8
        price:
          type: number
          description: Preis des Geschäfts in EUR/MWh
          example: 5.20
        amount:
          type: number
          description: Betrag des Geschäfts in EUR (Menge × Preis)
          example: 41.60
        status:
          type: string
          description: "`awaiting_payment` bis zum festgestellten Geldeingang, `settled`, sobald OES HC und HKN auf die Konten des Käufers übertragen hat"
          enum:
            - awaiting_payment
            - settled
          example: awaiting_payment
        concluded_at:
          type: string
          format: date-time
          description: ISO-8601-Zeitstempel des Abschlusses
          example: "2026-04-23T10:15:00Z"
      required:
        - id
        - listing_id
        - counter_offer_id
        - side
        - delivery_date
        - hour
        - hour_suffix
        - quantity
        - price
        - amount
        - status
        - concluded_at
    Collateral:
      type: object
      description: "Das Sicherheitenkonto des Teilnehmers. Das Limit wirkt sofort, eine Nachschussfrist gibt es nicht."
      properties:
        collateral_posted:
          type: number
          description: "Hinterlegte Sicherheit in EUR: Barsicherheit und Bankbürgschaft auf erstes Anfordern"
          example: 12000.00
        collateral_required:
          type: number
          description: "Aktueller Sicherheitenbedarf in EUR, mindestens die Mindestsicherheit von 10.000 EUR je Teilnehmer. Beim Verkäufer zählen Sanktionsposition, Nachweisposition, Haltebetrag und Zahlungsposition, beim Käufer offene Gebote zum Limitpreis und Geschäfte zum Abschlusspreis bis zum festgestellten Geldeingang; wer beide Rollen ausübt, besichert beide Seiten. Die API rechnet ihn mit jedem Gebot, Zuschlag und Abschluss, mit der Fixierung von P_ref(h) um 15:00 Uhr an D−1, mit jedem Eingang abrechnungsrelevanter Messwerte und mit jedem HKN-Eingang neu."
          example: 10000.00
        collateral_free:
          type: number
          description: "Freies Limit in EUR: collateral_posted − collateral_required. Gebote und Orders, die den Bedarf erhöhen, prüft die API dagegen und weist sie zurück, wenn es nicht reicht. Käufe zur Glattstellung bleiben möglich, soweit Kaufpreis × Menge das freie Limit zuzüglich der freiwerdenden Deckungsposition der Stunde nicht übersteigt, darüber nur gegen Vorauszahlung. Ist der Marktzugang gesperrt, ist eine Glattstellung nur mit Zustimmung von OES möglich."
          example: 2000.00
        as_of:
          type: string
          format: date-time
          description: ISO-8601-Zeitstempel dieser Momentaufnahme
          example: "2026-03-20T09:05:00Z"
      required:
        - collateral_posted
        - collateral_required
        - collateral_free
        - as_of
    SettlementRun:
      type: object
      description: "Ein Abrechnungstag: Alle Dokumente, die OES an diesem Kalendertag für den Teilnehmer abrechnet, saldiert OES zu einem Nettosaldo. Die Zahlungskette hat drei Schritte, je an einem eigenen Bankarbeitstag: OES reicht den Saldo am Abrechnungstag bei der Bank ein, fällt er auf einen Nicht-Bankarbeitstag, am nächsten Bankarbeitstag. Einen Saldo zu Lasten des Teilnehmers zieht OES am Bankarbeitstag nach der Einreichung per SEPA-Lastschrift ein, einen Saldo zu seinen Gunsten überweist OES am Bankarbeitstag danach. Fällt ein Schritt auf einen Nicht-Bankarbeitstag, rücken er und alle folgenden Schritte auf die nächsten Bankarbeitstage (Beispiel: Sanktionsrechnung Sa 02.05., Einreichung Mo 04.05., Lastschrift Di 05.05.). Den Kaufpreis eines Aftermarket-Geschäfts überweist OES dem Verkäufer erst am Bankarbeitstag nach dem festgestellten Geldeingang (TD+6). Jede Einzelforderung bleibt neben der Saldierung bestehen."
      properties:
        id:
          type: string
          description: Eindeutige Kennung des Abrechnungstags
          example: run_b7c8d9e0
        type:
          type: string
          description: "`daily`: der Abrechnungstag, an dem OES alle Dokumente des Kalendertags saldiert"
          enum:
            - daily
          example: daily
        run_date:
          type: string
          format: date
          description: "Abrechnungstag: der Kalendertag, an dem OES die Dokumente abgerechnet hat"
          example: "2026-03-18"
        period_start:
          type: string
          format: date
          description: "Frühester Liefertag oder Handelstag, auf den sich eine Position dieses Abrechnungstags bezieht"
          example: "2026-03-18"
        period_end:
          type: string
          format: date
          description: "Spätester Liefertag oder Handelstag, auf den sich eine Position dieses Abrechnungstags bezieht"
          example: "2026-03-18"
        net_amount:
          type: number
          description: "Nettosaldo des Abrechnungstags in EUR aus Sicht des Teilnehmers: Einen positiven Betrag überweist OES, einen negativen zieht OES ein"
          example: -2550.00
        payment_date:
          type: string
          format: date
          description: "Tag, an dem die Bank die Zahlung des Saldos ausführt. OES reicht den Saldo am Abrechnungstag bei der Bank ein, an einem Nicht-Bankarbeitstag am nächsten Bankarbeitstag. Die Lastschrift folgt am Bankarbeitstag nach der Einreichung, die Überweisung am Bankarbeitstag danach; Einreichung, Lastschrift und Überweisung brauchen je einen eigenen Bankarbeitstag, und die Kette verschiebt sich als Ganzes (Beispiel: Sanktionsrechnung Sa 02.05., Einreichung Mo 04.05., Lastschrift Di 05.05.). Den Kaufpreis eines Aftermarket-Geschäfts überweist OES dem Verkäufer erst am Bankarbeitstag nach dem festgestellten Geldeingang (TD+6)."
          example: "2026-03-19"
      required:
        - id
        - type
        - run_date
        - period_start
        - period_end
        - net_amount
        - payment_date
    SettlementRunList:
      type: object
      properties:
        runs:
          type: array
          description: Liste der Abrechnungstage
          items:
            $ref: "#/components/schemas/SettlementRun"
        pagination:
          $ref: "#/components/schemas/Pagination"
      required:
        - runs
        - pagination
    SettlementItem:
      type: object
      description: Eine Position eines Abrechnungstags
      properties:
        id:
          type: string
          description: Eindeutige Kennung der Position
          example: itm_f1g2h3i4
        run_id:
          type: string
          description: Der Abrechnungstag, zu dem die Position gehört
          example: run_b7c8d9e0
        item_type:
          type: string
          description: "`grey_share` (Graustromanteil eines Day-ahead- oder Intraday-Geschäfts: P_grey × Menge je Viertelstunde), `certificate_instalment` (Grünstromprämie eines Day-ahead- oder Intraday-Geschäfts: P_QHC × Menge je Viertelstunde, sowie der Kaufpreis eines Geschäfts im Granular Matching zum Abschlusspreis; Graustromanteil und Grünstromprämie ergeben zusammen den Kaufpreis, OES rechnet beide mit dem Geschäft ab), `cash_compensation` (Sanktion des Verkäufers für eine Fehlmenge oder eine HKN-Fehlmenge: 2 × P_ref(h) × sanktionierte Menge, bei einer HKN-Fehlmenge mindestens 2 × P_GO je MWh; in der Sanktionsrechnung am 2. des übernächsten Monats), `compensation_credit` (Entschädigung des gekürzten Käufers: sein Anteil an der Sanktion der Stunde nach seiner Prämienbasis; mit der Abschlussrechnung am 10. des übernächsten Monats), `aftermarket_settlement` (Kaufpreis eines Geschäfts auf dem Granular Aftermarket)"
          enum:
            - grey_share
            - certificate_instalment
            - cash_compensation
            - compensation_credit
            - aftermarket_settlement
          example: grey_share
        direction:
          type: string
          description: Zahlungsrichtung aus Sicht des Teilnehmers
          enum:
            - debit
            - credit
          example: debit
        delivery_date:
          type: string
          format: date
          description: Liefertag, auf den sich die Position bezieht (YYYY-MM-DD)
          example: "2026-03-18"
        hour:
          type: integer
          nullable: true
          minimum: 1
          maximum: 24
          description: Stunde, auf die sich die Position bezieht (1–24 wie bei EPEX); null bei Positionen, die über einen Tag aggregiert sind
          example: 14
        hour_suffix:
          type: string
          nullable: true
          description: "`A` (noch MESZ) oder `B` (schon MEZ), wenn sich die Position auf die doppelte Stunde 3 am 25-Stunden-Tag der Umstellung auf Winterzeit bezieht; sonst null"
          enum:
            - A
            - B
          example: null
        quantity:
          type: number
          description: Menge in MWh, die die Position abrechnet (3 Nachkommastellen)
          example: 30.000
        unit_price:
          type: number
          description: Einzelpreis in EUR/MWh
          example: 80.00
        amount:
          type: number
          description: Betrag der Position in EUR (Menge × Einzelpreis)
          example: 2400.00
      required:
        - id
        - run_id
        - item_type
        - direction
        - delivery_date
        - hour
        - hour_suffix
        - quantity
        - unit_price
        - amount
    SettlementItemList:
      type: object
      properties:
        items:
          type: array
          description: Liste der Abrechnungspositionen
          items:
            $ref: "#/components/schemas/SettlementItem"
        pagination:
          $ref: "#/components/schemas/Pagination"
      required:
        - items
        - pagination
  responses:
    NotFound:
      description: Die Ressource existiert nicht, oder der Aufrufer hat keinen Zugriff
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://api.otark.com/errors/order_not_found
            title: Order nicht gefunden
            status: 404
            instance: /v1/orders/ord_g7h8i9j0
    BadRequest:
      description: Ungültige Anfrage — Validierungsfehler oder Verstoß gegen eine Geschäftsregel
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://api.otark.com/errors/validation
            title: Validierung fehlgeschlagen
            status: 400
            instance: /v1/orders
            errors:
              - field: quantity
                code: invalid_type
                message: Expected number, received string
    Unauthorized:
      description: Fehlender oder ungültiger API-Schlüssel
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://api.otark.com/errors/invalid_api_key
            title: Ungültiger API-Schlüssel
            status: 401
    Forbidden:
      description: Dem API-Schlüssel fehlen die erforderlichen Scopes
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://api.otark.com/errors/insufficient_scopes
            title: Unzureichende Scopes des API-Schlüssels
            status: 403
            detail: "Missing scope: trading:write. Please create a new API key with the required scopes."
    Conflict:
      description: Zustandskonflikt — der Vorgang lässt sich im aktuellen Zustand nicht ausführen
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://api.otark.com/errors/gate_closed
            title: Gate Closure überschritten
            status: 409
            detail: The day-ahead gate for delivery day 2026-03-18 closed at 10:30 Europe/Berlin. Bids can no longer be changed or withdrawn.
    RateLimited:
      description: Ratenbegrenzung überschritten
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://api.otark.com/errors/rate_limited
            title: Ratenbegrenzung erreicht
            status: 429
paths:
  /v1/prices/{delivery_date}:
    get:
      operationId: getDayPrices
      summary: Preise eines Liefertags abrufen
      description: "Das Preisblatt eines Liefertags abrufen: je Stunde den Green-SPOT-Clearingpreis `p_bundle` und den Graustrompreis `p_grey` (Day-ahead der EPEX SPOT DE/LU), beide mit der geräumten Menge je Viertelstunde auf die Stunde gewichtet, den Spread und den Zertifikatpreis `p_hc`.\n\n`p_hc` ist das mit der geräumten Menge gewichtete Mittel der vier Viertelstundenpreise P_QHC dieser Stunde. Einen Preisboden gibt es weder je Viertelstunde noch je Stunde, beide Preise können negativ sein. Jede Stunde führt ihre vier Viertelstunden in `quarter_hours` mit, je mit `p_bundle`, `p_grey`, `spread`, `p_qhc` und der geräumten Menge `q_cleared`, so dass sich `p_hc` nachrechnen lässt. Für eine Stunde ohne geräumte Menge sind `p_hc` und `p_hc_source` null.\n\nAus denselben Werten ergibt sich der Referenzpreis der Sanktion: P_ref(h) ist der höhere Wert aus `p_hc` und dem höchsten `p_qhc` einer Viertelstunde mit `q_cleared` > 0, mindestens null; für eine Stunde ohne geräumte Menge ist P_ref(h) = 0. Er steht mit der zweiten Veröffentlichung fest, und kein späterer Abschluss bewegt ihn.\n\nVeröffentlicht wird an D−1: `p_bundle` und `q_cleared` mit der ersten Veröffentlichung um 11:00 Uhr, `p_grey`, `spread`, `p_qhc` und `p_hc` mit der zweiten um 15:00 Uhr Europe/Berlin. Liegt das EPEX-Ergebnis verspätet vor, folgt die zweite Veröffentlichung spätestens eine Stunde danach; bleibt es bis 20:00 Uhr aus, bildet die Otark GmbH den Graustrompreis aus dem Ersatz-Spread und veröffentlicht um 20:00 Uhr. Noch nicht veröffentlichte Felder sind null. Einmal veröffentlicht, stehen die Preise für den gesamten Lebenszyklus des Liefertags fest, auch bei einer nachträglichen Korrektur des EPEX-Ergebnisses. Abrechnung und Sanktion beziehen sich auf die zweite Veröffentlichung.\n\nErforderlicher Scope: `trading:read`"
      tags:
        - Prices
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - trading:read
      parameters:
        - name: delivery_date
          in: path
          required: true
          description: Liefertag (YYYY-MM-DD)
          schema:
            type: string
            format: date
            example: "2026-03-18"
      responses:
        "200":
          description: Stundenpreise des Liefertags
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DayPrices"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /v1/bids:
    get:
      operationId: listBids
      summary: Gebote auflisten
      description: "Die Day-ahead-Gebote des Aufrufers auflisten. Filterbar nach Liefertag, Status und Richtung.\n\nErforderlicher Scope: `trading:read`"
      tags:
        - Day-ahead bids
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - trading:read
      parameters:
        - $ref: "#/components/parameters/DeliveryDateParam"
        - name: status
          in: query
          description: Nach dem Status des Gebots filtern
          schema:
            type: string
            enum:
              - open
              - binding
              - withdrawn
        - name: direction
          in: query
          description: Nach der Richtung des Gebots filtern
          schema:
            type: string
            enum:
              - buy
              - sell
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/AfterParam"
      responses:
        "200":
          description: Liste der Gebote
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BidList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
    post:
      operationId: createBid
      summary: Gebot abgeben
      description: "Ein Day-ahead-Gebot für eine Viertelstunde eines Liefertags abgeben, auf beiden Marktseiten je Portfolio. Mehrere Gebote desselben Teilnehmers für dieselbe Viertelstunde fasst die Auktion zu einer stückweise linearen Gebotskurve zusammen. Blockgebote und Alles-oder-nichts-Bedingungen gibt es nicht, Teilzuschläge sind stets zulässig.\n\nMenge in Schritten von 0,1 MW je Viertelstunde (0,025 MWh), mindestens 0,1 MW; Preisschritt 0,01 EUR/MWh, Preisgrenzen −500 bis 4.000 EUR/MWh. Gebote außerhalb weist die API mit einem Validierungsfehler zurück. Bieten darf nur, wer zugelassen ist, Sicherheit hinterlegt hat, ein gültiges SEPA-Firmenlastschriftmandat führt und nicht gesperrt ist. Jedes Gebot bindet Sicherheit: Ein Gebot, das den Sicherheitenbedarf erhöht, prüft die API gegen das freie Limit und weist es zurück, wenn es nicht reicht.\n\nEin Verkaufsgebot verlangt eine aktive, nicht gesperrte Anlage im Portfolio; aus einem erworbenen Anspruch lässt sich im Day-ahead nicht verkaufen. Aus Erzeugung darf ein Verkäufer je Portfolio und Viertelstunde höchstens die Nettonennleistung seiner aktiven Anlagen laut MaStR × 0,25 h verkaufen, offene Verkaufsgebote, Zuschläge und Intraday-Verkäufe aus Erzeugung zusammengerechnet; ein Verkauf aus Bestand zählt nicht mit. Ein Gebot darüber weist die API zurück.\n\nGebote lassen sich bis zur Gate Closure um 10:30 Uhr Europe/Berlin an D−1 ändern und zurückziehen; mit der Gate Closure werden sie unwiderruflich bindend.\n\nErforderlicher Scope: `trading:write`"
      tags:
        - Day-ahead bids
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - trading:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BidCreate"
      responses:
        "200":
          description: Angelegtes Gebot
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Bid"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/Conflict"
  /v1/bids/{bid_id}:
    get:
      operationId: getBid
      summary: Gebot abrufen
      description: "Ein einzelnes Gebot über seine Kennung abrufen.\n\nErforderlicher Scope: `trading:read`"
      tags:
        - Day-ahead bids
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - trading:read
      parameters:
        - name: bid_id
          in: path
          required: true
          description: Kennung des Gebots
          schema:
            type: string
            example: bid_a1b2c3d4
      responses:
        "200":
          description: Angaben zum Gebot
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Bid"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
    put:
      operationId: updateBid
      summary: Gebot ändern
      description: "Menge oder Preislimit eines offenen Gebots ändern. Möglich bis zur Gate Closure um 10:30 Uhr Europe/Berlin an D−1 — danach ist das Gebot unwiderruflich bindend, und die Anfrage wird mit einem Zustandskonflikt zurückgewiesen. Die API prüft das geänderte Gebot wie ein neues: Grenzen, freies Limit und bei Verkaufsgeboten Anlage und Mengenobergrenze.\n\nErforderlicher Scope: `trading:write`"
      tags:
        - Day-ahead bids
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - trading:write
      parameters:
        - name: bid_id
          in: path
          required: true
          description: Kennung des Gebots
          schema:
            type: string
            example: bid_a1b2c3d4
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BidUpdate"
      responses:
        "200":
          description: Geändertes Gebot
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Bid"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
    delete:
      operationId: withdrawBid
      summary: Gebot zurückziehen
      description: "Ein offenes Gebot zurückziehen. Möglich bis zur Gate Closure um 10:30 Uhr Europe/Berlin an D−1 — danach ist das Gebot unwiderruflich bindend, und die Anfrage wird mit einem Zustandskonflikt zurückgewiesen. Die Antwort liefert das Gebot mit dem Status `withdrawn`.\n\nErforderlicher Scope: `trading:write`"
      tags:
        - Day-ahead bids
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - trading:write
      parameters:
        - name: bid_id
          in: path
          required: true
          description: Kennung des Gebots
          schema:
            type: string
            example: bid_a1b2c3d4
      responses:
        "200":
          description: Zurückgezogenes Gebot
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Bid"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /v1/awards:
    get:
      operationId: listAwards
      summary: Zuschläge auflisten
      description: "Die Day-ahead-Zuschläge des Aufrufers je Liefertag und Stunde auflisten. `quantity` ist Q_award(h), die Summe der vier Viertelstundenzuschläge, `price` der Stunden-Clearingpreis p_bundle(h). Das Tupel jedes Zuschlags ist (Liefertag, Viertelstunde): Lieferverpflichtung und Kaufpreis entstehen je Viertelstunde und stehen im Feld `quarter_hours` mit Menge und Clearingpreis.\n\nDie Otark GmbH teilt jedem Teilnehmer seine Zuschläge einzeln mit der ersten Veröffentlichung um 11:00 Uhr Europe/Berlin an D−1 mit; teilnehmerbezogene Ergebnisse veröffentlicht sie nie.\n\nErforderlicher Scope: `trading:read`"
      tags:
        - Awards
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - trading:read
      parameters:
        - $ref: "#/components/parameters/DeliveryDateParam"
        - $ref: "#/components/parameters/HourParam"
        - $ref: "#/components/parameters/HourSuffixParam"
        - name: direction
          in: query
          description: Nach der Seite des Zuschlags filtern
          schema:
            type: string
            enum:
              - buy
              - sell
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/AfterParam"
      responses:
        "200":
          description: Liste der Zuschläge
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AwardList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
  /v1/coverage:
    get:
      operationId: listCoverage
      summary: Positionen auflisten
      description: "Die Positionen des Aufrufers je Tupel (Liefertag, Stunde) auflisten: q_award, q_metered, q_bought, q_sold, die Short-Menge q_gap und die anbietbare Long-Menge free_position. Pos(h) = q_metered − (q_sold − q_bought); negativ heißt short, positiv long.\n\nGenettet wird je Teilnehmer über alle Portfolios, Anlagen, Technologien und die vier Viertelstunden derselben Stunde, nie über Stunden, Liefertage oder Teilnehmer hinweg. Als Ist-Wert zählen allein die abrechnungsrelevanten Messwerte des MSB (Q_metered); gemeldete oder vorläufige Werte gehen nie in die Rechnung ein, die mit jedem Dateneingang und jedem Geschäft neu läuft. Solange für eine Anlage keine Messwerte vorliegen und der Korrekturschluss am 20. des Folgemonats nicht erreicht ist, ist die Position der Stunde nicht bestimmbar und die Stunde im Granular Matching nicht handelbar. Liegen zum Korrekturschluss keine Messwerte vor, gilt Pos(h) als negative Nettoverkaufsmenge.\n\nZum Ende des GM-Fensters (`final_gate_at`) stellt OES die Fehlmenge F(h) fest: die dann verbleibende Short-Menge q_gap.\n\nErforderlicher Scope: `trading:read`"
      tags:
        - Coverage
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - trading:read
      parameters:
        - $ref: "#/components/parameters/DeliveryDateParam"
        - $ref: "#/components/parameters/HourParam"
        - $ref: "#/components/parameters/HourSuffixParam"
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/AfterParam"
      responses:
        "200":
          description: Liste der Positionen
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CoverageList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
  /v1/orders:
    get:
      operationId: listOrders
      summary: Orders auflisten
      description: "Die Orders des Aufrufers im Orderbuch des Granular Matching auflisten. Filterbar nach Liefertag, Stunde, Seite und Status.\n\nErforderlicher Scope: `trading:read`"
      tags:
        - Granular Matching
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - trading:read
      parameters:
        - $ref: "#/components/parameters/DeliveryDateParam"
        - $ref: "#/components/parameters/HourParam"
        - $ref: "#/components/parameters/HourSuffixParam"
        - name: side
          in: query
          description: Nach der Seite der Order filtern
          schema:
            type: string
            enum:
              - buy
              - sell
        - name: status
          in: query
          description: Nach dem Status der Order filtern
          schema:
            type: string
            enum:
              - open
              - filled
              - cancelled
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/AfterParam"
      responses:
        "200":
          description: Liste der Orders
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrderList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
    post:
      operationId: createOrder
      summary: Order aufgeben
      description: "Eine Limit-Order in das anonyme Orderbuch des Granular Matching (Phase 3) einstellen. Gehandelt werden Ansprüche auf HC je Tupel (Liefertag, Stunde), allein zur Glattstellung zwischen verkaufter und gemessener Erzeugung. Das Orderbuch eines Liefertags ist von D+1, 15:00 Uhr bis zum Ablauf des letzten Kalendertags des Folgemonats (24:00 Uhr Europe/Berlin) offen, an jedem Kalendertag; eine Störung des Marktbetriebs kann das Ende verschieben. Außerhalb dieses Fensters weist die API Orders mit einem Zustandskonflikt zurück. Menge in Schritten von 0,025 MWh, Preisschritt 0,01 EUR/MWh, Preisgrenzen 0,00 bis 1.000 EUR/MWh; Orders außerhalb weist die API mit einem Validierungsfehler zurück.\n\nKaufen darf nur, wer in der Stunde short ist (Pos(h) < 0), höchstens bis Pos(h) = 0; das letzte gekaufte Los darf die Position auf höchstens +0,025 MWh heben. Verkaufen darf nur, wer in der Stunde long ist (Pos(h) > 0), höchstens bis Pos(h) = 0. Offene Orders desselben Teilnehmers zählen auf die Grenze mit; die API prüft jede Order gegen q_gap und free_position der Position. Solange für eine Anlage keine Messwerte vorliegen und der Korrekturschluss nicht erreicht ist, ist die Stunde nicht handelbar; gemeldete oder vorläufige Werte tragen keine Order. Verkauft ein Käufer erworbene Ansprüche weiter, weist sein Nachweis die Menge als nicht grün aus.\n\nEine risikoerhöhende Order prüft die API gegen das freie Limit. Kauforders zur Glattstellung bleiben möglich, soweit Kaufpreis × Menge das freie Limit zuzüglich der freiwerdenden Deckungsposition der Stunde nicht übersteigt, darüber nur gegen Vorauszahlung.\n\nGematcht wird nach Preis-Zeit-Priorität; eine Teilausführung ist stets zulässig, der Rest bleibt im Orderbuch. Gegenpartei jedes Abschlusses ist OES. Ein Abschluss ist verbindlich: OES hebt ihn nur bei einem offensichtlichen technischen Fehler auf (Mistrade, Antrag bis 24:00 Uhr des Handelstags) und hebt Abschlüsse zwischen Konten verbundener Unternehmen und Scheingeschäfte wie einen Mistrade auf.\n\nErforderlicher Scope: `trading:write`"
      tags:
        - Granular Matching
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - trading:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OrderCreate"
      responses:
        "200":
          description: Angelegte Order — möglicherweise bereits teilweise oder vollständig gegen das Orderbuch ausgeführt
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/Conflict"
  /v1/orders/{order_id}:
    put:
      operationId: updateOrder
      summary: Order ändern
      description: "Menge oder Preislimit einer offenen Order ändern — wie das Löschen jederzeit bis zur Ausführung möglich. Der nicht ausgeführte Rest wird im Orderbuch ersetzt; bereits ausgeführte Geschäfte bleiben endgültig, und eine vollständig ausgeführte Order lässt sich nicht mehr ändern. Die API prüft die geänderte Order wie eine neue: Grenzen, freies Limit und die Position der Stunde.\n\nErforderlicher Scope: `trading:write`"
      tags:
        - Granular Matching
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - trading:write
      parameters:
        - name: order_id
          in: path
          required: true
          description: Kennung der Order
          schema:
            type: string
            example: ord_g7h8i9j0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OrderUpdate"
      responses:
        "200":
          description: Geänderte Order
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
    delete:
      operationId: deleteOrder
      summary: Order löschen
      description: "Eine offene Order löschen. Der nicht ausgeführte Rest verlässt das Orderbuch; bereits ausgeführte Geschäfte bleiben endgültig. Eine vollständig ausgeführte Order lässt sich nicht mehr löschen. Die Antwort liefert die Order mit dem Status `cancelled`.\n\nErforderlicher Scope: `trading:write`"
      tags:
        - Granular Matching
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - trading:write
      parameters:
        - name: order_id
          in: path
          required: true
          description: Kennung der Order
          schema:
            type: string
            example: ord_g7h8i9j0
      responses:
        "200":
          description: Gelöschte Order
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /v1/trades:
    get:
      operationId: listTrades
      summary: Geschäfte auflisten
      description: "Die ausgeführten Geschäfte des Aufrufers im Granular Matching auflisten. Der Markt sieht jedes Geschäft nur mit Preis und Menge, ohne die Beteiligten; dieser Endpunkt liefert die eigenen Geschäfte des Aufrufers samt ihrer Order-Referenz. Die Positionen rechnet die API nach jedem Geschäft neu.\n\nErforderlicher Scope: `trading:read`"
      tags:
        - Granular Matching
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - trading:read
      parameters:
        - $ref: "#/components/parameters/DeliveryDateParam"
        - $ref: "#/components/parameters/HourParam"
        - $ref: "#/components/parameters/HourSuffixParam"
        - name: side
          in: query
          description: Nach der Seite des Geschäfts filtern
          schema:
            type: string
            enum:
              - buy
              - sell
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/AfterParam"
      responses:
        "200":
          description: Liste der Geschäfte
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TradeList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
  /v1/listings:
    get:
      operationId: listListings
      summary: Inserate auflisten
      description: "Die Inserate auf dem Granular Aftermarket auflisten. Voreingestellt kommen alle offenen Inserate anonym zurück — Produkt, Menge und Preis, nie der Inserent. Mit `own=true` kommen allein die eigenen Inserate des Aufrufers, einschließlich der abgeschlossenen und zurückgezogenen.\n\nMit `include_counter_offers=true` trägt jedes Inserat ein Feld `counter_offers`: bei eigenen Inseraten die eingegangenen Gegenangebote, bei fremden nur die eigenen des Aufrufers.\n\nErforderlicher Scope: `trading:read`"
      tags:
        - Granular Aftermarket
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - trading:read
      parameters:
        - $ref: "#/components/parameters/DeliveryDateParam"
        - $ref: "#/components/parameters/HourParam"
        - $ref: "#/components/parameters/HourSuffixParam"
        - name: side
          in: query
          description: Nach der Seite des Inserats filtern
          schema:
            type: string
            enum:
              - buy
              - sell
        - name: own
          in: query
          description: Nur die eigenen Inserate des Aufrufers liefern (alle Status)
          schema:
            type: string
            enum:
              - "true"
              - "false"
            default: "false"
        - name: include_counter_offers
          in: query
          description: Ein Feld `counter_offers` je Inserat aufnehmen
          schema:
            type: string
            enum:
              - "true"
              - "false"
            default: "false"
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/AfterParam"
      responses:
        "200":
          description: Liste der Inserate
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListingList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
    post:
      operationId: createListing
      summary: Inserat anlegen
      description: "Ein Inserat auf dem Granular Aftermarket (Phase 4) veröffentlichen. Ein Inserat nennt Richtung, Liefertag und Stunde, eine Menge in ganzen MWh (1 MWh = 1 HKN) und einen Preis in EUR/MWh. Die Preisangabe ist Pflicht, mit einem Boden bei 0,00 EUR/MWh, ohne Obergrenze und in Schritten von 0,01 EUR/MWh. Mit `allow_partial` lässt der Inserent die unmittelbare Annahme von Teilmengen zu; ohne diese Option ist das Inserat nur als Ganzes annehmbar, und kleinere Mengen verlangen ein Gegenangebot.\n\nVerkaufen darf nur, wessen HKN bei OES liegen und dessen HC verfügbar sind. Vor der Zuteilung ist je Stunde höchstens die Long-Position anbietbar, min(ausgestellte HC der Stunde; max(0; Pos(h) ohne Aftermarket-Verkäufe)), nie ein HC, das einen gehandelten Anspruch deckt. Zugeteilte und auf dem Aftermarket erworbene HC sind als nicht mehr handelbar gekennzeichnet. Ab der Veröffentlichung blockiert OES die inserierten HC phasenübergreifend: Dieselbe Menge lässt sich nicht zweimal anbieten, das zuerst eingestellte Angebot gewinnt. Beim Abschluss prüft das System das freie Limit des Käufers; reicht es nicht, kommt das Geschäft nicht zustande.\n\nHandelbar sind die Liefertage von Monatsanfang M−10 bis Monatsende M−1, bezogen auf den aktuellen Tag. Ein Liefermonat ist damit ab dem ersten Tag des Folgemonats handelbar, sobald HC ausgestellt sind (frühestens am 21. des Folgemonats), und bis zum Board-Schluss 10 Monate nach Ende des Erzeugungsmonats; an diesem Tag erlischt jedes offene Inserat. Die zwei Monate bis zur gesetzlichen HKN-Übertragungsfrist brauchen die HKN für den Weg auf das Registerkonto des Käufers.\n\nErforderlicher Scope: `trading:write`"
      tags:
        - Granular Aftermarket
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - trading:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ListingCreate"
      responses:
        "200":
          description: Angelegtes Inserat
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Listing"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/Conflict"
  /v1/listings/{listing_id}:
    put:
      operationId: updateListing
      summary: Inserat ändern
      description: "Menge, Preis oder die Option zur Teilannahme eines eigenen Inserats ändern — wie das Löschen möglich, solange es nicht angenommen ist. Bei einem Verkaufsinserat prüft die API die geänderte Menge erneut, und die Blockierung der HC folgt der neuen Menge. Ein offenes Gegenangebot, das nicht mehr zum geänderten Inserat passt (etwa weil die neue Menge kleiner ist als die angebotene), weist die API automatisch zurück.\n\nErforderlicher Scope: `trading:write`"
      tags:
        - Granular Aftermarket
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - trading:write
      parameters:
        - name: listing_id
          in: path
          required: true
          description: Kennung des Inserats
          schema:
            type: string
            example: lst_p5q6r7s8
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ListingUpdate"
      responses:
        "200":
          description: Geändertes Inserat
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Listing"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
    delete:
      operationId: deleteListing
      summary: Inserat löschen
      description: "Ein eigenes Inserat löschen. Möglich, solange es nicht angenommen ist; die Blockierung der inserierten HC endet. Offene Gegenangebote auf das Inserat weist die API automatisch zurück. Die Antwort liefert das Inserat mit dem Status `withdrawn`.\n\nErforderlicher Scope: `trading:write`"
      tags:
        - Granular Aftermarket
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - trading:write
      parameters:
        - name: listing_id
          in: path
          required: true
          description: Kennung des Inserats
          schema:
            type: string
            example: lst_p5q6r7s8
      responses:
        "200":
          description: Zurückgezogenes Inserat
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Listing"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /v1/listings/{listing_id}/accept:
    post:
      operationId: acceptListing
      summary: Inserat annehmen
      description: "Ein offenes Inserat zu seinem Preis annehmen. Ohne Mengenangabe im Body umfasst die Annahme die volle offene Menge; eine Teilmenge in ganzen MWh ist nur zulässig, wenn der Inserent `allow_partial` gesetzt hat — der Rest bleibt inseriert.\n\nBeim Abschluss prüft das System das freie Limit des Käufers. Reicht es nicht, kommt das Geschäft nicht zustande. Kommt es zustande, belegt der Kaufpreis das Limit des Käufers bis zum Ende der Abwicklung. Abgewickelt wird Zug um Zug: OES rechnet das Geschäft an TD+1 ab und zieht den Kaufpreis an TD+2 per Lastschrift ein. Nach dem festgestellten Geldeingang (TD+5) überträgt OES HC und HKN auf das GCR-Konto und das benannte HKNR-Konto des Käufers und überweist den Kaufpreis am Bankarbeitstag danach (TD+6) an den Verkäufer. Scheitert der Einzug, entfällt das Geschäft mit Ablauf der Frist nach Rückgabe der Lastschrift ohne weitere Erklärung: OES hebt die Blockierung auf, der Verkäufer kann die HC erneut anbieten, und der Käufer trägt Gebotssperre, Bankgebühren und Bearbeitungsentgelt. Ein Zukauf auf dem Aftermarket zählt im Nachweis des Käufers als datierter Nachtrag und ändert keine Sanktion.\n\nErforderlicher Scope: `trading:write`"
      tags:
        - Granular Aftermarket
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - trading:write
      parameters:
        - name: listing_id
          in: path
          required: true
          description: Kennung des Inserats
          schema:
            type: string
            example: lst_p5q6r7s8
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ListingAccept"
      responses:
        "200":
          description: Zustande gekommenes Geschäft
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BoardTrade"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /v1/listings/{listing_id}/counter-offers:
    post:
      operationId: createCounterOffer
      summary: Gegenangebot abgeben
      description: "Ein Gegenangebot auf ein Inserat abgeben — ein anderer Preis, eine kleinere Menge als die offene Menge des Inserats oder beides. Ein Gegenangebot bindet den Anbietenden 72 Stunden; die Frist ist systemseitig fest und nicht individuell einstellbar. Danach erlischt es von selbst.\n\nMehrere Gegenangebote auf dasselbe Inserat sind gleichzeitig zulässig. Ein Gegenangebot, das nicht mehr zum Inserat passt — etwa weil dessen Restmenge kleiner geworden ist als die angebotene —, wird automatisch zurückgewiesen. Beim Abschluss prüft das System das freie Limit des Käufers; reicht es nicht, kommt das Geschäft nicht zustande.\n\nErforderlicher Scope: `trading:write`"
      tags:
        - Granular Aftermarket
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - trading:write
      parameters:
        - name: listing_id
          in: path
          required: true
          description: Kennung des Inserats
          schema:
            type: string
            example: lst_p5q6r7s8
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CounterOfferCreate"
      responses:
        "200":
          description: Angelegtes Gegenangebot
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CounterOffer"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /v1/counter-offers/{counter_offer_id}/accept:
    post:
      operationId: acceptCounterOffer
      summary: Gegenangebot annehmen
      description: "Ein Gegenangebot auf ein eigenes Inserat annehmen, innerhalb seiner Bindefrist. Das Geschäft kommt über Menge und Preis des Gegenangebots zustande; der Rest des Inserats bleibt zum ursprünglichen Preis stehen. Abgewickelt wird wie jedes Aftermarket-Geschäft: Zug um Zug, Lastschrift an TD+2, Übertragung von HC und HKN und Überweisung an den Verkäufer erst nach dem festgestellten Geldeingang.\n\nErforderlicher Scope: `trading:write`"
      tags:
        - Granular Aftermarket
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - trading:write
      parameters:
        - name: counter_offer_id
          in: path
          required: true
          description: Kennung des Gegenangebots
          schema:
            type: string
            example: cof_t9u0v1w2
      responses:
        "200":
          description: Zustande gekommenes Geschäft
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BoardTrade"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /v1/collateral:
    get:
      operationId: getCollateral
      summary: Sicherheitenkonto abrufen
      description: "Das Sicherheitenkonto lesen: hinterlegte Sicherheit (Barsicherheit oder Bankbürgschaft auf erstes Anfordern), den aktuellen Sicherheitenbedarf und das freie Limit collateral_free = collateral_posted − collateral_required.\n\nDas Limit wirkt sofort, eine Nachschussfrist und ein Mahnverfahren gibt es nicht: Gebote und Orders, die den Bedarf erhöhen, prüft die API gegen das freie Limit und weist sie zurück, wenn es nicht reicht. Käufe zur Glattstellung bleiben möglich, soweit Kaufpreis × Menge das freie Limit zuzüglich der freiwerdenden Deckungsposition der Stunde nicht übersteigt, darüber nur gegen Vorauszahlung; ist der Marktzugang gesperrt, nur mit Zustimmung von OES. Zugeschlagene Mengen, Fehlmengen und Haltebetrag des Verkäufers bemisst OES ab der Fixierung um 15:00 Uhr an D−1 mit 2 × P_ref(h), davor mit 2 × P_HC,peak.\n\nFrei wird eine Sicherheit erst, wenn die besicherte Verpflichtung erloschen ist: bei einer Zahlung mit dem festgestellten Geldeingang (bei einer Lastschrift mit Ablauf der Rückgabefrist von 3 Bankarbeitstagen nach Ausführung, bei einer Vorauszahlung per Echtzeitüberweisung mit dem Eingang), bei einer sanktionsbewehrten Pflicht mit der Glattstellung oder dem HKN-Eingang.\n\nErforderlicher Scope: `settlement:read`"
      tags:
        - Collateral
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - settlement:read
      responses:
        "200":
          description: Momentaufnahme des Sicherheitenkontos
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Collateral"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
  /v1/settlement-runs:
    get:
      operationId: listSettlementRuns
      summary: Abrechnungstage auflisten
      description: "Die Abrechnungstage des Aufrufers auflisten. Je Teilnehmer und Abrechnungstag saldiert OES alle an diesem Tag abgerechneten Dokumente zu einem Nettosaldo. Day-ahead-Geschäfte des Liefertags D rechnet OES an D vor 12:00 Uhr ab, Intraday-Geschäfte des Liefertags D an D+1 vor 12:00 Uhr, Geschäfte im Granular Matching und auf dem Granular Aftermarket vom Handelstag TD an TD+1 vor 12:00 Uhr. Gesondert rechnet OES die Sanktionsrechnungen am 2. des übernächsten Monats nach dem Liefermonat ab, die Abschlussrechnung mit den Entschädigungen am 10. des übernächsten Monats und das Dezember-Clearing mit dem Dezember-Abschluss am 10. Februar; auch sie gehen in den Saldo ihres Abrechnungstags ein.\n\nDie Zahlungskette hat drei Schritte, je an einem eigenen Bankarbeitstag: OES reicht den Saldo am Abrechnungstag bei der Bank ein, fällt er auf einen Nicht-Bankarbeitstag, am nächsten Bankarbeitstag. Einen Saldo zu Lasten des Teilnehmers zieht OES am Bankarbeitstag nach der Einreichung per SEPA-Lastschrift ein, einen Saldo zu seinen Gunsten überweist OES am Bankarbeitstag danach. Fällt ein Schritt auf einen Nicht-Bankarbeitstag, rücken er und alle folgenden Schritte auf die nächsten Bankarbeitstage (Beispiel: Sanktionsrechnung Sa 02.05., Einreichung Mo 04.05., Lastschrift Di 05.05.). Die Abrechnung selbst läuft an jedem Kalendertag. Den Kaufpreis eines Aftermarket-Geschäfts überweist OES dem Verkäufer erst am Bankarbeitstag nach dem festgestellten Geldeingang (TD+6). Jede Einzelforderung bleibt neben der Saldierung bestehen, fällig und besichert.\n\nErforderlicher Scope: `settlement:read`"
      tags:
        - Settlement
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - settlement:read
      parameters:
        - name: type
          in: query
          description: Nach der Art filtern
          schema:
            type: string
            enum:
              - daily
        - name: run_date_from
          in: query
          description: "Filter: Abrechnungstag >= diesem Wert (YYYY-MM-DD)"
          schema:
            type: string
            format: date
            example: "2026-03-01"
        - name: run_date_to
          in: query
          description: "Filter: Abrechnungstag <= diesem Wert (YYYY-MM-DD)"
          schema:
            type: string
            format: date
            example: "2026-03-31"
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/AfterParam"
      responses:
        "200":
          description: Liste der Abrechnungstage
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SettlementRunList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
  /v1/settlement-runs/{run_id}/items:
    get:
      operationId: listSettlementItems
      summary: Abrechnungspositionen auflisten
      description: "Die Positionen eines Abrechnungstags auflisten. Jede Position nennt ihre Art, ihre Richtung, den Liefertag, auf den sie sich bezieht, Menge, Einzelpreis und Betrag; die Summe aller Positionen ist der Nettosaldo des Abrechnungstags. Ein Day-ahead- oder Intraday-Geschäft erscheint mit zwei Positionen, Graustromanteil und Grünstromprämie, die zusammen den Kaufpreis ergeben und umsatzsteuerlich getrennt sind.\n\nErforderlicher Scope: `settlement:read`"
      tags:
        - Settlement
      security:
        - ApiKeyAuth: []
      x-required-scopes:
        - settlement:read
      parameters:
        - name: run_id
          in: path
          required: true
          description: Kennung des Abrechnungstags
          schema:
            type: string
            example: run_b7c8d9e0
        - name: item_type
          in: query
          description: Nach der Art der Position filtern
          schema:
            type: string
            enum:
              - grey_share
              - certificate_instalment
              - cash_compensation
              - compensation_credit
              - aftermarket_settlement
        - $ref: "#/components/parameters/LimitParam"
        - $ref: "#/components/parameters/AfterParam"
      responses:
        "200":
          description: Liste der Abrechnungspositionen
          headers:
            x-ratelimit-limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
            x-ratelimit-remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            x-ratelimit-reset:
              $ref: "#/components/headers/X-RateLimit-Reset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SettlementItemList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
