logo
API docs by Redocly

Faradyn Platform Documentation (1.0.1)

Download OpenAPI specification:Download

Introduction

The Faradyn platform is designed to allow you to automate the process of receiving auction requirements and submitting your resulting bids and offers.

The platform aims to achieve this through the use of a RESTful API which allows you to query and submit data and a WebSocket Interface to enable the timely delivery of relevant notifications.

API Introduction

The Faradyn Platform API allows you to programmatically submit bids and offers for electricity auctions run by NESO.

The API is designed around REST concepts, accepts JSON-encoded request bodies and returns JSON-encoded responses.

The API is available at the following URLs:

Rate Limiting

Rate limiting is currently disabled. These limits will be reviewed after the beta period.

Requests to the API are rate limited to 200 requests per minute per Organisation. If you exceed this limit, you will receive a 429 Too Many Requests response. You can view your current rate limit status within your organisation dashboard.

Authentication Overview

The API uses API keys to authenticate requests. You can view and manage your API keys within your organisation dashboard. All requests must be authenticated with an API key and signed with a JWT and will fail if the key is invalid or missing.

API Key

API keys can be generated through the Web UI. An API key should be included with every request in a header called X-API-Key. Every API key will be prefixed with the intended environment, for example test-api- or live-api-

Any requests missing an API key will be rejected with a 401 Unauthorized response.

An API key can be marked as Read Only. This restricts it to only making GET requests.

JWT Signatures

All requests and responses must be signed with a JWT. These signatures will be included within the X-JWT HTTP header.

Any requests missing a valid JWT signature will be rejected with a 401 Unauthorized response.

JWTs must be signed with one of the following algorithms:

  • RS256 - RSA SHA256
  • ES256 - ECDSA SHA256
  • EdDSA - Ed25519

You can select the algorithm you would like to use when creating your API Key. This algorithm will be used for both request and response signatures.

You can inspect the JWT signature of a request through the API Key's request log within the Web UI.

Request JWT Signature

Any requests missing a valid JWT signature will be rejected with a 401 Unauthorized response.

