On this page

Native vs Normalized

Artery's default response is a native passthrough layer: every response carries the upstream provider's raw shape, unmodified, inside a native field. An optional normalized field is added on responses where semantics align across providers — opt in with a header (see below).

The native shape is preserved indefinitely. Normalization is additive.

The envelope

Every data endpoint returns:

json{
  "native": {
    /* raw upstream JSON, byte-for-byte */
  },
  "meta": {
    "provider": "polymarket",
    "fetchedAt": "2026-05-08T12:00:00.000Z",
    "source": "live"
  }
}

Field	Type	Description
`native`	provider-specific	Upstream JSON unmodified — including any provider quirks
`meta.provider`	enum	One of `polymarket`, `kalshi`, `hyperliquid`, `hyperliquid_hip4`, `hyperliquid_dex`
`meta.fetchedAt`	ISO-8601	Server-side timestamp at the moment of upstream fetch
`meta.source`	enum	`live` (direct upstream) or `indexed` (Artery indexer cache)

Tip

The envelope is the only transformation Artery applies in the native path. Field names, casing, units, and ID formats inside native are exactly as upstream returns them. If Polymarket renames a field tomorrow, your call sees the new name within minutes.

Why native first?

Predictable, contract-stable code at the cost of slightly more parsing on the client. Three reasons:

Schema churn. Polymarket Gamma, Kalshi, and HL HIP-4 all ship breaking changes monthly. A normalized layer that wraps moving targets either lags or gets noisy.
Information loss. Kalshi quotes Yes and No as two separate orderbooks that arbitrage to $1. Polymarket quotes a single book with side. There is no lossless single shape — pick early and you choke recipes.
Trust. Quants want to verify against upstream docs. native means what they read on docs.polymarket.com is what their code consumes.

Normalized responses

The normalized layer adds optional unified shapes on responses where semantics align:

json{
  "native": {
    /* unchanged */
  },
  "meta": {
    /* unchanged */
  },
  "normalized": {
    "kind": "binary_market",
    "yesPrice": 0.62,
    "noPrice": 0.38,
    "expiresAt": "2026-12-31T23:59:00Z",
    "_divergence": []
  }
}

The contract:

Native shape is always preserved — no breaking change at the switchover.
Normalize only where a clean cross-provider mapping exists. We will not invent fake fields just to fit the schema.
_divergence lists places the normalization had to make a judgment call (e.g. "Kalshi reports yes_bid_dollars; we used the higher-volume side").

Opt-in via header

Normalized responses are requested by setting X-Artery-Normalize: 1. Without the header, responses ship the native envelope only.

bashcurl https://api.artery.questflow.ai/v1/polymarket/markets/0xCONDITION_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Artery-Normalize: 1"

When to normalize, when to stay native

Stay native

Building a single-provider product. Need every upstream field. Tracking schema changes is part of your job anyway.

Normalize

Cross-provider arbitrage. Multi-platform UI. Comparison dashboards where divergent shapes would force per-provider rendering branches.

Native vs Normalized#

The envelope#

Why native first?#

Normalized responses#

Opt-in via header#

When to normalize, when to stay native#

See also#