# NightWatch — Knowledge Graph for AI agents

NightWatch is a cross-exchange token intelligence Knowledge Graph. It tracks
tokens across ~10 crypto exchanges (global + Korean) and records, per token:
contract identity across chains, a proprietary A-F liquidity grade, per-venue
deposit/withdrawal status, and exchange listings.

## How to fetch a token note

    GET /kg/{TOKEN}.md        e.g.  GET /kg/BLAST.md

Returns one Obsidian-style markdown "wiki note" (media type
text/markdown) that lets an agent fetch a single URL and instantly know the
token. TOKEN is a ticker (BTC, BLAST, …); case-insensitive. Every note is a
LIVE render of the Knowledge Graph at request time — not a stored file. Unknown
tokens still return a valid note with an honest "limited coverage" line.

## Vault mirror

Obsidian vault mirror of this wiki, git-cloneable: https://github.com/jamboree777/thusus-vault

## Note structure

1. YAML frontmatter — the machine contract. Fields:
   - token            ticker (string)
   - type             always "token"
   - nw_grade         best-venue liquidity grade A-F, or null if ungraded
   - nw_grade_worst   worst-venue liquidity grade (omitted if unknown)
   - identity         contract-identity verdict:
                      verified_same | collision | partial | no_contract_data
   - contracts        list of { chain, address } (addresses quoted)
   - exchanges        array of exchange ids the token is listed on
   - korean_exchanges array of Korean exchange ids (subset of exchanges)
   - transfer         open | blocked | partial | unknown (derived from dep/wd)
   - asset_class      e.g. crypto (omitted if unknown)
   - updated          UTC ISO timestamp of this render
   - source           always "nightwatch-kg"
   A field NightWatch lacks is simply ABSENT (never faked); only nw_grade may
   be an explicit null.

2. Prose + sections: Identity, Grade by exchange, Deposit / Withdrawal,
   Related, Events, Backers & Project, Sources. When Thusus has shadowed this
   token, a "Thusus shadow-fund track record" dimension (paper/dry-run trade
   count, settled realized net USD, win rate, last trades) also renders on both
   tiers. When the community has contributed sourced claims, a "Community intel"
   dimension renders on both tiers: [verified] claims (passed review) and
   [community-reported, unverified] claims (pending, explicitly NOT facts).
   Submit a sourced claim via POST /kg/claim (source_url mandatory); list them
   via GET /kg/claims?base=. Pro-only sections (behind the API key): One Price
   (cross-exchange), Market Makers / microstructure, On-chain. Events (recent
   dep/wd status changes + lifecycle) and Backers (contribution scaffold) render
   on both tiers.

## Wikilink convention

[[wikilinks]] are the Knowledge Graph EDGES. A note links every exchange
([[bybit]], [[upbit]]), every chain ([[blast]]), the asset class
([[asset_class/crypto]]), and — on a ticker collision — a [[collision]] flag.
Deeper namespaces: [[event/...]] (dep/wd freeze/resume, delisting, suspension),
[[backer/...]] (project backers/team — contribution-filled), [[mm/...]]
(per-venue market-maker/microstructure). Link targets are plain and guessable
(lowercase ids / tickers).

## Honesty contract

Notes never fabricate a fact or a source. Missing data is omitted or stated as
"limited coverage". Sources listed at the foot of each note name only the KG
sweeps that actually fed that note.

source: nightwatch-kg

## Access & tiers

The token note is free to fetch, with two tiers:

  - free (no key): rate-limited to 30 requests / 60s per IP
    and served from a ~60s micro-cache (so it lags real-time by up to ~60s). You
    get the full core note — frontmatter, Identity, Grade by exchange,
    Deposit/Withdrawal, Related, Events, Backers & Project, Sources — plus a
    locked "Deep intelligence" teaser. Frontmatter carries `tier: free`.
  - pro (send header `X-NW-User-Key: <your key>`): unmetered (no rate limit),
    served from a shorter ~10s cache (near real-time), and richer — adds
    `nw_grade_7d`, dep/wd provenance, an OPEN "Deep intelligence" section
    that links the deep endpoints (One Price/arbitrage verify, order-book probe
    prescreen, per-venue grade detail, dep/wd change history), and three deep
    data sections rendered inline: One Price (cross-exchange spread + 24h
    recurrence), Market Makers / microstructure, and On-chain activity, plus
    the `one_price_actionable_pct`, `arb_hits_24h`, `mm_venues` frontmatter.
    Frontmatter carries `tier: pro`.

Get a key at /docs/api. The same key works as `X-NW-User-Key` across the API.

Roadmap (honest): usage-based metering — x402 / USDC pay-per-call — is planned,
so agents will be able to pay per request without a pre-provisioned key.

## Thusus shadow fund

GET /arb/thusus/fund — stateless reconstruction of the Thusus $10,000 virtual paper fund's current distribution across exchanges, replayed from shadow-trade history (balances, in-flight, topups, recent flows, realized net; never real capital).

GET /arb/thusus/attribution?dims=gap_cause,deviation_pattern&min_n=2 — slices settled shadow-trade P&L by the entry-time trade fingerprint (WHY the arb existed: gap_cause, asset_class, venue_pair, grade asymmetry, spread/depth/size buckets, anchor_leg, deviation_pattern). Marginals per dimension plus `a+b` pair combos; reports fingerprint_coverage (older rows carry no fingerprint and are excluded).

GET /arb/insights?days=14 — Insight Engine v1: deterministic plain-English editorial cards derived from recurring-gap + deposit/withdraw + anomaly data. Two detectors, no LLM: venue_drain (a venue is the habitual cheap side of recurring gaps, i.e. arbitrage flow keeps draining it) and mm_signal (repeated deposit/withdraw suspensions plus a volume/microburst anomaly within ~48h on the same token@exchange — pattern consistent with market-maker operations). Every card is verified against exchange notices (7d) + community evaluations and carries a status; a venue suspending dep/wd across >=10 tokens is promoted to a single venue_risk card. Informational, not financial advice.

source: nightwatch-kg