The request JWT signature must include the following claims:

  • iat - The current UNIX timestamp as an integer. Any signatures with an iat claim that is in the future will be rejected.
  • method - The HTTP method of the request. This must be upper case, for example "GET"
  • url - The pathname of the request. This must not include the hostname, for example "/v1/submissions"
  • query - SHA256 hash of the query string being used for this request.
    • For example SHA256('perPage=100&page=2') → d678362383069d5aa7382aed7e0a86816cdc1fd0235fae09f57e36cb5d27b6ef
  • body - SHA256 hash of the request body.
    • For example SHA256('{"submissions":[]}") → ff9adb183df850d5bac15521142bbff3825a2c33470c34cef6a67d17957543b8

The request JWT signature may optionally include the following claims:

  • exp - The UNIX timestamp at which the JWT expires and should be rejected as an integer.
    • If not included, the JWT will expire 30 seconds after the iat claim.
    • This value be no more than 5 minutes after the iat claim.

The JWT must be signed with the private key that matches the public key you provided for the API key in use.

JWT Example

Note that the JSON examples show below have been formatted. They were not formatted when generating the example signature.

{
  "alg": "RS256",
  "typ": "JWT"
}

Payload

{
  "iat": 1550000000,
  "method": "GET",
  "url": "/v1/submissions",
  "query": "d678362383069d5aa7382aed7e0a86816cdc1fd0235fae09f57e36cb5d27b6ef",
  "body": "ff9adb183df850d5bac15521142bbff3825a2c33470c34cef6a67d17957543b8"
}

Signature

Hpwh8vTAdXobNpeyP71426BbkBT5oiZoJ1qy-6Bh6aZ8OThmtt45AQ5-hC7UueKqSYmeI5B75oZMYVNgf5eA20rkG3WNL9AHHvFDaWOtpgAP3x7OHsgI57_BJkFQqkEYQl0gPlWbrxmosUOJeo6bEwM5wNeipsB337XSXoC2sxU7mv4Eks8zxAn7FEAXY9hWzQNukyFnejc-nf2tYKyjIUnffXgePAJUHFQNpoQ5KruOczov64U8tmXGJeBplinjbzplcZh1IelvQYAx4IH1pz-USU8MEKmF6PEgj8_Ivfhp4PGjlOcsrX4kXaFVseBPiEGyNzptrehy3dr82KmS6Q51D9ZUXDXQIwyhhS2Puot8unpVk51oEeY0ZIyWeohHfGVpvTy_Z5YZ0UZEGJv5FiI7_rofW_3l9J5D1U5j1eH37QjqFsUvT96WX_T1eDXd9PoX1wq-XEsKf_-vahKWFvNbLAi6tT0YzeTU5MSxOa5zDaNO8WTVHhIz-6Iag00d4nNYCZNN8ZVWJJhDzG64gf1z-VSWLC4aUyvxx3NhtDP8IJCgeSvZn368Z0-VydPd5Dlo9ZMROuxOeQJjsXgLkSKzcHNUpKR2ku99Pu4kMmng1Yl5u4CmRmxZEH_Q4D9PayjW7FksvvSvEgJKvN0vjBCjiZfZp7E8-0tSLaN9k3k

Full JWT

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE1NTAwMDAwMDAsIm1ldGhvZCI6IkdFVCIsInVybCI6Ii92MS9zdWJtaXNzaW9ucyIsInF1ZXJ5IjoiZDY3ODM2MjM4MzA2OWQ1YWE3MzgyYWVkN2UwYTg2ODE2Y2RjMWZkMDIzNWZhZTA5ZjU3ZTM2Y2I1ZDI3YjZlZiIsImJvZHkiOiJmZjlhZGIxODNkZjg1MGQ1YmFjMTU1MjExNDJiYmZmMzgyNWEyYzMzNDcwYzM0Y2VmNmE2N2QxNzk1NzU0M2I4In0.Hpwh8vTAdXobNpeyP71426BbkBT5oiZoJ1qy-6Bh6aZ8OThmtt45AQ5-hC7UueKqSYmeI5B75oZMYVNgf5eA20rkG3WNL9AHHvFDaWOtpgAP3x7OHsgI57_BJkFQqkEYQl0gPlWbrxmosUOJeo6bEwM5wNeipsB337XSXoC2sxU7mv4Eks8zxAn7FEAXY9hWzQNukyFnejc-nf2tYKyjIUnffXgePAJUHFQNpoQ5KruOczov64U8tmXGJeBplinjbzplcZh1IelvQYAx4IH1pz-USU8MEKmF6PEgj8_Ivfhp4PGjlOcsrX4kXaFVseBPiEGyNzptrehy3dr82KmS6Q51D9ZUXDXQIwyhhS2Puot8unpVk51oEeY0ZIyWeohHfGVpvTy_Z5YZ0UZEGJv5FiI7_rofW_3l9J5D1U5j1eH37QjqFsUvT96WX_T1eDXd9PoX1wq-XEsKf_-vahKWFvNbLAi6tT0YzeTU5MSxOa5zDaNO8WTVHhIz-6Iag00d4nNYCZNN8ZVWJJhDzG64gf1z-VSWLC4aUyvxx3NhtDP8IJCgeSvZn368Z0-VydPd5Dlo9ZMROuxOeQJjsXgLkSKzcHNUpKR2ku99Pu4kMmng1Yl5u4CmRmxZEH_Q4D9PayjW7FksvvSvEgJKvN0vjBCjiZfZp7E8-0tSLaN9k3k

Response JWT Signature

All responses with a valid API Key will include a JWT signature.

The response JWT signature will include the following claims:

  • iat - The current UNIX timestamp as an integer.
  • exp - iat + 30 seconds.
  • code - The HTTP response code of the request as an integer.
  • body - SHA256 hash of the response body.
    • For example SHA256('{"submissions":[]}") → ff9adb183df850d5bac15521142bbff3825a2c33470c34cef6a67d17957543b8

The JWT must be signed using our private key and should be validated using the public key provided on the API Key page within the Web UI.

JWT Example

Note that the JSON examples show below have been formatted. They were not formatted when generating the example signature.

{
  "typ": "JWT",
  "alg": "RS256"
}

Payload

{
  "iat": 1550000000,
  "exp": 1550000030,
  "code": 200,
  "body": "3ae44b19724a05e2d9ab88bac2acc3402e8fc421da6fc016af185546ae00765f"
}

Signature

PyhkKOzJzjUzpjGcQQVco5WN24tKXw3D5E9kvuHYw7Wkq1nnqsn2iHbRpgUicqFKPVZfidnY7vaRXKRTeLqCv7Hv7q3Z8dLSdmgGCxRHeQOOJwsXlVMQz4JkcP4LAMmsDBq0R6ZnhSAX0xMSMtZ9PoOpEcIad8gVXoSyrNaiwB4453fzp-Bi72t5_J4phgExgPdMkYZvfbWwzZC6OtQIH2ZiBLiGOi4XyV4RNOA9qk_94EdkmzKYcb6Ipq8IHJWWPcRDseGmua2UEwbOOp2zrvHQoe4BbkSt98wA2IUhcNA3PFNxMg_LTT1j4JBtYpPqs7SQRHd82VYS4GjWcm3P5EFjRcKHPlyU9FxIziTkPREXp7ag2SJknzEmP4JsNiqArs1FjPOCb1yMe36mGfj1wWBc8b1NzvoH_AgFL8lQq_RD7pmYZx4IcbRh4WHemVpqD2Pr5Vl6hCOOAMc-0ldU3C4__9cjF1Sc69lx4Dvo0wZ5VA-Zy5UHnNIQW74rgl9bhJFtsDhrLrYR75gCUcn3F32BejibeZn2VE3cNfLCOXO4se0aTZydeTxAeWLLqGk1QWdE5wqtV06cCPpOP_YSgsMho5hZtfnXsmsNpBsHi5uQ9aGCKI5tK-aOOkOccB_q_rxprKdPZ6GscWZxK5bK_p1jhkVsliqZIMKXYtT7KeM

Full JWT

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE1NTAwMDAwMDAsImV4cCI6MTU1MDAwMDAzMCwiY29kZSI6MjAwLCJib2R5IjoiM2FlNDRiMTk3MjRhMDVlMmQ5YWI4OGJhYzJhY2MzNDAyZThmYzQyMWRhNmZjMDE2YWYxODU1NDZhZTAwNzY1ZiJ9.PyhkKOzJzjUzpjGcQQVco5WN24tKXw3D5E9kvuHYw7Wkq1nnqsn2iHbRpgUicqFKPVZfidnY7vaRXKRTeLqCv7Hv7q3Z8dLSdmgGCxRHeQOOJwsXlVMQz4JkcP4LAMmsDBq0R6ZnhSAX0xMSMtZ9PoOpEcIad8gVXoSyrNaiwB4453fzp-Bi72t5_J4phgExgPdMkYZvfbWwzZC6OtQIH2ZiBLiGOi4XyV4RNOA9qk_94EdkmzKYcb6Ipq8IHJWWPcRDseGmua2UEwbOOp2zrvHQoe4BbkSt98wA2IUhcNA3PFNxMg_LTT1j4JBtYpPqs7SQRHd82VYS4GjWcm3P5EFjRcKHPlyU9FxIziTkPREXp7ag2SJknzEmP4JsNiqArs1FjPOCb1yMe36mGfj1wWBc8b1NzvoH_AgFL8lQq_RD7pmYZx4IcbRh4WHemVpqD2Pr5Vl6hCOOAMc-0ldU3C4__9cjF1Sc69lx4Dvo0wZ5VA-Zy5UHnNIQW74rgl9bhJFtsDhrLrYR75gCUcn3F32BejibeZn2VE3cNfLCOXO4se0aTZydeTxAeWLLqGk1QWdE5wqtV06cCPpOP_YSgsMho5hZtfnXsmsNpBsHi5uQ9aGCKI5tK-aOOkOccB_q_rxprKdPZ6GscWZxK5bK_p1jhkVsliqZIMKXYtT7KeM

Read Auctions

All requests related to reading auction data

List all auctions

Use this endpoint to retrieve auctions. This includes auctions in all statuses, including closed and cancelled auctions.

Results are returned in reverse chronological order with newest auctions being returned first.

Authorizations:
(ApiKeyJWTSignature)
query Parameters
page
integer

The page number to return

perPage
integer

Number of results to return per page. This value must be between 1 and 200, and the default is 20

AuctionStatus (string) or Array of AuctionStatus (strings)

Filter by auction status. This can be a single status or a list of statuses. If no status is provided, all auctions will be returned.

startedAfter
string <date-time>
Example: startedAfter=2022-12-08T10:00:00Z

Filter by the auction start date. Only auctions started after this date will be included.

startedBefore
string <date-time>
Example: startedBefore=2022-12-08T10:00:00Z

Filter by the auction start date. Only auctions started before this date will be included.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "pages": {
    }
}

Retrieve an auction

Retrieve the details of an auction using the auction's unique ID.

Authorizations:
(ApiKeyJWTSignature)
path Parameters
auctionId
required
string

The ID of the auction, this value is case sensitive.

Responses

Response samples

Content type
application/json
{
  • "lots": [
    ],
  • "id": "2022_12_08-10_00",
  • "dateStarted": "2022-12-08T10:00:00Z",
  • "biddingCloseDate": "2022-12-08T12:00:00Z",
  • "status": "Running",
  • "dateCompleted": "2022-12-08T12:30:00Z",
  • "dateCancelled": null,
  • "cancellationReason": "string",
  • "currentVersionNumber": 1,
  • "links": {}
}

List all relevant submissions

Use this endpoint to retrieve all submissions relevant to this auction. This includes submissions in all statuses, including withdrawn ones.

Results are returned in reverse chronological order with newest submissions being returned first.

Note: This endpoint is essentially an alias of /v1/submissions with the relevantToAuction parameter set

Authorizations:
(ApiKeyJWTSignature)
query Parameters
page
integer

The page number to return

perPage
integer

Number of results to return per page. This value must be between 1 and 200, and the default is 20

sortBy
string
Default: "deliveryTime"
Enum: "deliveryTime" "dateUpdated"

How to sort the results. By default, results are sorted by the submissions delivery time.

sortOrder
string
Default: "desc"
Enum: "asc" "desc"

The order to sort the results. By default, results are sorted in descending order.

SubmissionStatus (string) or Array of SubmissionStatus (strings)

Filter results by status.

SubmissionStage (string) or Array of SubmissionStage (strings)

Filter results by stage.

DeliveryPoint (string) or Array of DeliveryPoint (strings)

Filter results by the delivery point they were submitted to.

AuctionDirection (string) or Array of AuctionDirection (strings)

Filter results by their direction

startAfter
string <date-time>
Example: startAfter=2020-01-01T00:00:00Z

Filter results by their start date. Only submissions with a start date after this date will be returned.

startBefore
string <date-time>
Example: startBefore=2020-01-01T00:00:00Z

Filter results by their start date. Only submissions with a start date before this date will be returned.

endAfter
string <date-time>
Example: endAfter=2020-01-01T00:00:00Z

Filter results by their end date. Only submissions with a end date after this date will be returned.

endBefore
string <date-time>
Example: endBefore=2020-01-01T00:00:00Z

Filter results by their end date. Only submissions with a end date before this date will be returned.

submittedByUser
string

Return only submissions that were last updated by this user. This should be the user's ID

submittedByApiKey
string

Return submissions that were last updated by this API key. This should be the API key's ID

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "pages": {
    }
}

