IDX Protocol (Version 0.1.0-20250403)

1. Introduction

This document defines the IDX Protocol (§ 6 IDX Protocol) and a data model (§ 5 Data Model) to enable the seamless and interoperable exchange (§ 3 Business Case and Rational) of opportunity data (§ 5.1 Opportunity).

It shall demonstrate that interoperability of impact investment data leads to more investments into SDG-related solutions.

This technical specification is a living document and is work in progress.

1.1. Out of Scope

The following topics and concerns are not within the scope of this specification:

1. KYC- or AML-related topics.

2. Legal or other regulatory aspects of impact investments.

3. The definition of the impact investment or the impact investments space.

4. Data provenance and data security aspects.

2. Definitions

Host System

Software implementation conforming to this specifiction.

Data Owner

A party that exchanges data with another party utilizing the IDX Protocol.

Data Recipient

A party that receives or requests data from a data owner utilizing the IDX Protocol.

Party

A data owner or a data recipient.

Interoperable

The quality of being able to exchange data between host systems irrespective of the vendors of the host systems, without the need for translation or transformation of the data.

OpenId Provider Configuration Document

A OpenId Provider Configuration Document document provided in accordance with [OPENID-CONNECT] Section 4.

AuthEndpoint

The endpoint to request an access token after discovering the value through AuthEndpoint Discovery (§ 6.2.1 Authentication Endpoint Discovery).

3. Business Case and Rational

Note: Non-normative section

The IDX Protocol aims to serve impact investors and investees alike by increasing the efficiency of deal sourcing. The IDX Protocol achieves this by enabling the exchange of investment opportunity data (see § 4 Data Transactions).

The interoperability enabled by the IDX Protocol supports to

1. reduce the friction and cost of impact investment decision making for both investors and investees,

2. increase the number of investments in SDG-related solutions, and

3. increase transparency and accountability of impact investments.

4. Data Transactions

Note: Non-normative section

A data transaction is an abstraction for the exchange of data (§ 5 Data Model) between two parties, serving one or more business cases (§ 3 Business Case and Rational).

Each transaction shall illustrate how the IDX Protocol can be utilized to address the described business cases.

4.1. Data Transaction 1: Opportunity Data Exchange

This data transaction enables an investee (such as a farmer or a cooperative) as the data owner to make Opportunity available to one or more investors or impact funds (the data recipient(s)).

This data transaction also enables an investor or impact fund (the data owner) to share an Opportunity with other investors or impact funds (the data recipient(s)).

For this,

1. the data owner MUST gather the necessary data and input it into a host system that implements the IDX Protocol;

2. the host system MUST

   1. encode this data as an Opportunity and

   2. make it available through an HTTP API, as specified in § 6 IDX Protocol;

   3. provide the data recipient(s) with the credentials necessary for authentication;

3. the data recipient MUST

   1. authenticate with the host system, by following the Authentication Flow;

   2. call the Action OpportunityExchange to retrieve the Opportunity data;

   3. in case more than one Opportunity is returned, filter by, e.g., the name of the data owner.

5. Data Model

The IDX Data Model consists of the data type Opportunity at this point.

5.1. Opportunity

The Opportunity data type contains information relating to a single investment opportunity. This data type has OPTIONAL properties relating to impact investment opportunities.

Host systems make Opportunities available through the IDX Protocol (§ 6 IDX Protocol).

5.1.1. Data Attributes

The Opportunity data type has the following properties:

5.1.2. Opportunity Lifecycle

Host systems SHOULD provide a mechanism to handle the lifecycle of an Opportunity, the life cycle being:

1. Creation: An Opportunity is created by a party and enters the host system subsequently.

2. Update: An Opportunity can be updated by the party that created it later on. In this case, the host system SHOULD

   1. Mark the previous version of the Opportunity as closed and

   2. Create a new Opportunity with the updated data, linking the new Opportunity to the previous one through the previousIds property.

3. Closing: An Opportunity can be closed by the party that created it. In this case, the host system SHOULD:

   1. Mark the Opportunity as closed and

   2. Update the Opportunity with the closing date.

   Note: Closing does not imply success in any way but rather that other parties should no longer consider the Opportunity (as identified by its id) for investment.

