Developer Documentation

The Parity API provides programmatic access to Parity's outcome modeling engine. Use it to model collars, buffers, and covered calls for supported stocks and ETFs.

Base URL

https://outcomes.parityoutcomes.com

API Version

v1

Current Endpoints

Make your first request to model approximately one-year outcomes for SPY using a 10% downside target:

curl -X POST "https://outcomes.parityoutcomes.com/v1/outcomes" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "SPY",
    "days": 365,
    "downside_target_pct": 10
  }'

This request asks Parity to model approximately one-year outcomes for SPY using a 10% downside target.

Example Response (abbreviated)

{
  "api_version": "v1",
  "symbol": "SPY",
  "unit": { "shares": 100 },
  "request": { "days": 365, "downside_target_pct": 10 },
  "market": { "underlying_price": 521.34 },
  "expiration": { "date": "2027-08-19", "days_to_expiration": 365 },
  "expected_dividends": { "per_share": 4.12, "per_unit_dollars": 412.00 },
  "strategies": {
    "collar": {
      "status": "available",
      "strategy": "collar",
      "protection_type": "maximum_loss_floor",
      "summary": { "estimated_max_loss_pct": 10.0, "estimated_upside_cap_pct": 12.5 }
    },
    "buffer": { "status": "available", "strategy": "buffer", "..." : "..." },
    "covered_call": { "status": "available", "strategy": "covered_call", "..." : "..." }
  },
  "meta": { "generated_at": "2026-08-11T18:23:00Z" }
}

The full response contains detailed strategy structures, trade legs, and pricing. See the Response section for the complete contract.

Where to go next

• Retrieve supported securities → GET /v1/securities
• Explore protection levels → POST /v1/frontier
• Compare time horizons → POST /v1/horizons
• Compare securities → POST /v1/screen

Every protected Parity API request requires an API key using Bearer authentication.

Authorization: Bearer par_live_...

API keys can be created from Dashboard - API Access (Settings - API Access).

Recommended Architecture

User's application
        |
        v
Customer's backend/server
        |
        v
Parity API

Not recommended:

User's browser
        |
        v
Parity API  (secret embedded in JavaScript)

Keys should generally be stored in environment variables or a secrets manager.

Use GET /v1/securities to retrieve Parity's current supported-security universe before submitting symbols to a modeling endpoint. This endpoint returns availability metadata only. It does not model an outcome.

Parity exposes four modeling endpoints. Each answers a different question about protection outcomes. They are not redundant — choose the one that matches what you want to compare.

All four endpoints return the same complete strategy contract — option legs, per-leg quotes, package pricing, and executable / midpoint modeled outcomes.

Returns the current list of securities supported by Parity's options-data universe.

Parity refreshes this universe daily from current option contracts and serves the saved snapshot. Calling this endpoint does not open a new live market-data session.

Request

This endpoint does not accept a request body.

Example Request

curl "https://outcomes.parityoutcomes.com/v1/securities" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response (abbreviated)

{
  "symbols": [
    "AAPL",
    "MSFT",
    "NVDA",
    "QQQ",
    "SPY",
    "TSLA"
  ],
  "count": 5932,
  "newly_supported": [],
  "newly_supported_count": 0,
  "market_date": "2026-08-21",
  "as_of": "2026-08-24T02:26:20.285348+00:00",
  "stale": false
}

The symbols array is abbreviated. The production response includes the complete current universe.

Response Fields

Availability Meaning

A symbol appearing in symbols means current option contracts were present when Parity built the saved market snapshot. It does not guarantee that every strategy, investment horizon, downside target, or pricing mode will produce an eligible modeled outcome.

Use the relevant modeling endpoint to determine whether an eligible collar, buffer, or covered call is available for a specific request.

When to Use This Endpoint

Use /v1/securities to populate a supported ticker selector, validate a ticker before submitting a modeling request, monitor changes to Parity's supported universe, or identify recently supported securities.

Models Parity's supported outcome structures for one underlying security, investment horizon, and downside target.

Request Body

How the downside target is interpreted

• Collar: approximately the requested maximum-loss target.
• Buffer: approximately the requested first-loss buffer target.
• Covered call: approximately the requested downside cushion from option income and expected dividends.

Market availability and discrete option strikes mean actual modeled outcomes may differ from the exact requested target.

Explore the efficient outcome frontier for one security, strategy, and investment horizon.