List auction versions

Lists all the versions of an auction. This provides a full history of the requirements of an auction.

Results do not include the lots of each version. These can be retrieved using the Retrieve an auction version endpoint.

Results are returned in reverse chronological order with newest version being returned first.

Authorizations:
(ApiKeyJWTSignature)
path Parameters
auctionId
required
string

The ID of the auction, this value is case sensitive.

query Parameters
page
integer

The page number to return

perPage
integer

Number of results to return per page. This value must be between 1 and 200, and the default is 20

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "pages": {
    }
}

Retrieve an auction version

Retrieve the details of an auction version using the version's unique ID.

Authorizations:
(ApiKeyJWTSignature)
path Parameters
auctionId
required
string

The ID of the auction, this value is case sensitive.

auctionVersionId
required
string

The ID of the auction version

Responses

Response samples

Content type
application/json
{
  • "id": "2022_12_08-10_00",
  • "versionNumber": 1,
  • "dateCreated": "2022-12-08T10:00:00Z",
  • "biddingCloseDate": "2022-12-08T12:00:00Z",
  • "lots": [
    ],
  • "comments": "string"
}

Get auction results

Lists all of your scheduled trades for an auction. Scheduled trades are sorted by their start date, ascending.

Authorizations:
(ApiKeyJWTSignature)
path Parameters
auctionId
required
string

