Market Data API

The Eden connector API provides a small, read-only market-data surface for external tools. It includes three GET endpoints:

Endpoint	What it returns
/v1/connectors/market-data/targets	Expected-move price targets for one option expiration
/v1/connectors/market-data/levels	P-Trans and N-Trans levels computed from one expiration’s GEX ladder
/v1/connectors/market-data/market-structure	Completed daily, weekly, or monthly structure and momentum

These endpoints do not return a raw option chain or OHLC candles. Each response is a smaller, computed data product intended for connector use.

Muse invocation keyword

When this connector is used in Muse, Eden is the invocation keyword. A user can begin a request with “Eden” to tell Muse to use Eden market data.

Examples:

• “Eden, show me the next SPY price targets.”
• “Eden, where are SPY P-Trans and N-Trans?”
• “Eden, what is the weekly market structure for QQQ?”

Muse should treat Eden as a case-insensitive connector keyword, not as a ticker symbol or an API query value. The words after “Eden” provide the symbol, data request, expiration, or timeframe. If a user says only “Eden,” Muse should ask what symbol and market data they want.

Base URL

https://api.edentrading.xyz

All requests use GET. Do not send a request body.

Authentication

Send your Eden API key as a Bearer token on every request:

Authorization: Bearer <Eden API key>

The key must include the market-data:read scope. Keep the key on your server or in your connector’s secret store. Do not place it in public browser code, logs, URLs, or source control.

Example:

curl "https://api.edentrading.xyz/v1/connectors/market-data/targets?symbol=SPY&expiration=next" \
  --header "Authorization: Bearer eden_live_REDACTED"

Authentication errors use this format:

{
  "error": {
    "code": "unauthorized",
    "message": "A valid Eden API key is required."
  }
}

An authorized key without market-data:read receives HTTP 403:

{
  "error": {
    "code": "insufficient_scope",
    "message": "The API key cannot read market data."
  }
}

Rate limits

The current default limit is 60 requests per 60-second window per API-key record. The same quota is shared by all three connector endpoints; it is not a separate limit for each route. Your deployment’s configured limit may differ.

The fixed window begins with the first request in that window. It does not reset at the top of each clock minute. Each authenticated connector request uses one unit. A limited request receives HTTP 429, a Retry-After response header in seconds, and this body:

{
  "error": {
    "code": "rate_limited",
    "message": "API key request limit exceeded."
  },
  "retryAfterSeconds": 18
}

Wait for the larger of Retry-After or retryAfterSeconds before trying again. Market structure can also return a 429 when historical-data provider capacity is temporarily limited.

Price targets

Returns expiration-scoped expected-move price targets that Eden has already computed. It does not return the contracts or quotes used to produce them.

Request

GET /v1/connectors/market-data/targets?symbol=SPY&expiration=next

Query parameters

Parameter	Required	Values	Default	Meaning
symbol	Yes	Supported ticker, such as SPY	—	Symbol to analyze; normalized to uppercase
expiration	No	next or an ISO date such as 2026-10-09	next	Earliest available expiration or one exact expiration

Aliases such as weekly and monthly are not accepted. Use next or YYYY-MM-DD.

Successful response

HTTP 200 returns schema eden.connector.price-targets.v1:

{
  "schema": "eden.connector.price-targets.v1",
  "symbol": "SPY",
  "instrumentType": "equity",
  "expiration": "2026-10-09",
  "computedAt": "2026-10-04T14:31:08.412Z",
  "providerTimestamp": "2026-10-04T14:15:00.000Z",
  "feed": "delayed",
  "units": {
    "price": "USD",
    "move": "USD"
  },
  "spotPrice": 671.42,
  "ageSeconds": 12.8,
  "dataStatus": "fresh",
  "targets": [
    {
      "lower": 663.18,
      "upper": 679.66,
      "move": 8.24,
      "formula": "gextron_max_move_v1"
    }
  ],
  "meta": {
    "snapshotId": "SPY:2026-10-04T14:31:08.412Z"
  }
}