Upon each change to Opportunity data (creation, update, or closing), the host system SHOULD provide the new version of the Opportunity to the data recipient(s) through the IDX Protocol.

5.2. Additional Utility Data Types

5.2.1. Data Type PreviousInvestor

The PreviousInvestor data type contains information relating to a previous investor to a previous investment Opportunity.

The PreviousInvestor data type has the following properties:

5.2.2. Data Type Income

The Income data type contains information relating to the income of a party directly or indirectly represented by an Opportunity.

The Income data type has the following properties:

5.2.3. Data Type Cost Structure

The CostStructure data type contains information relating to the cost structure of the party directly or the parties indirectly represented by an Opportunity.

The CostStructure data type has the following properties:

5.2.4. Data Type SustainableFarmingPractices

The SustainableFarmingPractices data type contains information relating to the sustainable farming practices of the party directly or the parties indirectly represented by an Opportunity.

The SustainableFarmingPractices data type has the following properties:

6. IDX Protocol

This section defines an HTTP-based API for the interoperable exchange of Opportunity data between host systems.

Note: The scope of the HTTP API is minimal by design. Additional features will be added in future versions of this specification.

Interoperable data exchange between a data owner and a data recipient can be achieved by

1. the data owner offering Opportunity data through a host system that implements the IDX Protocol, and

2. the data recipient making authenticated calls to retrieve Opportunity data, i.e., by calling the Action OpportunityExchange.

6.1. Host system Minimum Requirements

A host system MUST offer a OpenId Provider Configuration Document as further specified in § 6.2.1 Authentication Endpoint Discovery.

A host system MUST implement the Authentication Flow and Action OpportunityExchange.

A host system MUST offer its actions under https method only.

A host system MUST offer all actions under the same Hostname and Subpath except for the AuthEndpoint returned in the token_endpoint of the OpenId Provider Configuration Document (see Authentication Flow).

6.2. Authentication Flow

A host system MUST require a data recipient to first authenticate before calling other endpoints such as Action OpportunityExchange.

The authentication flow consists of two steps:

1. Discovery of the host system’s authentication endpoint (see § 6.2.1 Authentication Endpoint Discovery.

2. Acquiring a bearer token through Action Authenticate (see § 6.2.2 Action Authenticate).

6.2.1. Authentication Endpoint Discovery

A party discovers the value of the AuthEndpoint by

1. performing a GET request to a host system’s OpenId Provider Configuration Document, using [Hostname]/.well-known/openid-configuration.

   1. the returned document MUST define the token_endpoint property accordingly.

2. using the value of token_endpoint as the AuthEndpoint

6.2.2. Action Authenticate

The Action Authenticate is an HTTP endpoint. It MUST return bearer tokens using client credentials in conformance with [rfc6749] Section 4.4 (OAuth2 Client Credentials).

Host systems MAY offer this action under potentially any path and hostname, provided that this is discoverable as specified in § 6.2.1 Authentication Endpoint Discovery.

See § 6.4.1 Example Action Authenticate request and response for an example request and response.

6.2.2.1. Request Syntax

POST AuthEndpoint HTTP/1.1
accept: application/json
content-type: application/x-www-form-urlencoded
authorization: Basic BasicAuth
content-length: ContentLength
AuthBody

With Request parameters:

BasicAuth

See [rfc6749] Section 4.4.2

AuthBody

See [rfc6749] Section 4.4

ContentLength

The length of the Body. See [rfc9112].

6.2.2.2. Response Syntax

HTTP/1.1 AuthStatusCode OK
content-type: application/json
content-length: ContentLength

AuthResponseBody

With action-specific response parameters

AuthStatusCode

A HTTP response code conforming to [rfc6749] Section 4.4 and Section 5.

AuthResponseBody

A JSON Object conforming to either [rfc6749] Section 4.4 in case of successful authentication (containing an access token), or [rfc6749] Section 5.2 otherwise.

6.3. Action OpportunityExchange

Lists the data owner’s Opportunity data incrementally (see § 6.3.1 Pagination).

A Host system SHOULD implement an access management system to return only the Opportunity data intended for the requesting data recipient.

6.3.1. Pagination

Host systems MUST implement pagination server-side such that

1. The host system MAY return less Opportunities than requested through the Limit request parameter

2. The host system MUST return a Link header if there are additional Opportunities ready to be retrieved, such that

3. The Link header conforms to [rfc8288]

4. The value of the rel parameter is equal to next

5. the target IRI (RFC8288, Section 3.1) of the Link header is absolute

6. The value of host of the target IRI is equal to the value of the host request header from the original OpportunityExchange HTTP request

The target IRI from a pagination link header is called a pagination link.

Upon a host system returning a pagination link

1. a data recipient CAN call the pagination link more than once

2. upon each call, the host system

   1. MUST return the same set of Opportunities upon successful authentication (i.e. BearerToken authentication)

   2. MUST NOT return more Opportunities than requested in case Limit was defined by a data recipient

   3. MUST return a Link header conforming with the previous description in case additional Opportunities are available

3. If a response contains a second pagination link, upon calling the second pagination link, the previous pagination link MAY no longer work

   • i.e. data recipients MUST NOT assume that previous pagination links continue to return results after advancing in the pagination process

4. a pagination link MUST be valid for at least 180 seconds after creation

5. a data recipient SHOULD retry calling the pagination link after the server returned an error

6. and SHOULD use a randomized exponential back-off strategy when retrying

6.3.2. Request Syntax

GET Subpath/1/opportunities?Limit HTTP/1.1
host: Hostname
authorization: Bearer BearerToken

Subpath

If a host system uses a relative subpath, then the requesting data recipient MUST prepend this subpath.

Hostname

The requesting data recipient MUST use the domain name of the host system.

BearerToken

Bearer token (see [rfc6750]).

Limit

Limit is an OPTIONAL request parameter. If defined,

1. the name of the HTTP request parameter MUST be limit

2. and the value MUST be a positive integer.

6.3.3. Response Syntax

Response without a link header:

HTTP/1.1 StatusCode StatusText
content-type: application/json
content-length: ContentLength

ResponseBody

Paginated response with a link header:

HTTP/1.1 StatusCode StatusText
content-type: application/json
content-length: ContentLength
link: PaginationLink; rel="next"

ResponseBody

With response parameters

StatusCode

If the host system returns opportunity data, the HttpStatusCode MUST be 200.

Otherwise, the host system MUST return the appropriate HTTP error code.

StatusText

The HTTP Status text conforming to the HTTP status code StatusCode.

ResponseBody

If the host system accepts the BearerToken, the body MUST be a JSON object with property data with value a JSON array of Opportunities.

Otherwise, the host system MUST return an error response JSON object with the following properties:

• code: the error response code (corresponding to the StatusCode) encoded as a String;

• message: a human-readable error description encoded as a String.

PaginationLink

See pagination link and § 6.3.1 Pagination.

6.4. Examples

6.4.1. Example Action Authenticate request and response

Example Request

POST /auth HTTP/1.1
accept: application/json
content-type: application/x-www-form-urlencoded
authorization: Basic [base64(client_id:client_secret)]
grant-type: client_credentials

Example Successful Response

{
  "access_token": "...",
  "token_type": "bearer"
}

Example Error Response (Invalid Client)

HTTP/1.1 400 Bad Request
date: Wed, 29 Jan 2025 19:33:16 GMT
content-type: application/json

{
  "error": "invalid_client",
  "error_description": "Authentication failed"
}

6.4.2. Example Action OpportunityExchange request and response

Example Request

GET /1/opportunities?limit=1 HTTP/1.1
host: example.com
authorization: Bearer [access_token]

Example Successful Response

HTTP/1.1 200 OK
content-type: application/json
content-length: 661
server: example-server
link: <https://api.example./1/opportunities?limit=1&offset=1>; rel="next"

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174002",
      "specVersion": "0.0.1",
      "createdAt": "2025-01-28T12:00:00Z",
      "status": "active",
      "previousIds": [ "123e4567-e89b-12d3-a456-426614174000", "123e4567-e89b-12d3-a456-426614174001" ],
      "companyName": "Example Company",
      "email": "example@company.com",
      "city": "Berlin",
      "country": "DE",
      "websiteUrl": "https://example.com",
      "businessSummary": "Example business summary",
      "fundingAsk": "1230000",
      "fundingCurrency": "EUR",
      "previousInvestors": [
        {
          "name": "Example Investor",
          "email": "example@investor.com",
          "investmentDate": "2025-01-28"
        }
      ],
      "incomes": [
        {
          "amount": "1230000",
          "currency": "EUR",
          "kind": "SustainableFarming",
          "date": "2025-01-28"
        }
      ],
      "costStructure": {
        "currency": "EUR",
        "totalCosts": "1230000",
      },
      "sustainableFarmingPractices": {
        "soilManagement": ["CoverCrops"],
        "biodiversityPractices": ["EfficientAgrochemicalsUse"],
        "waterManagement": ["SoilWaterConservation"]
      }
    }
  ]
}