The ID of the auction, this value is case sensitive.

query Parameters
page
integer

The page number to return

perPage
integer

Number of results to return per page. This value must be between 1 and 200, and the default is 20

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "pages": {
    }
}

Read Submissions

All requests related to reading submission data

List all submissions

Use this endpoint to retrieve submissions made by your organisation. This includes submissions in all statuses, including withdrawn ones.

Results are returned in reverse chronological order with newest submissions being returned first.

Authorizations:
(ApiKeyJWTSignature)
query Parameters
page
integer

The page number to return

perPage
integer

Number of results to return per page. This value must be between 1 and 200, and the default is 20

sortBy
string
Default: "deliveryTime"
Enum: "deliveryTime" "dateUpdated"

How to sort the results. By default, results are sorted by the submissions delivery time.

sortOrder
string
Default: "desc"
Enum: "asc" "desc"

The order to sort the results. By default, results are sorted in descending order.

SubmissionStatus (string) or Array of SubmissionStatus (strings)

Filter results by status.

SubmissionStage (string) or Array of SubmissionStage (strings)

Filter results by stage.

auctionId
string

Filter results by the auction they were submitted to. Note that this does not return all submission that will be considered for an auction. Open submissions that match the auction's requirements will also be considered for the auction.

relevantToAuction
string

