Empire uses the following Auction Statuses that are available for the Participants.

💡 This is the "happy path" of Auction process steps and they always happens in the specified order. Thus the terms "before", "after", "between" etc. referring to statuses can and will be used throughout the documentation (e.g "bidding is possible between the BIDDING_OPEN and the BIDDING_CLOSE statuses").

• the Schedule List / Results List column describes if the Auction in a given state is visible under either in the Auction Schedule List or the Auction Results List functions as it depends on the status
• Auction Details are always available in any status describing the ATC, OC and so on
• the Auction Results is available for logged-in Participants "one step before" it is getting released for the general public

Empire validates Participant bids based on BritNed's Access Rules. Invalid bids will be rejected, when submitted either via the UI or the API (with the appropriate error code). The bid validation rules can be found in the tables below.

Capacity & Price Validation Rules

The Auction Schedule is used to list all the Auctions that are between PRELIMINARY_SPEC_PUBLISHED and FINAL_RESULTS_PUBLISHED statuses. BritNed schedules Long Term auctions based on their internal schedule. Day Ahead and Intraday auctions are recurring Auctions that are managed automatically.

Day Ahead and Intraday Auctions get published every single day based on the following schedule automatically:

Please note that due to the nature of the Auction Schedule the Day Ahead and Intraday auctions will only "appear" after they are stepped into PRELIMINARY_SPEC_PUBLISHED status (as per image above), and once the Auction moves to the FINAL_RESULTS_PUBLISHED status it will "disappear" from the Auction Schedule and will turn up in the Auction Results List.

To view the Auction Schedule List as a Participant use the getAuctions endpoint. The endpoint specification does not outline these as it is for general use so please follow the below additional steps:

• as the screen is paginated, specify the limit and the offset parameter
• specify the sortBy parameter, on the GUI the default is BIDDING_PERIOD_START_DESC
• freely specify the borderDirection or timescales or productTypes depending on what type and list of Auctions you are wanting to filter
• if you wish to add a delivery date from/to parameter to your query, please bear in mind that Empire uses an overlap validation when filtering for such date ranges. This means that if and auction's delivery period start and end dates overlap even for a single day with your specified start and end delivery date range, the auction will be returned by the endpoint.

The Auction Results function list all Auctions that reached the FINAL_RESULTS_PUBLISHED status. After an Auction moves from Provisional Results Published to Final Results Published it "disappears" from the Auction Schedule List it will "appear" on the Auction Results list

To access the Auction Results List as a Participant, use the getPublicAllocatedAuctions endpoint.

❗ Please note that with the coming 1.1.0 release of the API there will be new endpoints for the Auction Results available only for logged-in Participants.

The endpoint specification does not outline these as it is for general use so please follow the below additional steps:

• as the screen is paginated, specify the limit and the offset parameter
• specify the sortBy parameter, on the GUI the default is BIDDING_PERIOD_START_DESC
• freely specify the borderDirection or timescales or productTypes depending on what type and list of Auctions you are wanting to filter
• if you wish to add a delivery date from/to parameter to your query, please bear in mind that Empire uses an overlap validation when filtering for such date ranges. This means that if and auction's delivery period start and end dates overlap even for a single day with your specified start and end delivery date range, the auction will be returned by the endpoint.

There are timescale-specific Auction Details endpoints available that are designed to return the Auction Details - basically the "configuration" of an given Auction - for the Long Term, Day Ahead and Intraday timescales.

Depending on the timescale either use the getDayAheadAuction or the getIntraDayAuction endpoints.

These endpoints will return the Auction Details including the Available Transfer Capacity (ATC) per MTU, Offered Capacity (OC) per MTU alongside with a breakdown of how much is UIoSI capacity (in case of the Day Ahead auction).

For more information please visit the specific endpoint detail in the 🧭 API Navigator.