targets can contain more than one item for an index when more than one option root shares the chosen expiration. Index target items may also contain:

{
  "seriesId": "SPXW:2026-10-09:pm",
  "root": "SPXW",
  "settlement": "pm",
  "expirationTime": "2026-10-09T20:00:00.000Z"
}

Those index fields are series details. They do not contain a raw chain.

Field notes

• computedAt is when Eden published the snapshot used by the response.
• providerTimestamp is the provider observation time and can be null.
• feed identifies the feed as delayed.
• ageSeconds is the age of the published snapshot when the request is served.
• dataStatus is fresh or stale under Eden’s configured snapshot age limit. A stale response can still be HTTP 200.
• lower and upper are the expected-move price bounds, while move is the expected move in USD.
• formula identifies the calculation version.

Key levels

Returns GEX P-Trans and N-Trans transition levels for one chosen expiration ladder. It does not return the full option chain or an all-expiration GEX curve.

For an index, Eden combines matching series for the chosen expiration by strike before finding the transitions. Four consecutive available strikes with the same non-zero sign establish a transition. A zero value breaks the sequence.

Request

GET /v1/connectors/market-data/levels?symbol=SPY&expiration=next

Query parameters

Parameter	Required	Values	Default	Meaning
symbol	Yes	Supported ticker, such as SPY	—	Symbol to analyze; normalized to uppercase
expiration	No	next or an ISO date such as 2026-10-09	next	Earliest available expiration or one exact expiration

Successful response

HTTP 200 returns schema eden.connector.key-levels.v1:

{
  "schema": "eden.connector.key-levels.v1",
  "symbol": "SPY",
  "instrumentType": "equity",
  "expiration": "2026-10-09",
  "computedAt": "2026-10-04T14:31:08.412Z",
  "providerTimestamp": "2026-10-04T14:15:00.000Z",
  "feed": "delayed",
  "units": {
    "strike": "USD",
    "netGex": "USD"
  },
  "spotPrice": 671.42,
  "ageSeconds": 12.8,
  "dataStatus": "fresh",
  "levels": {
    "version": "gex_transitions_v1",
    "spot": 671.42,
    "pTrans": {
      "status": "established",
      "strike": 675,
      "confirmationStrikes": [675, 676, 677, 678]
    },
    "nTrans": {
      "status": "established",
      "strike": 668,
      "confirmationStrikes": [668, 667, 666, 665]
    },
    "priceState": "drunken_sailor"
  },
  "meta": {
    "snapshotId": "SPY:2026-10-04T14:31:08.412Z",
    "methodology": "four_consecutive_nonzero_same_sign_strikes_v1",
    "includedSeries": [],
    "ladderPointCount": 94
  }
}

Each transition is either established or not established. A missing transition has this exact shape:

{
  "status": "not_established",
  "strike": null,
  "confirmationStrikes": []
}

priceState is one of above_p_trans, at_p_trans, drunken_sailor, at_n_trans, below_n_trans, partial, or unestablished. partial means only one transition was established. unestablished means neither was established.

For equity and ETF responses, meta.includedSeries is empty. For index responses, it lists the series IDs combined for the chosen expiration. ladderPointCount is the number of strike rows used in the transition calculation.

The timestamps and freshness fields have the same meaning as the price-target response.

Market structure

Returns the completed daily, weekly, and monthly market-structure view for an equity or ETF. It summarizes the current regime, swing levels, range position, momentum, and prices that would confirm continuation or reversal. It does not return raw OHLC candles. Index symbols are not supported.

Request

GET /v1/connectors/market-data/market-structure?symbol=SPY&timeframes=1D,1W,1M

Query parameters

Parameter	Required	Values	Default	Meaning
symbol	Yes	Supported equity or ETF ticker	—	Symbol to analyze; normalized to uppercase
timeframes	No	Comma-separated 1D, 1W, 1M	1D,1W,1M	Return only the selected completed-period views

Each timeframe is computed independently from split-adjusted daily price history. The newest unfinished calendar period is excluded.

Successful response

HTTP 200 returns schema eden.market-structure.v1:

{
  "schema": "eden.market-structure.v1",
  "symbol": "SPY",
  "instrumentType": "equity",
  "computedAt": "2026-10-04T15:00:00.000Z",
  "dataStatus": "fresh",
  "timeframes": [
    {
      "timeframe": "1D",
      "asOf": "2026-10-02",
      "status": "ready",
      "structure": {
        "regime": "bullish",
        "state": "intact",
        "swingLow": { "price": 650.1, "date": "2026-09-25" },
        "swingHigh": { "price": 675.3, "date": "2026-10-01" },
        "candidateSwingLow": null,
        "candidateSwingHigh": null,
        "rangePosition": 0.8,
        "rangePositionPercent": 80
      },
      "momentum": {
        "value": 5.1,
        "previousValue": 4.9,
        "state": "positive_rising",
        "direction": "bullish",
        "strength": "strengthening",
        "color": "light_green"
      },
      "confirmation": {
        "continuation": {
          "direction": "above",
          "price": 675.3,
          "requires": "price_break",
          "wouldConfirm": null
        },
        "reversal": {
          "direction": "below",
          "price": 650.1,
          "requires": "completed_close",
          "resultingRegime": "bearish"
        }
      },
      "latestEvent": null
    }
  ],
  "meta": {
    "priceBasis": "split_adjusted",
    "completedPeriodsOnly": true,
    "historyYears": 20,
    "dataSource": "parquet",
    "supportedInstrumentTypes": ["equity", "etf"]
  }
}

Example prices and states are illustrative. timeframes contains one object per requested timeframe. If history is insufficient, that object has status: "insufficient_history", structure: null, and momentum: null. meta.dataSource indicates whether the underlying prices came from the cache, archive, or historical provider.

Queued snapshots and retries

Price targets and key levels read computed option snapshots. If no snapshot exists yet, Eden queues a refresh and returns HTTP 202 with Retry-After: 3.

Targets example:

{
  "schema": "eden.connector.price-targets.v1",
  "symbol": "SPY",
  "dataStatus": "queued",
  "retryAfterSeconds": 3
}

Levels uses the same shape with schema eden.connector.key-levels.v1.

Wait at least the number of seconds in Retry-After, then repeat the same GET request. A 202 means the request was accepted, not that target or level data was returned.

Market structure does not use this snapshot-queue response. It reads cached history when available, then the stock-price archive, and can fall back to the historical provider.

Errors

Errors are JSON. The connector endpoints use a nested error object for the errors below.

Status	Code	Meaning
400	invalid_query	A required query parameter is missing or a value is invalid
400	invalid_symbol	The targets or levels symbol is invalid or unsupported
401	unauthorized	The Bearer token is missing, invalid, or not an Eden API key
403	insufficient_scope	The key does not include market-data:read
404	expiration_not_found	The requested target or GEX expiration is unavailable
429	rate_limited	The API-key budget or market-structure provider capacity was exceeded
503	authentication_unavailable	API-key verification is temporarily unavailable

Missing symbol:

{
  "error": {
    "code": "invalid_query",
    "message": "symbol is required."
  }
}

Invalid expiration syntax:

{
  "error": {
    "code": "invalid_query",
    "message": "expiration must be next or an ISO date"
  }
}

Expiration not found for targets:

{
  "error": {
    "code": "expiration_not_found",
    "message": "No computed target exists for that expiration."
  }
}

Expiration not found for levels uses the message No GEX ladder exists for that expiration.

Invalid market-structure selections return invalid_query, for example timeframes must contain only 1D, 1W, or 1M.

Freshness checklist

• For price targets and key levels, inspect computedAt, providerTimestamp, feed, ageSeconds, and dataStatus.
• Do not treat dataStatus: "stale" as current just because the request returned HTTP 200.
• For market structure, inspect each timeframe’s asOf date, status, and meta.dataSource.
• Market structure uses only completed periods; weekly and monthly structures update when their calendar periods finish.
• Honor Retry-After on 202 and 429 responses instead of retrying in a tight loop.