The Frontier endpoint evaluates a range of target outcomes for a selected strategy and returns the distinct, non-dominated structures available across that range.

Supported strategies

• collar
• buffer
• covered_call

Each returned frontier point includes the modeled outcome, option structure, complete trade ticket, bid/mid/ask quotes, midpoint and executable package pricing, and marginal tradeoff information.

Request Body

How the target is interpreted

The meaning of the target depends on the selected strategy:

Market availability and discrete option strikes mean the actual modeled frontier metric may differ from the exact requested target.

Example Request

curl -X POST "https://outcomes.parityoutcomes.com/v1/frontier" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "SPY",
    "strategy": "buffer",
    "days": 365,
    "min_target_pct": 5,
    "max_target_pct": 15,
    "step_pct": 1
  }'

This asks Parity to evaluate SPY buffer outcomes from a 5% through 15% target in 1% increments.

Frontier Behavior

Parity evaluates each requested target using the same underlying market-data snapshot.

The endpoint then:

• removes duplicate option structures
• sorts results using the strategy's actual midpoint frontier metric
• removes dominated structures
• returns only distinct efficient outcomes

Efficient-frontier construction and dominance comparisons use executable modeled economics as the primary basis. Every frontier point returns both outcomes.executable and outcomes.midpoint, plus both executable and midpoint package pricing.

Because listed option strikes are discrete, the number of returned frontier points may be lower than the number of targets evaluated.

For example, a request evaluating 26 target values may return only 11 distinct efficient structures.

Response

The top-level response includes:

Example Response (abbreviated)

{
  "api_version": "v1",
  "symbol": "SPY",
  "strategy": "buffer",
  "frontier_definition": {
    "target_metric": "first_loss_buffer_pct",
    "frontier_metric": "effective_buffer_pct",
    "upside_metric": "upside_cap_pct"
  },
  "unit": {
    "shares": 100
  },
  "request": {
    "days": 365,
    "min_target_pct": 5,
    "max_target_pct": 15,
    "step_pct": 5,
    "targets_evaluated_pct": [
      5,
      10,
      15
    ]
  },
  "market": {
    "underlying_price": 772.51
  },
  "expiration": {
    "date": "2027-09-17"
  },
  "frontier": [
    {
      "status": "available",
      "strategy": "buffer",
      "target": {
        "downside_target_pct": 5
      },
      "summary": {
        "estimated_buffer_pct": 6.06,
        "estimated_upside_cap_pct": 20.62
      },
      "structure": {
        "long_put_strike": "...",
        "short_put_strike": "...",
        "short_call_strike": "..."
      },
      "trade": {
        "legs": [
          "... three option legs ..."
        ],
        "package_pricing": {
          "midpoint": {
            "effect": "DEBIT",
            "total_dollars": "..."
          },
          "executable": {
            "effect": "DEBIT",
            "total_dollars": "..."
          }
        }
      },
      "outcomes": {
        "executable": {
          "effective_buffer_pct": 6.06,
          "upside_cap_pct": 20.62
        }
      },
      "marginal_tradeoff": null
    }
  ],
  "meta": {
    "strategy": "buffer",
    "quote_visibility": "full",
    "pricing_modes": [
      "executable",
      "midpoint"
    ],
    "frontier_point_count": 3
  }
}

The example is abbreviated. Live responses include the full trade ticket, actual bid/mid/ask quotes, quote timestamps, package pricing, and complete modeled outcome fields.

Full Trade Tickets

Every frontier point uses the same detailed strategy contract already documented under /v1/outcomes.

Annualized metrics (collar)

For every collar frontier point, both outcomes.midpoint and outcomes.executable include:

• annualized_downside_pct — the modeled maximum loss annualized to a one-year basis.
• annualized_cap_pct — the modeled upside cap annualized to a one-year basis.

Annualizing lets you compare collar outcomes modeled across different horizons on an apples-to-apples basis. The non-annualized upside cap and frontier metric remain available on each point.

Marginal Tradeoff

Frontier points after the first may include:

{
  "marginal_tradeoff": {
    "additional_frontier_pct": 4.54,
    "upside_cap_change_pct": -4.52,
    "upside_cap_change_per_frontier_pct": -1.00
  }
}

• additional_frontier_pct is the change in the selected strategy's actual frontier metric relative to the previous efficient point.
• upside_cap_change_pct is the resulting change in upside cap.
• upside_cap_change_per_frontier_pct measures the change in upside cap for each additional percentage point of the frontier metric.