In case these endpoints below are called when an Auction is between PRELIMINARY_SPEC_PUBLISHED and BIDDING_CLOSED statuses, Empire will return a 409 Conflict HTTP status with the AUCTION_RESULTS_NOT_AVAILABLE error code, as the Auction's results are only available after:

• PROVISIONAL_RESULTS_PUBLISHED status for logged-in users with the VIEW_PUBLISHED_AUCTIONS permission (effectively all Participant Users)
• FINAL_RESULTS_PUBLISHED status for anonymous (not logged in) Users

For both Day Ahead and Intraday auctions two different endpoints need to be called in order to fetch different dataset.

The generic getDayAheadOrIntraDayAuctionResults endpoint which shows the generic non participant specific results of the auction - it will return for each MTU the:

• Total Requested Capacity in requestedCapacity
• Total Allocated Capacity in allocatedTrs
• Marginal Price in marginalPrice
• Number of Participants that placed bids in participantCount
• Total bids placed in bidCount
• Number of Participants that were awarded bids in successfulParticipantCount

The endpoint further returns the participantId of every successful Participant that was awarded Allocated Capacity from the Auction.

The getDayAheadOrIntraDayAuctionParticipantResults endpoint returns the detailed Allocated Capacity (Transmission Rights) for the Participant for each MTU. Currently this will return:

• for the specific Participant the allocatedTrs per MTU.

❗ Please note that prior to the 1.1.0 release of the API being live the requestedCapacity will always be NULL even when the Participant's own results are requested. With the release above this endpoint will also be extended to include the marginalPrice for each MTU

The getAuctionAllocationResultsReport endpoint can be used to fetch Auction Results in a standard "ECAN Allocation Results Document v4.0" XML format.

The endpoint need to receive the Participant's own Participant ID in the X-Participant-Id request header along with the value of the idOrDisplayId parameter in the request path which need to contain either:

• an "Internal ID" / in UUIDv4 format, can be obtained from the browser URLs or the id field of an Auction object
• a "Display ID" / shown on the GUI, or can be obtained from the displayId field of an Auction object

The resulting XML file can be validated against the attached auction results schema definition.

Bidding for Long Term (LT) and Day Ahead / Intraday auctions (DA/ID) has separate endpoints. This is because whilst bidding for LT requires only a requested capacity and bid amount, for DA/ID this is broken down to an MTU level - requiring a different payload to be sent and validated.

You can use the submitLongTermAuctionBids endpoint to submit Long Term bids.

As the most simple payload goes, Long Term bids only require a price and a requested capacity to be sent for each bid item. For example the following payload would result in valid bids:

{
  "bids": [
    {
      "value": {
        "price": 1.0,
        "capacity": 5000
      }
    },
    {
      "value": {
        "price": 0.1,
        "capacity": 6000
      }
    }
  ]
}

The above creates 2 bids:

• one for 5 MW at the bid price of €1
• another for 6 MW at the bid price of €0.1

❗ Submitting a LT bid request for an auction will always overwrite any existing bids with the new payload!

• If you wish to change your existing bids, you can do so by resubmitting the same payload, with the values changed accordingly.
• If you wish to append more bids to the existing ones, ensure to include the existing bids in your request, as well as the new bids you would like to add

You need to use the submitDayAheadOrIntraDayAuctionBids endpoint to submit Day Ahead or Intraday bids.

DA / ID bids are grouped in so-called Bid Groups, encompassing a set of bid prices and requested capacities for the auction's MTUs. You can add an arbitrary number of Bid Groups, as long as the requested capacity and/or the bid price differs between them, for the same MTU.

The actual Bids in each Bid Group contains an mtu, price and capacity element, such that:

{
  "bidGroups": [
    {
      "bids": [
        {
          "mtu": "2023-10-05T14:00:00Z",
          "value": {
            "price": 0.5,
            "capacity": 5000
          }
        },
        {
          "mtu": "2023-10-05T15:00:00Z",
          "value": {
            "price": 0.5,
            "capacity": 5000
          }
        },
        {
          "mtu": "2023-10-05T16:00:00Z",
          "value": {
            "price": 0.5,
            "capacity": 5000
          }
        },
        {
          "mtu": "2023-10-05T17:00:00Z",
          "value": {
            "price": 0.5,
            "capacity": 5000
          }
        }
      ]
    },
    {
      "bids": [
        {
          "mtu": "2023-10-05T14:00:00Z",
          "value": {
            "price": 1,
            "capacity": 6000
          }
        },
        {
          "mtu": "2023-10-05T15:00:00Z",
          "value": {
            "price": 1,
            "capacity": 6000
          }
        },
        {
          "mtu": "2023-10-05T16:00:00Z",
          "value": {
            "price": 1,
            "capacity": 6000
          }
        },
        {
          "mtu": "2023-10-05T18:00:00Z",
          "value": {
            "price": 1,
            "capacity": 6000
          }
        }
      ]
    }
  ]
}

The above payload creates 2 Bid Groups for the specified MTUs such that (in descending order of bid price):

Please observe that the two groups contain bids for different MTUs - the second one having the last bid for a later MTU than the first one's last bid.

❗ Submitting a DA / ID bid request for an auction will always overwrite any existing bids with the new payload!

• If you wish to change your existing bids, you can do so by first sending a GET request to the getDayAheadOrIntraDayAuctionBids endpoint, to obtain the Bid Group IDs, then include the bid group ID before each bid group, followed by the bids object as above.
• If you wish to append more bids to the existing ones, also ensure to include all existing bids using their Bid Group ID, followed by the new bid groups you wish to add.

You can use XML files to enter or edit your bids. The XML files should follow the attached bidding schema as Empire will validate the uploaded file against it. The XML file can be uploaded to Empire via the UI, using the Manual File Upload feature, or via the API as well.

When uploading the bidding files via the UI, please ensure to select the appropriate bidding timescale: LT or DA/ID.

To upload a bidding XML, first send a POST request to the uploadAttachment endpoint, with the XML in the file field of the body, as per the documentation. This will upload the XML file as an Attachment to Empire.

💡 Please bear in mind that no validation takes place at this point as Empire will not interpret the file, just store it. The file upload endpoint will return an id field in the response, please take a note of this.

Then, send a POST request to the uploadLongTermBids or uploadDayAheadOrIntraDayBids endpoints, with the attachmentId in the body being the id from the above request. This will apply and interpret the previously uploaded Attachment as the selected timescale's bidding file - triggering all validations and checks. Should the request return an error, it means that no bids have been entered and the errors should be fixed before they can be processed.

Example XML files can be found on BritNed's website, as well as examples to perform file uploads from Postman.

The below problems are the most common pitfalls of XML bids uploading.

The uploaded file does not conform to any of the given schemas

There is most likely a syntax or semantic issue with the XML file you submitted. Please check your XML's conformity to the above referred schemas. Pay special attention to ensuring that your organisation's EIC code is correct, as well as the timestamps and directions.

Auction is not open for bidding

The Auction's UUID specified in the request is for an auction that is past its Bidding Open status. Bids are only accepted for Auctions between their BIDDING_OPEN and BIDDING_CLOSED statuses.

Auction Not Found

When a 404 Not Found HTTP status is returned, it means that the Auction's UUID specified in the request is invalid. Please ensure that you use a valid auction UUID and also that you are sending the request to the appropriate environment, e.g TRAINING or PRODUCTION.

MTU list misaligned

There is an issue with the MTU list supplied in the bidding XML. Commonly this is a result of either wrongly converting the MTU time to UTC or using MTUs belonging to a different auction.

Bid capacity is invalid

One or more of the requested bid capacities is invalid. Please ensure to enter requested bid capacities in kWs!

In the attached PDF below we have gathered a few illustrative examples on how to execute various bidding requests:

BritNed - Empire - Integration Examples.pdf