Example Error Response (Invalid Token)

HTTP/1.1 401 Unauthorized
content-type: application/json
content-length: 29

{
  "code": "Unauthorized",
  "message": "Invalid token"
}

Appendix A: Changelog

Version 0.1.0-20250403 (2025-04-03)

Summary:

• bumped version number to 0.1.0

• rewording of Appendix B: Conformance Testing

• several fixes and clean ups to stray definitions with no further reference

Version 0.0.1-20250219 (2025-02-19)

Summary:

• addition of Opportunity lifecycle definitions. Specifically

  • addition of properties id, previousIds, specVersion, createdAt, status

  • addition of chapter § 5.1.2 Opportunity Lifecycle

Version 0.0.1-20250128 (2025-01-28)

Summary: Initial release of the specification.

Appendix B: Conformance Testing

This appendix is a work in progress. All feedback is welcome.

Conformance Testing is an interoperabilty testing process, performed by executing and passing test cases (Test Matrix).

The goal of this process is to assess the interoperability between host systems, and to which extend an individual host system implements this specification.

The process is structured by a set of test cases (Test Cases), with categories Mandatory Tests and Recommended Tests (also see Test Matrix).

Within the process, host systems have different roles:

1. the host system executing tests, which in this role is called the tester host system,

2. the host system under test, which in this role is called the target host system.

A target host system has successfully passed the Conformance Testing if it passed all Mandatory Tests.

Note: It is recommended to perform the Conformance Testing process as a bilateral testing process, wherein two parties mutually test each other’s host systems as a target host system and a tester host system:

Note: It is RECOMMENDED for the parties to also test and document the results from running Recommended Tests.

Test Matrix

Test Cases

Although both host systems are tested in bilateral testing, only one of them is the target of the tests at each time.

Bilateral testing MUST include the following tests (and MAY include additional tests):

Test Case 001: AuthEndpoint Discovery

Tests the target host system’s ability to have a discoverable AuthEndpoint.

Request

A GET request must be sent to the target host system’s [Hostname]/.well-known/openid-configuration endpoint.

Expected Response

A valid OpenId Provider Configuration Document (conforming to [OPENID-CONNECT] Section 4) MUST be returned. The value of the token_endpoint property MUST be a valid URL, offering Action Authenticate.

Test Case 002: Successful Authentication

Tests the target host system’s ability to authenticate a data recipient.

Request

A POST request must be sent to the target host system’s AuthEndpoint with valid credentials as per the syntax specified in § 6.2.2.1 Request Syntax.

Expected Response

The target host system MUST respond with StatusCode 200 OK and a JSON body containing the access token, as specified in § 6.2.2.2 Response Syntax.

Test Case 003: Authentication with Invalid Credentials

Tests the target host system’s ability to handle invalid credentials during authentication.

Request

A POST request must be sent to the target host system’s AuthEndpoint with invalid credentials as per the syntax specified in § 6.2.2.1 Request Syntax.

