# `Bourse.Unified.OptionSurface`
[🔗](https://github.com/ZenHive/bourse/blob/main/lib/bourse/unified/option_surface.ex#L1)

Coherent option discovery and instrument-Greeks surface for option venues.

Joins market identity with risk data by **canonical unified symbol**, preserves
native provenance (`info`) and distinct source vs local observation timestamps,
and fails explicitly on missing identity, ambiguous matches or stale data.

# `discover`

```elixir
@spec discover(Bourse.Exchange.t(), keyword() | map()) ::
  {:ok, [Bourse.OptionInstrument.t()]} | {:error, Bourse.Error.t()}
```

Discovers active option calls and puts for a venue.

Options:

  * `:base` / `"base"` — restrict to an underlying base currency
  * `:quotes` — when true (default), attempt to attach bid/ask/IV/OI via
    `fetch_option_chain` when available
  * `:observed_at` — override local observation time (tests)
  * `:request_opts` — options forwarded to venue HTTP calls

# `instrument_greeks`

```elixir
@spec instrument_greeks(Bourse.Exchange.t(), String.t(), keyword() | map()) ::
  {:ok, Bourse.InstrumentGreeks.t()} | {:error, Bourse.Error.t()}
```

Fetches instrument Greeks for one canonical symbol and joins market identity.

Options:

  * `:max_age_ms` — when set, fails if source timestamp is missing or older
    than this many milliseconds relative to `observed_at`
  * `:observed_at` — override local observation time (tests)
  * `:request_opts` — options forwarded to venue HTTP calls

# `surface`

```elixir
@spec surface(Bourse.Exchange.t(), keyword() | map()) ::
  {:ok,
   [
     %{
       instrument: Bourse.OptionInstrument.t(),
       greeks: Bourse.InstrumentGreeks.t()
     }
   ]}
  | {:error, Bourse.Error.t()}
```

Builds the joined option+Greeks surface for active instruments.

Options:

  * `:base` / `"base"` — restrict discovery
  * `:limit` — cap the number of instruments whose Greeks are fetched
  * `:max_age_ms` — freshness gate applied per instrument
  * `:observed_at` — override local observation time (tests)
  * `:request_opts` — options forwarded to venue HTTP calls

---

*Consult [api-reference.md](api-reference.md) for complete listing*