Filter results by whether they are relevant to an auction. This will return all submissions that are specifically for this auction or are open and match the auction's requirements.

DeliveryPoint (string) or Array of DeliveryPoint (strings)

Filter results by the delivery point they were submitted to.

AuctionDirection (string) or Array of AuctionDirection (strings)

Filter results by their direction

startAfter
string <date-time>
Example: startAfter=2020-01-01T00:00:00Z

Filter results by their start date. Only submissions with a start date after this date will be returned.

startBefore
string <date-time>
Example: startBefore=2020-01-01T00:00:00Z

Filter results by their start date. Only submissions with a start date before this date will be returned.

endAfter
string <date-time>
Example: endAfter=2020-01-01T00:00:00Z

Filter results by their end date. Only submissions with a end date after this date will be returned.

endBefore
string <date-time>
Example: endBefore=2020-01-01T00:00:00Z

Filter results by their end date. Only submissions with a end date before this date will be returned.

submittedByUser
string

Return only submissions that were last updated by this user. This should be the user's ID

submittedByApiKey
string

Return submissions that were last updated by this API key. This should be the API key's ID

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "pages": {
    }
}

Retrieve a submission

Retrieve the details of a submission using the submission's unique ID.

Authorizations:
(ApiKeyJWTSignature)
path Parameters
submissionId
required
string

The ID of submission

Responses

Response samples

Content type
application/json
{
  • "id": "submission-id",
  • "auctionId": "2022_12_08-10_00",
  • "status": "Active",
  • "stage": "Received",
  • "dateSubmitted": "2022-12-08T10:00:00Z",
  • "direction": "Offer",
  • "volume": 1000,
  • "start": "2022-12-08T13:00:00Z",
  • "end": "2022-12-08T14:00:00Z",
  • "price": 125.25,
  • "deliveryPoint": "IFA1",
  • "expiryDate": "2022-12-08T14:00:00Z",
  • "expiryDateIsAutomatic": false
}

