Skip to content

Connect a market-data feed

Goal: have WebSocketFeed workers publish a venue's market data (order books, trades, candles) for chosen pairs onto the platform's topics, defined once as a feed definition shared on the context.

Prerequisites

  • Signed in as an admin (others can view definitions only: View…).
  • The context you want the feed on is active (Switch context); on a protected context each write asks first.
  • For venues that need credentials: the names of the secrets in the cluster's worker Secret (you give references, never values).

Steps

  1. Open Trading > Feeds (route /trading/feeds).
  2. Start a definition: in New, pick a venue preset (e.g. binance, fakevenue-binance). The editor New feed opens with a template:

    {
      "$schema": "https://app.virtufin.com/schemas/feed-definition.v1.schema.json",
      "name": "binance",
      "description": "…",
      "preset": "binance",
      "world": "act",
      "pairs": [],
      "families": ["orderbook.update"],
      "reconnect": true
    }
    
  3. Fill it in. Add pairs, e.g. "pairs": ["BTC_USDT", "ETH_USDT"]; list the families you want (orderbook.update, trade.update, candle.update — the last also needs "intervals": ["1m"]); or give topics (templates with {pair}/{interval}) instead. Optional: world (act or hyp.<NAME>), universe, secrets ({"<feed secret>": "<reference>"}), feed (further WebSocketFeed config keys such as maxitems).

  4. Read the preview under the text area: every error with its path (e.g. /families/0 binance serves no 'x'), warnings (unused: no family listed takes an interval), and N topics on M feeds with each planned feed's topics, plus the plan's problems (unserved topics, over a venue limit).
  5. Save and connect (or Save to connect later). The definition is saved as cfg.feed.<NAME>; Connect brings its feeds to its topics, with the definition's name as their owner (feedowner=<name>). A notice says <name>: N feeds serving M topics (K created).

To change a definition later: select it, Edit…, change, Save and connect (the feeds move to the new topics). To stop it: Disconnect (deletes its feeds), then Delete… if the definition should go.

What you should see

  • The definition's row: the dot turns yellow (connecting), then green (all its feeds connected); State connected; Msg/s and Latency p50/p90 fill in.
  • Detail (or Enter): its topics and each feed with its state, subscribed count and msg/s.
  • The feed workers in Infra > Connections and Infra > Workers (tagged feedowner, source, world).
  • Data on the topics: Infra > Events → Topics…, or Trading > Order Book.

Troubleshooting

Symptom Cause and fix
names no topic: give pairs (and intervals for candle.update) or topics pairs is empty.
/families/0 … serves no '…' The preset does not serve that family; the message lists the ones it does.
/<field> '…' is not supported yet Fields of the TUI's older world definitions (ws_url, subscribe, …) are not accepted: use a preset.
Save disabled The definition does not validate, or you are not an admin (Only admins may change feeds).
Connect fails with an incomplete plan Some topics no feed can serve, or a venue limit is exceeded (shown in the preview): fewer pairs or families.
State stays partly connected / red dot Open Detail, then the feed in Infra > Connections → Refresh status for the feed's own report; an alert is raised for disconnected feeds.
Delete… says disconnect it first Its feeds run: Disconnect, then Delete….

More: Views > Feeds, Connections.