unrip/docs/spec.md

NEAR Intents demand monitor: bus-first source plan

Why websocket quote requests are still the MVP demand signal

Public solver quote requests remain the closest thing to live demand because they appear when a user or integration asks the network for executable pricing. They are still the right upstream source, but the runtime architecture is now bus-first rather than terminal-first.

Why this source wins for a first monitor:

• Most real-time: quote requests arrive before settlement and usually before a completed trade is visible anywhere else.
• Closer to intent formation: they reflect active user demand, not just historical outcomes.
• Operationally simple: a single websocket feed can drive the ingest side without indexing chains, scraping dashboards, or correlating multiple APIs.
• Good enough for ranking demand: even if quotes do not always become fills, repeated quote flow is still a strong indicator of what users are currently trying to do.

Tradeoffs vs other sources

Solver websocket quote requests

Pros:

• lowest-latency view of current demand
• directly tied to solver workflow
• suitable for a streaming ingest adapter
• can be normalized into pair, size, and frequency metrics immediately

Cons:

• quote requests are interest, not guaranteed executed volume
• public access may still be rate-limited, undocumented, or require credentials depending on environment
• schema and availability may change faster than user-facing products

Explorer

Explorer (https://explorer.near-intents.org/) is useful for validation and historical inspection, but it is usually a worse primary source for an MVP demand monitor.

Tradeoffs:

• better for human inspection than low-latency streaming
• likely shows processed/published activity instead of raw quote demand
• may lag the actual request path
• less convenient as a machine-first demand feed

Status dashboard / published status

Status (https://status.near-intents.org/posts/dashboard) is useful for system health, not demand discovery.

Tradeoffs:

• tells us whether the platform is up, degraded, or incident-affected
• does not represent per-request user demand
• coarse and aggregated by design

Published intents / settled outcomes

Published or completed intents are higher-confidence signals, but lower-fidelity for immediate demand sensing.

Tradeoffs:

• stronger evidence of actual execution
• misses abandoned demand and pre-trade discovery
• arrives later than quote traffic
• may require more indexing and entity correlation work

Runtime architecture

solver websocket quote stream
        |
        v
src/apps/near-intents-ingest.mjs
        |
        +--> raw.near_intents.quote
        |
        +--> norm.swap_demand
                     |
                     v
          src/apps/dummy-consumer.mjs

Responsibilities

src/apps/near-intents-ingest.mjs

• loads env from .env
• parses optional --pair 'asset_a->asset_b'
• connects to the NEAR Intents websocket
• subscribes to quote and quote_status
• publishes raw venue envelopes to raw.near_intents.quote
• publishes normalized swap-demand envelopes to norm.swap_demand

src/apps/dummy-consumer.mjs

• consumes normalized events from norm.swap_demand
• logs observed demand as a placeholder for later strategy logic

Kafka / Redpanda layer

• broker endpoint comes from KAFKA_BROKERS
• Redpanda is supported through Kafka protocol compatibility
• topics are configurable via env and default to:
  • raw.near_intents.quote
  • norm.swap_demand

Assumptions and limitations

• The websocket is the best available MVP source, not a perfect truth source.
• Demand is approximated by quote requests, not by settled intents.
• Live endpoints require auth in practice; NEAR_INTENTS_API_KEY must be provided.
• Request schemas may evolve; the parser should tolerate missing fields.
• The current product is intentionally minimal: no database, no backfill, no reconciliation against chain state.
• The dummy consumer proves the decoupled flow but is not a strategy engine.

Run instructions

Install:

npm install

Start ingest:

npm run near-intents:ingest

Direct node entrypoint:

node src/apps/near-intents-ingest.mjs

Run with exact-pair filtering:

npm run near-intents:ingest -- --pair 'asset_a->asset_b'

Start dummy consumer:

npm run dummy-consumer

Direct node entrypoint:

node src/apps/dummy-consumer.mjs

Decision summary

For an MVP whose job is to answer "what are users asking for right now?", solver websocket quote requests are still the best first source because they are the most direct, timely, and stream-friendly signal. The implementation now routes that signal through Kafka/Redpanda topics so ingestion and downstream reaction can evolve independently.