List submission versions

Retrieve all versions of a submission.

Results are returned in reverse chronological order with newest version being returned first.

Authorizations:
(ApiKeyJWTSignature)
path Parameters
submissionId
required
string

The ID of submission

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "pages": {
    }
}

Retrieve a submission version

Retrieve the details of a submission version using the version's unique ID.

Authorizations:
(ApiKeyJWTSignature)
path Parameters
submissionId
required
string

The ID of submission

submissionVersionId
required
string

The ID of the submission version

Responses

Response samples

Content type
application/json
{
  • "id": "0123456789abcdef",
  • "versionNumber": 1,
  • "auctionId": "2022_12_08-10_00",
  • "withdrawn": false,
  • "dateSubmitted": "2022-12-08T10:00:00Z",
  • "direction": "Offer",
  • "volume": 1000,
  • "start": "2022-12-08T13:00:00Z",
  • "end": "2022-12-08T14:00:00Z",
  • "price": 125.25,
  • "deliveryPoint": "IFA1",
  • "expiryDate": "2022-12-08T14:00:00Z",
  • "expiryDateIsAutomatic": false,
  • "user": {
    },
  • "apiKey": {
    }
}

Write Submissions

All requests related to writing submission data. This includes adding, updating, and withdrawing submissions.

Write Submissions

Write multiple submissions. Submissions that already exist will be updated, new submissions will be created.

All actions are performed as a batch. If any of the submissions fail validation, none of the submissions will be created or updated.

Authorizations:
(ApiKeyJWTSignature)
Request Body schema: application/json
required
Array of objects (WriteSubmission)

The submissions to write. Writing a submission will automatically transition it from withdrawn to submitted.

withdraw
Array of strings

The IDs of submissions to withdraw

Responses

Request samples

Content type
application/json
{
  • "submissions": [
    ],
  • "withdraw": [
    ]
}

Response samples

Content type
application/json
{
  • "updated": [
    ],
  • "withdrawn": [
    ],
  • "unchanged": [
    ]
}

WebSocket Introduction

The Faradyn Platform WebSocket interface allows you to subscribe to timely notifications triggered by the Faradyn Platform.

Messages exchanged by the WebSocket interface are JSON-encoded.

A WebSocket can be added through the Web UI. This is also where you can configure which notifications will be delivered to each WebSocket.

Each WebSocket Key can only have one active connection at a time. If you attempt to connect using a WebSocket Key that already has an established connection, the previous connection will be closed.

The WebSockets are available at the following URLs:

WebSocket Authentication

Connections to the WebSocket are authenticated using a WebSocket Key generated within the Web UI.

There are two methods to authenticate to the WebSocket:

  • X-WebSocket-Key header
  • authenticate message

X-WebSocket-Key header

This is the preferred method of authentication. The WebSocket Key, generated within the Web UI, is passed to the WebSocket interface using the X-WebSocket-Key header.

The WebSocket key will then be authenticated before the request is upgraded to a WebSocket. A connected event will then be sent to the client.

authenticate message

Some WebSocket client implementations do not allow for custom headers to be sent. In this case, the WebSocket Key can be sent as a message to the WebSocket interface.

Upon the request being upgraded to a WebSocket, the client must send an authenticate message:

{
  "action": "authenticate",
  "key": "Your WebSocket Key"
}

The WebSocket key will then be authenticated before the connected event is sent to the client.

The connection will be closed if the WebSocket key is invalid or if no key is sent within 2 seconds.

WebSocket Events

Events are sent to the client as JSON objects. The following events are supported:

  • Connection Established - connected
    • This event is not related to a notification and therefore doesn't contain a notification object.
    • There is no need to acknowledge this event.
  • Auction Created - auction-created
  • Auction Ended - auction-ended
  • Auction Results - auction-results
  • Auction Deadline Approaching - auction-deadline-approaching
  • Auction Updated - auction-updated
  • Auction Cancelled - auction-cancelled
  • Submissions Received - submissions-received

