Skip to content
parchmentdocs
Open app

Prices

Storage price reads and the display-only live price stream

Candles for several markets

get/markets/candles

Query parameters

  • marketsstringrequired

    Comma-separated market object ids (required): 1 to 64 once normalized and de-duplicated, the first of each kept in request order.

    Example0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645
  • resolutionstringrequired

    Candle interval, aligned on the Unix epoch (UTC): 1s, 5s, 15s, 1m, 5m, 15m, 1h, 4h or 1d (required). 1s, 5s and 15s reach back only as far as the service keeps its 1 s Lazer bars (7 days by default).

    One of1s5s15s1m5m15m1h4h1d
  • fromMsstring

    Inclusive start, milliseconds; same rules as the prices fromMs. Raised to the start of the limit-th newest interval up to toMs.

    Example1796590800000
  • toMsstring

    Inclusive end, milliseconds (default: the end of the current interval, so a batch reads one window); same rules as the prices fromMs.

    Example1796677200000
  • limitstring

    Newest intervals read: canonical decimal from 1 (default and at most 500; larger values are clamped by the service); an empty value is omitted.

    Pattern^(0|[1-9][0-9]*)$
    Example50

Responses

  • The candles of each market, as GET /markets/{id}/candles answers them (same cache entries), with one window for the batch. A market whose read fails (unknown market, service error, or no answer within 15 s for the whole batch) carries that read's error instead; the rest still succeed. Cache-Control as on the single-market route for the oldest answer, or no-store when any series is an error.

    application/json

    • dataCandlesBatchrequired

      One series per requested market, in request order.

      • resolutionstringrequired

        The requested resolution.

        One of1s5s15s1m5m15m1h4h1d
      • seriesobject[]required
      • serverTimeMsstringrequired

        When the answer was assembled, Unix milliseconds.

        Pattern^-?(0|[1-9][0-9]*)n$
        Example1767225600000n

Example request

curl 'https://api.parchment.trade/markets/candles?markets=0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645&resolution=1s'
const res = await fetch("https://api.parchment.trade/markets/candles?markets=0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645&resolution=1s");
const { data } = await res.json();

Example response (200)

application/json
{
  "data": {
    "resolution": "1s",
    "series": [
      {
        "candles": [
          {
            "closeWad": "74250000000000000000n",
            "highWad": "74810000000000000000n",
            "lowWad": "73620000000000000000n",
            "openWad": "74250000000000000000n",
            "timeMs": "1796677200000n"
          }
        ],
        "marketId": "0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645"
      }
    ],
    "serverTimeMs": "1767225600000n"
  }
}

Candles

get/markets/{id}/candles

Path parameters

  • idstringrequired

    Market object id

    Pattern^(0[xX])?[0-9a-fA-F]{1,64}$
    Example0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645

Query parameters

  • resolutionstringrequired

    Candle interval, aligned on the Unix epoch (UTC): 1s, 5s, 15s, 1m, 5m, 15m, 1h, 4h or 1d (required). 1s, 5s and 15s reach back only as far as the service keeps its 1 s Lazer bars (7 days by default).

    One of1s5s15s1m5m15m1h4h1d
  • fromMsstring

    Inclusive start, milliseconds; same rules as the prices fromMs. Raised to the start of the limit-th newest interval up to toMs.

    Example1796590800000
  • toMsstring

    Inclusive end, milliseconds (default: the end of the current interval, so a batch reads one window); same rules as the prices fromMs.

    Example1796677200000
  • limitstring

    Newest intervals read: canonical decimal from 1 (default and at most 500; larger values are clamped by the service); an empty value is omitted.

    Pattern^(0|[1-9][0-9]*)$
    Example50

Responses

  • OHLC candles of the market's price points in the newest limit intervals of [fromMs, toMs], oldest first; an interval without a price point has no candle, except that 1s and 5s fill a quiet slot of a live 15 s bucket with a flat candle at the previous close. Answers are cached for 2 s, and served up to 10 s old while one refresh runs; 1s answers are cached for 0.5 s and served up to 1.5 s old, 5s and 15s for 1 s and up to 3 s, 4h and 1d for 15 s and up to 60 s. Concurrent misses share one service read per request key. Cache-Control: public, max-age=86400, immutable when the answer was read once toMs was before the current interval and at least 10 minutes old; otherwise public, with max-age and stale-while-revalidate the whole seconds left of the answer's cache windows above.

    application/json

    • dataCandlesrequired

      Oldest first; an interval without a price point has no candle.

      • candlesCandle[]required
        • closeWadstringrequired

          Scaled by 1e18 (WAD).

          Pattern^-?(0|[1-9][0-9]*)n$
          Example74250000000000000000n
        • highWadstringrequired

          Scaled by 1e18 (WAD).

          Pattern^-?(0|[1-9][0-9]*)n$
          Example74810000000000000000n
        • lowWadstringrequired

          Scaled by 1e18 (WAD).

          Pattern^-?(0|[1-9][0-9]*)n$
          Example73620000000000000000n
        • openWadstringrequired

          Scaled by 1e18 (WAD).

          Pattern^-?(0|[1-9][0-9]*)n$
          Example74250000000000000000n
        • timeMsstringrequired

          Milliseconds.

          Pattern^-?(0|[1-9][0-9]*)n$
          Example1796677200000n

