# Wickfeed documentation

One envelope for every event type and every book. Get a key, subscribe to a topic, filter on the verdict. That is the whole integration.

## Delivery

Exclusively through npayload. There is no other realtime endpoint.

- Subscribe: https://npayload.com/feeds/wickfeed
- Command: `npx npayload subscribe wickfeed.lit`

## Quickstart

1. **Get an npayload key** — Wickfeed is a feed on npayload. Create a key, then subscribe to the wickfeed topic. There is no separate Wickfeed account to manage.
2. **Subscribe to a topic** — wickfeed.lit for the verdict, or wickfeed.* for all four event types. Per contract topics exist for a single race.
3. **Filter on the verdict** — Most agents want driver equal to information, attribution above a floor they choose, and a reaction of under. Three conditions and you are done.
4. **Replay when you need history** — Ask npayload for an offset and read the window again. Because our windows are event time ordered, the replay is byte identical to what was published live.

## Topics

- `wickfeed.moved` — The mid crossed this contract adaptive threshold. Deterministic, no model in the path. (~90ms)
- `wickfeed.mouth` — A watched source spoke about this contract, with relevance and novelty attached. (~90ms)
- `wickfeed.print` — An official result, filing or document landed from a tracked source. (~90ms)
- `wickfeed.lit` — A qualifying move and a novel, relevant cause coincided. Carries the verdict. This is the product. (~3000ms, carries the verdict)

## Envelope

All four event types share this shape. moved, mouth and print omit the verdict object; only lit carries it.

### Identity

| Field | Type | Notes |
|---|---|---|
| `type` | string | wickfeed.<kind>.v<n> |
| `wick_id` | string | Deterministic. Stable across redelivery, so a duplicate is safe to discard. |
| `prev_wick_id` | string | null | Previous wick for this identifier. Forms a chain per contract. |
| `id` | string | The canonical wf: identifier. |
| `book` | string | midterms, fed, sports, geopol, crypto. |
| `venue` | string | Where this observation came from. |
| `venue_ref` | string | That venue’s own identifier for the contract. |

### Time

| Field | Type | Notes |
|---|---|---|
| `event_time` | ISO 8601 | The source’s timestamp. Windows are ordered by this, never by arrival. |
| `emit_time` | ISO 8601 | When Wickfeed published. |
| `late` | boolean | True when this arrived after we had already judged that moment. It never rewrites a signal you were already sent. |

### Price

| Field | Type | Notes |
|---|---|---|
| `mid` | number | 0.0 to 1.0. |
| `delta` | number | Signed change across the window. |
| `window_s` | integer | Window length in seconds. |
| `threshold` | number | The adaptive threshold in force for this contract when it fired. |

### Verdict (lit only)

| Field | Type | Notes |
|---|---|---|
| `verdict.driver` | enum | information, liquidity, unknown. |
| `verdict.attribution` | number | 0.00 to 1.00. Confidence the named cause produced the move. |
| `verdict.reaction` | enum | under, proportionate, over, unknown. |
| `verdict.reaction_gap` | number | null | How far from proportionate, in probability points. |
| `verdict.confidence` | number | The judge’s confidence in the whole verdict. |

### Cause

| Field | Type | Notes |
|---|---|---|
| `cause.kind` | enum | mouth, print, flow. |
| `cause.source` | string | The account, agency or venue actually observed. |
| `cause.source_class` | enum | candidate, official, agency, pundit, crowd. |
| `cause.authority` | enum | high, medium, low. Learned from the archive. |
| `cause.relevance` | integer | 0 to 100. |
| `cause.novelty` | integer | 0 to 100. First mention of a fact scores 100. |
| `cause.stance` | enum | pro_yes, pro_no, unclear. Never a sentiment score. |
| `cause.lag_s` | integer | Seconds between cause and move. Negative means the cause followed the move. |

## Versioning

Your handler should tolerate unknown fields and unknown enum values. If it does, adding the 2028 book will never break a running agent.

- No version bump: Adding a field, Adding a new book, venue or source, Adding a new enum value, Adding a new event type
- Requires a bump: Removing a field, Changing the meaning of a field, Narrowing an enum

Anything in the left column ships without a version bump, which is exactly why consumers must tolerate what they do not recognize.

## Example

```json
{
  "type": "wickfeed.lit.v1",
  "wick_id": "wick_01JQ8F3K2M7XNRV4T9Z0BC5D",
  "prev_wick_id": "wick_01JQ8F1A9H4KPMS2W7Y6XE3B",
  "id": "wf:us-senate-ga-2026",
  "book": "midterms",
  "venue": "polymarket",
  "venue_ref": "0x747dc809fb79e1b05be09c42d6179459a58de2ef",
  "event_time": "2026-11-03T19:04:12.331Z",
  "emit_time": "2026-11-03T19:04:13.902Z",
  "late": false,
  "mid": 0.58,
  "delta": 0.04,
  "window_s": 300,
  "threshold": 0.031,
  "verdict": {
    "driver": "information",
    "attribution": 0.79,
    "reaction": "under",
    "reaction_gap": 0.021,
    "confidence": 0.82,
    "cause": {
      "kind": "mouth",
      "source": "@ossoff",
      "source_class": "candidate",
      "authority": "high",
      "relevance": 94,
      "novelty": 100,
      "stance": "pro_yes",
      "lag_s": 240,
      "ref": "https://x.com/..."
    }
  },
  "corroboration": [
    {
      "kind": "print",
      "source": "AP",
      "relevance": 88,
      "novelty": 42,
      "lag_s": 148
    }
  ]
}
```

## Machine readable artifacts

- [/llms.txt](https://wickfeed.com/llms.txt) — Curated index for an LLM. Start here.
- [/llms-full.txt](https://wickfeed.com/llms-full.txt) — Everything inlined in one fetch.
- [/asyncapi.json](https://wickfeed.com/asyncapi.json) — AsyncAPI 3.0 spec: channels, operations, messages.
- [/schema/envelope.v1.json](https://wickfeed.com/schema/envelope.v1.json) — JSON Schema for the event envelope.
- [/ids.json](https://wickfeed.com/ids.json) — The wf: identifier registry. Free, no key.
- [/schema/id-entry.v1.json](https://wickfeed.com/schema/id-entry.v1.json) — JSON Schema for a registry entry.
- [/examples/lit.json](https://wickfeed.com/examples/lit.json) — A verdict carrying event.
- [/examples/unknown.json](https://wickfeed.com/examples/unknown.json) — An honest unexplained move.
- [/examples/moved.json](https://wickfeed.com/examples/moved.json) — A move with no cause attached.
- [/agent.json](https://wickfeed.com/agent.json) — Discovery descriptor. Also at /.well-known/wickfeed.json
- [/docs.md](https://wickfeed.com/docs.md) — This documentation as markdown.