Interpretation depends on strategy:

• For a collar, a positive value generally means accepting more maximum loss provides additional upside.
• For a buffer or covered call, a negative value generally means additional protection or cushion requires giving up upside.

This is a derived comparison between adjacent modeled outcomes, not a forecast of future investment performance.

Compare how the same protection objective changes across different investment horizons.

Parity fetches the market data for the selected security and models the requested strategy across multiple target horizons. Each available horizon returns the complete option structure and modeled outcome.

Supported strategies

• collar
• buffer
• covered_call

Request Body

Horizon constraints

• Minimum value for each horizon: 30
• Maximum value for each horizon: 750
• Maximum number of horizons: 6
• Duplicate horizons are not allowed.

If days is omitted, Parity currently evaluates:

• 90
• 180
• 270
• 365
• 540
• 730

Example Request

curl -X POST "https://outcomes.parityoutcomes.com/v1/horizons" \
  -H "Authorization: Bearer $PARITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "SPY",
    "strategy": "collar",
    "downside_target_pct": 10,
    "days": [90, 180, 365]
  }'

Response

Top-level fields include:

Each horizons[] item includes:

For an available horizon, outcome uses the same complete public strategy contract used elsewhere in the Parity API, including:

• status, strategy, protection_type, target, summary, structure, trade, outcomes

trade includes expiration, legs, per-leg bid / mid / ask quotes, quote timestamp, package_pricing.executable, and package_pricing.midpoint.

outcomes includes executable and midpoint.

Example Response (abbreviated)

{
  "symbol": "SPY",
  "strategy": "collar",
  "request": {
    "downside_target_pct": 10,
    "days": [90, 180, 365]
  },
  "horizons": [
    {
      "requested_days": 90,
      "status": "available",
      "expiration": {
        "date": "2026-11-20",
        "days_to_expiration": 98
      },
      "outcome": {
        "summary": {
          "estimated_max_loss_pct": 9.4949,
          "estimated_upside_cap_pct": 8.4312
        },
        "trade": {
          "...": "complete trade ticket"
        },
        "outcomes": {
          "midpoint": {
            "...": "..."
          },
          "executable": {
            "...": "..."
          }
        }
      }
    }
  ]
}

The example is abbreviated and shows a single horizon. Live responses include the full trade ticket, actual bid/mid/ask quotes, and complete modeled outcome fields for every available horizon.

When to use this endpoint

/v1/horizons is useful when the security and protection objective are known, but you want to compare how extending or shortening the protection period changes the available outcome.

Model the same outcome objective across multiple securities in one request.

The endpoint accepts up to 10 ticker symbols, one strategy, one target horizon, and one downside target. Parity returns the complete implementable modeled outcome for every security where an eligible structure is available.

Supported strategies

• collar
• buffer
• covered_call

Request Body

Results preserve the submitted security order in v1.

Example Request

curl -X POST "https://outcomes.parityoutcomes.com/v1/screen" \
  -H "Authorization: Bearer $PARITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "symbols": ["SPY", "QQQ", "NVDA"],
    "strategy": "collar",
    "days": 365,
    "downside_target_pct": 10
  }'

Response

Each successful results[] item includes:

Each successful security includes:

• exact option legs — action, quantity, option type, expiration, strike
• per-leg bid, mid, ask, and quote timestamp
• executable package pricing
• midpoint package pricing
• expected dividends
• executable modeled outcome
• midpoint modeled outcome

Example Response (abbreviated)

{
  "api_version": "v1",
  "strategy": "collar",
  "request": {
    "symbols": ["SPY", "QQQ", "NVDA"],
    "days": 365,
    "downside_target_pct": 10
  },
  "results": [
    {
      "symbol": "SPY",
      "status": "available",
      "market": {
        "underlying_price": 777.69
      },
      "expiration": {
        "date": "2027-09-17",
        "days_to_expiration": 399
      },
      "outcome": {
        "summary": {
          "estimated_max_loss_pct": 9.8538,
          "estimated_upside_cap_pct": 13.8917
        },
        "structure": {
          "long_put_strike": 695,
          "short_call_strike": 880
        },
        "trade": {
          "...": "complete trade ticket"
        },
        "outcomes": {
          "midpoint": {
            "...": "..."
          },
          "executable": {
            "...": "..."
          }
        }
      }
    }
  ],
  "unavailable": [],
  "meta": {
    "symbols_requested": 3,
    "results_available": 3,
    "results_unavailable": 0
  }
}

