Data Provider Adapter

The Data Provider Adapter API defines the contract that external data providers must implement to integrate with the FinP2P Router. Providers such as market data vendors, asset registries, and rating agencies implement this specification so the FinP2P node can fetch and receive financial data for assets on the network.

Data Types

The adapter exchanges data using standardized data type schemas defined in the FinP2P Certificates Spec. Each entry in the data payload references a data type and an optional schema URI for validation.

Integration Modes

The adapter supports two integration modes depending on whether data is fetched on-demand or streamed in real time.

Pull Mode (Async)

For scheduled or on-demand data retrieval. The node sends a fetch request, and the adapter responds asynchronously via a callback.

sequenceDiagram
    participant Node as FinP2P Node
    participant Adapter as Data Provider Adapter

    Node->>Adapter: POST /assets/data (identifiers, dataTypes)
    Adapter-->>Node: 202 Accepted (requestId)

    Note over Adapter: Fetches data from source

    Adapter->>Node: POST /data/assets/ingest (requestId, asset data)
    Node-->>Adapter: 200 OK (ingest results)

The node calls POST /assets/data with the asset identifiers and requested data types.
The adapter returns 202 Accepted with a requestId.
When the data is ready, the adapter pushes it to the node's ingest endpoint (POST /data/assets/ingest) referencing the requestId.

Push Mode (Subscription)

For real-time data streaming. The node creates a subscription, and the adapter pushes updates whenever data changes.

sequenceDiagram
    participant Node as FinP2P Node
    participant Adapter as Data Provider Adapter

    Node->>Adapter: POST /assets/data/subscribe (identifiers, dataTypes)
    Adapter-->>Node: 200 OK (subscriptionId)

    loop On data change
        Adapter->>Node: POST /data/assets/ingest (subscriptionId, asset data)
        Node-->>Adapter: 200 OK (ingest results)
    end

    Node->>Adapter: POST /assets/data/unsubscribe (subscriptionId)
    Adapter-->>Node: 200 OK

The node calls POST /assets/data/subscribe with the asset identifiers and data types to monitor.
The adapter returns a subscriptionId.
Whenever the data changes, the adapter pushes updates to the node's ingest endpoint referencing the subscriptionId.
To stop receiving updates, the node calls POST /assets/data/unsubscribe.

Asset Discovery

Adapters can advertise the assets they support by pushing assetHeader data. The node subscribes to the assetHeader data type, and the adapter pushes structured catalog metadata through the standard ingest pipeline. This allows the node to discover which assets are available from each provider without prior configuration.

Authentication

The node authenticates with adapters using the credentials configured during provider binding. Supported authentication methods include API keys, OAuth, and mTLS.

Ingest Callback

Both integration modes deliver data to the same ingest endpoint on the node. Each entry in the callback payload includes:

Asset identifier (ISIN or CAIP-19)
Data type and optional schema reference
Source identifier and timestamp
Data payload as a JSON object

The node validates each entry and returns per-entry results indicating whether the data was accepted or rejected.