The general format for events is:

{
  "type": "event-type",
  "payload": {},
  "notification": {
    "id": "notification ID",
    "dateCreated": "2023-01-01T00:00:00Z"
  }
}

The notification ID is used to acknowledge the event and is consistent between WebSocket connections. See Acknowledging Events for more information.

Connection Established

This event is triggered when the WebSocket connection is successfully established and authenticated. It is not related to a notification and therefore doesn't contain a notification object.

The connection ID can be used to view events related to the connection in the Web UI.

{
  "type": "connected",
  "payload": {
    "connection": "connection ID"
  }
}

Auction Created

This event is triggered when a new auction is published by NESO.

The payload will contain the full auction, similarly to the Retrieve an auction request

Auction Ended

This event is triggered when the bidding period for an auction has ended.

The payload will contain the full auction, similarly to the Retrieve an auction request

Auction Results

This event is triggered when the results for an auction have been processed and published by NESO.

This notification will only be fired if you have submitted any bids to the auction.

The payload will contain both the full auction, similarly to the Retrieve an auction request, and a list of your scheduled trades.

The scheduled trades will be in the same format as the Get auction results request.

{
  "auction": {},
  "scheduledTrades": [
    {
      "submissionId": "submission ID",
      "tradeId": "",
      "direction": "Buy",
      "volume": 1,
      "start": "2023-01-01T00:00:00Z",
      "end": "2023-01-01T00:30:00Z",
      "price": 1,
      "deliveryPoint": "IFA1"
    }
  ]
}

Please note that each submission may result in multiple scheduled trades, depending on NESO's requirements. The sum of accepted volume will not be greater than the volume submitted.

Auction Deadline Approaching

This event is triggered 10 minutes before the end of the bidding period for an auction.

The payload will contain the full auction, similarly to the Retrieve an auction request

Auction Updated

This event is triggered when an auction is updated by NESO. This could be due to a change in the auction requirements or a change in the bidding deadline.

The payload will contain the full auction, similarly to the Retrieve an auction request

Auction Cancelled

This event is triggered when an auction is cancelled by NESO.

The payload will contain the full auction, similarly to the Retrieve an auction request

Submissions Received

This event is triggered when the Faradyn platform has received any submissions from your organisation.

The payload will contain a list of submissions that have been added or updated, including all of their data. The payload will also include a list of submissions that have been withdrawn.

{
  "updated": [
    {
      "id": "submission ID",
      "auctionId": "auction ID",
      "status": "Active",
      "stage": "Received",
      "dateSubmitted": "2023-01-01T00:00:00Z",
      "direction": "Buy",
      "volume": 1,
      "start": "2023-01-01T00:00:00Z",
      "end": "2023-01-01T00:30:00Z",
      "price": 1,
      "deliveryPoint": "IFA1",
      "expiryDate": "2023-01-01T00:00:00Z",
      "expiryDateIsAutomatic": true
    }
  ],
  "withdrawn": [
    {
      "id": "submission ID",
      "auctionId": "auction ID",
      "status": "Active",
      "stage": "Received",
      "dateSubmitted": "2023-01-01T00:00:00Z",
      "direction": "Buy",
      "volume": 1,
      "start": "2023-01-01T00:00:00Z",
      "end": "2023-01-01T00:30:00Z",
      "price": 1,
      "deliveryPoint": "IFA1",
      "expiryDate": "2023-01-01T00:00:00Z",
      "expiryDateIsAutomatic": true
    }
  ]
}

Acknowledging WebSocket Events

All notifications received by your WebSocket client should be acknowledged.

This is done by sending a message back to the server with the id property from the notification object.

Upon connecting to the WebSocket server, you will be re-sent any unacknowledged notifications from the last 30 minutes.

Acknowledgment Message

{
  "action": "ack",
  "id": "notification id"
}