# 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

```text
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:

```bash
npm install
```

Start ingest:

```bash
npm run near-intents:ingest
```

Direct node entrypoint:

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

Run with exact-pair filtering:

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

Start dummy consumer:

```bash
npm run dummy-consumer
```

Direct node entrypoint:

```bash
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.