# near-intents-monitor

Minimal event-driven POC for the first trading-system component:

- **venue ingest**: NEAR Intents solver-bus quote flow
- **central bus**: Redpanda / Kafka-compatible broker
- **dummy reactor**: placeholder consumer for later trade-decision logic

## Architecture

```text
NEAR Intents WebSocket
        |
        v
src/apps/near-intents-ingest.mjs
        |
        +--> raw.near_intents.quote
        |
        +--> norm.swap_demand
                     |
                     v
       src/apps/dummy-consumer.mjs
```

The ingest app connects to the NEAR Intents websocket, subscribes to `quote` and `quote_status`, normalizes quote demand, and publishes to a Kafka-compatible topic.

## Project structure

```text
src/
  apps/
    near-intents-ingest.mjs
    dummy-consumer.mjs
  bus/
    kafka/
      producer.mjs
      consumer.mjs
  core/
    event-envelope.mjs
    log.mjs
    pair-filter.mjs
  lib/
    env.mjs
    config.mjs
  venues/
    near-intents/
      ingest.mjs
      normalize.mjs
      ws.mjs
```

## Environment

Create `.env` in repo root:

```env
NEAR_INTENTS_API_KEY=your_solver_jwt
NEAR_INTENTS_WS_URL=wss://solver-relay-v2.chaindefuser.com/ws
KAFKA_BROKERS=127.0.0.1:9092
KAFKA_CLIENT_ID=trading-system
KAFKA_TOPIC_NORM_SWAP_DEMAND=norm.swap_demand
KAFKA_CONSUMER_GROUP_DUMMY=dummy-reactor-v1
```

### Broker notes

- `KAFKA_BROKERS` accepts a comma-separated broker list.
- Redpanda works because the apps use the Kafka protocol via `kafkajs`.
- `src/lib/config.mjs` is the shared config loader for both app entrypoints.
- The ingest app publishes normalized quote-demand events to `norm.swap_demand` by default.

## Install

```bash
npm install
```

## Run

### Start NEAR Intents ingest

Use the package script:

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

Or run the app directly:

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

Optional exact-pair filter:

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

Example:

```bash
npm run near-intents:ingest -- --pair 'nep141:btc.omft.near->nep141:gnosis-0x420ca0f9b9b604ce0fd9c18ef134c705e5fa3430.omft.near'
```

The filter is direction-agnostic, so `asset_a->asset_b` also matches `asset_b->asset_a`.

### Start the dummy consumer

Use the package script:

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

Or run the app directly:

```bash
node src/apps/dummy-consumer.mjs
```

The dummy consumer subscribes to `norm.swap_demand`, logs the observed pair and quote id, and stands in for a future decision engine.

## Scripts

- `npm run near-intents:ingest` — start the websocket ingest and publish to Kafka/Redpanda topics
- `npm run dummy-consumer` — consume normalized demand events
- `npm start` — legacy wrapper that forwards into the ingest app

## Notes

- This repo is now bus-first: venue intake and downstream reaction are decoupled through Kafka-compatible topics.
- `index.mjs` remains only as a compatibility launch wrapper; operational docs should prefer `src/apps/*` entrypoints and npm scripts.
- Older single-file, Python, or TUI-only runtime instructions are obsolete for this repository state.