Event Correlation#

Artery's biggest value-add over per-provider SDKs is a single API that treats the same real-world question as one event — even though Polymarket, Kalshi, and Hyperliquid HIP-4 use completely different identifiers and metadata schemas.

The problem#

The same question shows up everywhere differently:

There is no external authority that maps these. Artery builds the mapping itself.

Structured parsers (current)#

For crypto price-binary markets, all three providers expose enough structure to parse without NLP:

textHIP-4 description:  class:priceBinary|underlying:BTC|expiry:20260509-0600|targetPrice:79583
                    ↓ parse
                    { underlying: 'BTC', threshold: 79583, op: 'gte', expiresAt: '2026-05-09T06:00:00Z' }
 
Kalshi ticker:      KXBTCD-26MAY0917-T69999.99
                    ↓ parse
                    { underlying: 'BTC', threshold: 69999.99, op: 'gte', expiresAt: '2026-05-09T17:00:00Z' }
 
Polymarket question: "Will the price of Bitcoin be above $70,000 on May 9?"
                     ↓ regex + endDateIso
                    { underlying: 'BTC', threshold: 70000, op: 'gte', expiresAt: '2026-05-09T00:00:00Z' }

Canonical clustering key#

Each parsed market is hashed into a canonical key; markets sharing a key join the same ArteryEvent:

textcanonical_key = `${underlying}|${op}|${round(threshold)}|${YYYY-MM-DD}`
            = "BTC|gte|70000|2026-05-09"

Day-level (rather than full-timestamp) precision lets Polymarket "by May 9" cluster with Kalshi "26MAY0917" — they resolve on the same trading day.

What gets clustered today#

Live numbers from a recent run:

The Polymarket vs Kalshi pair is the most active cluster because both venues list dense daily price-binary grids. HIP-4 is sparse (1 market today) and its strikes (e.g. $79,583) rarely match other venues' round-number strikes.

Endpoints#

bashcurl 'https://api.artery.questflow.ai/v1/events?underlying=BTC&min_providers=2&limit=5' \
  -H "Authorization: Bearer $TOKEN"

json{
  "events": [
    {
      "universalId": "evt_94c9a200-8152-43b1-8b10-46214bea101a",
      "canonicalName": "BTC ≥ $70,000 by 2026-05-09",
      "kind": "price_binary",
      "underlying": "BTC",
      "threshold": 70000,
      "op": "gte",
      "resolutionDate": "2026-05-09T00:00:00Z",
      "links": [
        {
          "provider": "polymarket",
          "providerMarketId": "0xa8aceb0fb04828602057be...",
          "source": "regex_title",
          "metadata": {
            "yesTokenId": "55007456209846753968...",
            "noTokenId":  "10093425111459431137..."
          }
        },
        {
          "provider": "kalshi",
          "providerMarketId": "KXBTCD-26MAY0917-T69999.99",
          "source": "structured_ticker"
        }
      ]
    }
  ]
}

Filtering#

GET /v1/events supports the following query params:

Recent additions#

What this is not (yet)#

• Election / outcome / sports markets are not clustered yet — they need entity-NER + temporal matching (roadmap)
• Approximate threshold matching — Polymarket "above $70k" and Kalshi T69999.99 happen to round to the same $70K bucket, but T69500 would NOT cluster with $70K (roadmap)
• Embedding-based clustering for long-tail markets (roadmap)
• Postgres persistence of registry + settlement history (roadmap)

How parsers fail (and that's OK)#

Parsers return null for anything they can't handle. The reconcile loop silently drops nulls and only registers what it understands. So:

• Sports markets, custom event markets, jokes, and anything non-crypto → not in /v1/events
• Range markets (Kalshi has cap_strike + floor_strike) → not yet parsed
• class:other HIP-4 outcomes → not parsed

This keeps the registry tight and high-confidence. Recent versions progressively relaxes parsers as we add NER + embedding fallbacks.

Reconcile schedule#

The reconcile job runs:

• Once on app bootstrap (1.5s after listen)
• Every 5 minutes thereafter
• On-demand via POST /v1/events/reconcile (admin scope)

Disable with ART_RECONCILE_OFF=true (useful for tests where upstream calls are noisy).

See also#

• Cross-platform spread recipe — using /v1/events/:id/spread to find arbitrage edges
• Native vs Normalized — wire shape