The example is abbreviated and shows a single result. Live responses include the full trade ticket, actual bid/mid/ask quotes, and complete modeled outcome fields for every available security.

Partial Success

A failure or unavailable structure for one security does not invalidate successful results for other submitted securities. Unavailable securities are returned separately in the unavailable array.

When to use this endpoint

/v1/screen models the securities you submit. It does not scan the full market and does not return recommendations.

The POST /v1/outcomes response contains the following top-level fields:

The strategies object contains three modeled strategy results. Each strategy includes status, strategy, protection_type, target, summary, structure, trade, and outcomes.

Collar

Buffer

protected_start_pct identifies approximately where the protected range begins relative to the current underlying price. protected_end_pct identifies approximately where that protected range ends.

Covered Call

The downside cushion comes from modeled option income plus expected dividends and is not the same thing as guaranteed principal protection.

Executable vs. Midpoint

Executable is Parity's primary pricing basis. The complete response includes outcomes.executable and outcomes.midpoint. Use outcomes.executable for the conservative estimate that reflects buy-at-ask / sell-at-bid economics.

Executable reflects Parity's conservative buy-at-ask / sell-at-bid estimate and does not imply a guaranteed fill. Midpoint reflects pricing based around option bid/ask midpoints and may not be achievable.

This applies consistently to /v1/outcomes, /v1/frontier, /v1/horizons, and /v1/screen.

New API keys currently include 1,000 requests per calendar month. The account/key's returned limit is authoritative.

GET /v1/usage

curl "https://outcomes.parityoutcomes.com/v1/usage" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "hourly_used": 1,
  "hourly_limit": null,
  "hourly_remaining": null,
  "monthly_used": 24,
  "monthly_limit": 1000,
  "monthly_remaining": 976
}

A null hourly_limit means no hourly cap is currently configured for that key. Do not translate null into 0.

When a configured limit is reached, the API returns HTTP 429.

Requests to GET /v1/securities count toward the same API-key usage limits as the modeling endpoints.

• Never commit API keys to Git.
• Never include them in frontend source code.
• Never put them in URLs.
• Never expose them in screenshots or support tickets unnecessarily.
• Use environment variables or secret storage.
• Revoke a key immediately if exposure is suspected.
• Create separate keys for separate integrations/environments when appropriate.
• Name keys descriptively (e.g. Production Backend, Staging, Internal Analytics).

Do not share one secret across every system.

Do not put API keys into browser-side fetch examples. JavaScript examples are explicitly Node/server-side.

curl -X POST "https://outcomes.parityoutcomes.com/v1/outcomes" \
  -H "Authorization: Bearer $PARITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "SPY",
    "days": 365,
    "downside_target_pct": 10
  }'

Explore an Outcome Frontier with Python

Use /v1/frontier to explore the tradeoff frontier for collars, buffers, and covered calls across a range of protection or income targets.

import os
import requests

API_KEY = os.environ["PARITY_API_KEY"]

response = requests.post(
    "https://outcomes.parityoutcomes.com/v1/frontier",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "symbol": "SPY",
        "strategy": "collar",
        "days": 365,
        "min_target_pct": 5,
        "max_target_pct": 20,
        "step_pct": 1,
    },
    timeout=60,
)

response.raise_for_status()

data = response.json()

for point in data["frontier"]:
    executable = point["outcomes"]["executable"]

    print(
        executable["max_loss_pct"],
        executable["upside_cap_pct"],
    )

Because Frontier returns complete trade tickets for every efficient point, the same response can be used to build charts, screen outcome tradeoffs, compare midpoint and executable pricing, inspect option quotes, or generate downstream trade instructions.

Retrieve Supported Securities with Python

import os
import requests

API_KEY = os.environ["PARITY_API_KEY"]

response = requests.get(
    "https://outcomes.parityoutcomes.com/v1/securities",
    headers={
        "Authorization": f"Bearer {API_KEY}",
    },
    timeout=60,
)

response.raise_for_status()

data = response.json()

print("Supported securities:", data["count"])
print("Recently supported:", data["newly_supported"])
print("Market date:", data["market_date"])
print("Snapshot stale:", data["stale"])