Skip to content

Connect a market-data feed

Goal: get live market data (order books, trades, candles) from a venue onto the platform's topics, by defining a feed and connecting it.

A feed definition (cfg.feed.<name>, shared on the context — the same the web app's Trading › Feeds shows) names a venue preset and the topics to serve. Connecting it creates or re-targets WebSocketFeed workers (tagged feedowner=<name>) that serve exactly those topics; disconnecting deletes them.

Prerequisites

  • An active context (Switch context). Saving, connecting and disconnecting are writes: the server lets only admins make them.
  • For a venue that needs credentials (e.g. alpaca): the key of the cluster's worker Secret (virtufin-worker-secrets) that holds them, e.g. alpaca-paper-key.

Presets shipped by market-data-devkit: binance (orderbook.update, trade.update, candle.update), alpaca (orderbook.update, trade.update), fakevenue-binance, fakevenue-alpaca (orderbook.update), binance-account-testnet.

Steps

  1. Open Feeds: Trading top tab, 1 (Feeds) in the default layout.
  2. Add a definition: press a, pick a preset in New feed definition: venue preset, press Next.
  3. Edit the JSON template. For binance it starts as:

    {
      "$schema": "https://app.virtufin.com/schemas/feed-definition.v1.schema.json",
      "name": "binance",
      "preset": "binance",
      "world": "act",
      "pairs": [],
      "families": ["orderbook.update"],
      "reconnect": true
    }
    

    Set a lower-case name (it becomes the feeds' owner), the pairs (e.g. ["BTC_USDT", "ETH_USDT"]) and the families; add intervals (e.g. ["1m"]) for candle.update. Instead of pairs x families you may list topics directly. world is act or hyp.<NAME>. For credentials add "secrets": {"alpacakey": "alpaca-paper-key"} (a reference into the worker Secret, never the value). The box below the editor validates as you type: errors at their JSON paths in red, warnings in yellow, or valid: <N> topics and the topics. 4. Save: Save (shared). A toast says Saved feed '<name>' (shared on this context); the row appears as disconnected. 5. Connect: highlight the row, press C. market-data-devkit's resolver plans the feeds (refusing topics over a venue's limits) and creates or re-targets them.

To change a definition later: Enter on its row, edit, Save, then C again — the feeds move to the edited topics, and the definition's surplus feeds are deleted. To stop it: X (asks first: its consumers get no data). To remove it: X, then d.

What you should see

  • A toast '<name>': <N> feed(s) serving <M> topics, <K> new.
  • The row's State becomes connected (every feed's socket open) or partly connected, with Feeds and Msg/s.
  • The feeds as rows on Infra › Connections (Msg/s, Subscribed, Latency) and on Infra › Workers; the data on Trading › Order Book, or on Infra › Events after adding the topics (a there).

Troubleshooting

Symptom Cause and fix
'<name>' is not valid: <error> on C The saved definition does not validate; Enter, fix the error shown at its path, Save.
A feed '<name>' exists already: edit it (Enter) Names are unique; edit the existing one or choose another name.
'<name>' is connected: disconnect it first (X) on d Only a disconnected definition can be deleted.
Connect fails with a permission error Only admins may change feeds on the server.
The feed stays partly connected or Msg/s stays 0 Check the feed on Infra › Connections: Status, Failures, and Enter for its detail. A missing secret key leaves the worker LOAD_FAILED.
Connect is refused naming topics They exceed the venue's limits (the preset's maximum items or connections); serve fewer pairs or families.

The local World files (~/.config/virtufin/tui/worlds/*.toml) and composite worlds are gone (tui#53); feed definitions replace them. Reference: Keybindings › Feeds. The AI tab can do the same with feeds__save, feeds__connect, feeds__disconnect (The TUI's API).