Expected Response

The target host system MUST respond with an error response, as specified in § 6.2.2.2 Response Syntax.

The StatusCode SHOULD be 401 Unauthorized and the code property SHOULD be Unauthorized. The message property CAN be any human-readable error message (e.g., "Invalid credentials").

Test Case 004: Malformed Authentication Request

Tests the target host system’s ability to handle malformed authentication requests.

Request

A POST request must be sent to the target host system’s AuthEndpoint with a malformed request (e.g., missing grant-type).

Expected Response

The target host system MUST respond with an error response, as specified in § 6.2.2.2 Response Syntax.

The StatusCode SHOULD be 400 BadRequest and the code property SHOULD be BadRequest. The message property CAN be any human-readable error message (e.g., "Malformed request").

Test Case 005: Action OpportunityExchange without Limit

Tests the target host system’s ability to return Opportunity data without a Limit.

Request

A GET request must be sent to the target host system’s [Subpath]/1/opportunities endpoint without a limit parameter.

Expected Response

The target host system MUST respond with StatusCode 200 OK and a valid JSON body containing the Opportunity data, as specified in § 6.3.3 Response Syntax. The Link header MAY be present.

Test Case 006: Action OpportunityExchange Pagination

Tests the target host system’s ability to paginate Opportunity data.

Request

A GET request must be sent to the target host system’s [Subpath]/1/opportunities endpoint with a limit parameter, requesting less Opportunity data than available.

Expected Response

The target host system MUST respond with StatusCode 200 OK and a valid JSON body containing a subset of the Opportunity data available, as specified in § 6.3.3 Response Syntax. The Link header MUST be present and conform to the pagination rules specified in § 6.3.1 Pagination.

Upon calling the pagination link, the target host system MUST return the next subset of the Opportunity data available. Upon calling the same link again, the target host system MUST return the same subset of Opportunity data.

Test Case 007: Action OpportunityExchange with Malformed Limit

Tests the target host system’s ability to handle a malformed limit parameter.

Request

A GET request must be sent to the target host system’s [Subpath]/1/opportunities endpoint with a malformed limit parameter (e.g., the value is not a positive integer or limit is misspelled).

Expected Response

The target host system MUST respond with an error response, as specified in § 6.3.3 Response Syntax. The StatusCode SHOULD be 400 BadRequest and the code property SHOULD be BadRequest. The message property CAN be any human-readable error message (e.g., "Malformed limit parameter").

Test Case 008: Action OpportunityExchange with Invalid Token

Tests the target host system’s ability to handle an invalid access token.

Request

A GET request must be sent to the target host system’s [Subpath]/1/opportunities endpoint with an invalid access token.

Expected Response

The target host system MUST respond with an error response, as specified in § 6.3.3 Response Syntax. The StatusCode SHOULD be 401 Unauthorized and the code property SHOULD be Unauthorized. The message property CAN be any human-readable error message (e.g., "Invalid token").

Test Case 009: Action OpportunityExchange with Expired Token

Tests the target host system’s ability to handle an expired access token.

Request

A GET request must be sent to the target host system’s [Subpath]/1/opportunities endpoint with an expired access token.

Expected Response

The target host system MUST respond with an error response, as specified in § 6.3.3 Response Syntax. The StatusCode SHOULD be 401 Unauthorized and the code property SHOULD be Unauthorized. The message property CAN be any human-readable error message (e.g., "Expired token").

Test Case 010: Malformed OpportunityExchange Request

Tests the target host system’s ability to handle malformed requests to the [Subpath]/1/opportunities.

Request

A GET request must be sent to the target host system’s [Subpath]/1/opportunities endpoint with a malformed request (e.g., missing authorization header).

Expected Response

The target host system MUST respond with an error response, as specified in § 6.3.3 Response Syntax. The StatusCode SHOULD be 400 BadRequest and the code property SHOULD be BadRequest. The message property CAN be any human-readable error message (e.g., "Malformed request").

Test Result Communications

It is recommended to send the conformance testing results to idx-interop-testing@sine.dev.