Example request

curl 'https://api.parchment.trade/markets/0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645/candles?resolution=1s'
const res = await fetch("https://api.parchment.trade/markets/0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645/candles?resolution=1s");
const { data } = await res.json();

Example response (200)

application/json
{
  "data": {
    "candles": [
      {
        "closeWad": "74250000000000000000n",
        "highWad": "74810000000000000000n",
        "lowWad": "73620000000000000000n",
        "openWad": "74250000000000000000n",
        "timeMs": "1796677200000n"
      }
    ]
  }
}

Price history

get/markets/{id}/prices

Path parameters

  • idstringrequired

    Market object id

    Pattern^(0[xX])?[0-9a-fA-F]{1,64}$
    Example0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645

Query parameters

  • fromMsstring

    Inclusive start, milliseconds: canonical decimal (digits only, no sign, whitespace or leading zero), 0 to 18446744073709551615, else 400 bad_request (negative and empty included).

    Pattern^(0|[1-9][0-9]*)$
    Example1796590800000
  • toMsstring

    Inclusive end, milliseconds; same rules as fromMs.

    Example1796677200000
  • limitstring

    Page size: canonical decimal (digits only, no sign, whitespace or leading zero), 1 to 18446744073709551615, else 400 bad_request; an empty value is omitted.

    Pattern^(0|[1-9][0-9]*)$
    Example50

Responses

  • application/json

    • dataPriceHistoryrequired

      Oldest point first.

      • pointsPricePoint[]required
        • priceWadstringrequired

          Scaled by 1e18 (WAD).

          Pattern^-?(0|[1-9][0-9]*)n$
          Example74250000000000000000n
        • sourcestringrequired

          Where a price point was observed.

          One offillstorage
        • timestampMsstringrequired

          Milliseconds.

          Pattern^-?(0|[1-9][0-9]*)n$
          Example1796677200000n
        • twapWadstring | null

          Scaled by 1e18 (WAD).

          Pattern^-?(0|[1-9][0-9]*)n$
          Example74250000000000000000n

Example request

curl 'https://api.parchment.trade/markets/0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645/prices'
const res = await fetch("https://api.parchment.trade/markets/0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645/prices");
const { data } = await res.json();

Example response (200)

application/json
{
  "data": {
    "points": [
      {
        "priceWad": "74250000000000000000n",
        "source": "fill",
        "timestampMs": "1796677200000n",
        "twapWad": "74250000000000000000n"
      }
    ]
  }
}

Prices

get/prices

Responses

  • Latest storage reads. status is price_unavailable when the storage has not been read or decoded.

    application/json

    • dataPricesrequired
      • marketsMarketPrice[]required
      • pinsPricePin[]required

Example request

curl 'https://api.parchment.trade/prices'
const res = await fetch("https://api.parchment.trade/prices");
const { data } = await res.json();

Example response (200)

application/json
{
  "data": {
    "markets": [
      {
        "ageMs": "1200n",
        "confWad": "30000000000000000n",
        "indicative": true,
        "maxAgeMs": "6000n",
        "priceWad": "74250000000000000000n",
        "reason": "string",
        "spreadSource": "floor",
        "spreadWad": "40000000000000000n",
        "stale": true,
        "status": "live",
        "storageId": "0x36d5377cee4c4a61087f999a9c137472ab8daa75ce225ec82d9e5f4ac1fb12bd",
        "timestampMs": "1796677200000n",
        "twapWad": "74250000000000000000n",
        "marketId": "0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645",
        "symbol": "WTI"
      }
    ],
    "pins": [
      {
        "ageMs": "1200n",
        "lazerFeedId": "1398n",
        "priceWad": "74250000000000000000n",
        "reason": "string",
        "sourceId": "2n",
        "stale": true,
        "status": "live",
        "storageId": "0x36d5377cee4c4a61087f999a9c137472ab8daa75ce225ec82d9e5f4ac1fb12bd",
        "symbol": "WTI",
        "timestampMs": "1796677200000n",
        "twapWad": "74250000000000000000n"
      }
    ]
  }
}

Live price stream (SSE)

get/prices/stream

Query parameters

  • marketsstring

    Comma-separated market object ids (at most 64); omitted streams every market

    Example0x6e6238eb4f69bfcc3e884a7d20904eb0995ca2e42c95dc8560d5a417486ab645

Responses

  • Server-Sent Events, display only (charts; marks, fills and PnL use the storage price). A retry: 1000 hint first; price events { marketId, symbol, priceWad, timestampMs } (n-suffixed decimal strings, priceWad 1e18-scaled), at most 10 per second per market, never a market's price twice or backwards, each market's latest first; unavailable events { marketId } when a market whose price was sent stops being current (a stalled feed, or the gateway reconnecting upstream): show its last price as stale until its next price event, which may repeat it; heartbeat { timestampMs } every 10 s. The stream ends after 54 to 60 minutes, or after 30 s of downstream backpressure.

    text/event-stream

    string

Example request

curl -N 'https://api.parchment.trade/prices/stream' \
  -H 'Accept: text/event-stream'
const events = new EventSource("https://api.parchment.trade/prices/stream");
events.onmessage = (event) => console.log(JSON.parse(event.data));

Example response (200)

text/event-stream
data: "string"