---
name: gs-quant-overview
description: "Guide to writing gs_quant code: sessions, instruments, portfolios, pricing and risk, results, datasets and backtesting. Use for any coding task that uses the gs_quant library, including slow pricing, timeouts, gs_quant error messages, and prices that differ from other tools or look a day old."
---

# gs_quant Quick Start

Before writing code that prices, calculates risk or resolves instruments, read `pricing.md`.

## 1. Creating a Session with `GsSession.use`

All API communication in `gs_quant` flows through an authenticated `GsSession`. Before making any pricing or data calls you must initialise a session with `GsSession.use()`.

### OAuth2 (Application Credentials)

```python
from gs_quant.session import GsSession, Environment

GsSession.use(
    environment_or_domain=Environment.PROD,
    client_id='my_client_id',
    client_secret='my_client_secret',
    scopes=('run_analytics',),
)
```

- **`environment_or_domain`** — `Environment.PROD` (default), `Environment.QA`, or `Environment.DEV`. You can also pass a raw URL string.
- **`client_id` / `client_secret`** — OAuth2 application credentials. When both are provided the library creates an `OAuth2Session`.
- **`scopes`** — Optional iterable of `GsSession.Scopes` values. Usually when pricing trade you will need `run_analytics`.

### Kerberos / SSO (Internal GS)

If no `client_id` is supplied, the library will attempt Kerberos or pass-through authentication automatically:
This is for internal GS users only and requires appropriate network access and installation of gs-quant-internal.

```python
GsSession.use(Environment.PROD)
```

### Using as a Context Manager

```python
with GsSession.get(Environment.PROD, client_id='...', client_secret='...') as session:
    # session is active inside this block
    ...
```

### Verifying the Session

```python
GsSession.current  # the currently active GsSession instance
```

---

## 2. Resolving an Instrument

When you construct an instrument you typically only specify a subset of its parameters. **Resolving** fills in all remaining fields by sending the instrument to the GS pricing service.

```python
from gs_quant.instrument import IRSwap

swap = IRSwap('Pay', '10y', 'USD')

# Before resolve: swap.fixed_rate is None
swap.resolve()
# After resolve: swap.fixed_rate is now populated with the current par rate

print(swap.fixed_rate)  # e.g. 0.0345
```

### What `resolve()` Does

1. Sends the instrument to the GS analytics service along with the current `PricingContext`.
2. The service computes any missing parameters — par rate, premium, forward points, etc.
3. By default (`in_place=True`), the instrument is updated in place. Pass `in_place=False` to receive a new resolved copy.

For marking an entered trade to market and reading resolved terms, see "Relative terms and resolve()" in `pricing.md`.

---

## 3. Combining Instruments in Portfolios

The `Portfolio` class groups instruments for pricing, resolution, and analysis as a single unit.

### Creating a Portfolio

```python
from gs_quant.instrument import IRSwap, IRSwaption
from gs_quant.markets.portfolio import Portfolio

swap = IRSwap('Pay', '10y', 'USD', name='USD 10y Payer')
swaption = IRSwaption('Receive', '10y', 'EUR', expiration_date='1y', name='EUR 1y10y Receiver')

portfolio = Portfolio([swap, swaption], name='My Portfolio')
```

From a dictionary (keys become instrument names):

```python
portfolio = Portfolio(
    {
        'USD 10y Payer': IRSwap('Pay', '10y', 'USD'),
        'EUR 5y Receiver': IRSwap('Receive', '5y', 'EUR'),
    }
)
```

### Nesting Portfolios

```python
usd_book = Portfolio([IRSwap('Pay', '5y', 'USD'), IRSwap('Receive', '10y', 'USD')], name='USD Book')
eur_book = Portfolio([IRSwap('Pay', '5y', 'EUR')], name='EUR Book')
master = Portfolio([usd_book, eur_book], name='Master Book')
```

### Portfolio Operations

```python
portfolio.append(IRSwap('Pay', '2y', 'GBP'))  # add instruments
first = portfolio[0]  # access by index
usd_swap = portfolio['USD 10y Payer']  # access by name
len(portfolio)  # top-level count
portfolio.all_instruments  # all instruments across nested portfolios
```

### Resolving and Pricing

```python
from gs_quant.risk import DollarPrice, IRDelta

portfolio.resolve()  # resolves all instruments in place
prices = portfolio.calc(DollarPrice)  # single risk measure
results = portfolio.calc([DollarPrice, IRDelta])  # multiple risk measures
```

---

## See Also

For detailed guidance on specific topics, open the file whose topic or symptoms match the task.

- `instruments.md` — Constructing all instrument types (IRSwap, XCcy swaps, FXOption, EqOption, etc.), strikes by asset class, and FX pitfalls
- `pricing.md` — PricingContext, HistoricalPricingContext and LiveMarket: which close is used and market data location, choosing contexts, long calculations and `is_batch`, relative terms and `resolve()`. Symptoms: slow code, many requests, timeouts, prices that differ from other tools or look a day old.
- `errors.md` — gs_quant error messages and what to do, and how to reach support when nothing fixes it.
- `datasets.md` — Accessing market and reference data via the gs_quant Dataset class: get_data, get_data_series, get_data_last, get_coverage, uploading data, batching large queries. Covers TREOD for equities, FXIVOL_STANDARD, symbol dimensions, and common pitfalls.
- `backtesting.md` — Guide to the gs_quant backtesting framework: Strategy, triggers, actions, GenericEngine, EquityVolEngine, transaction costs, and result extraction.
- `measure.md` — writing custom measures with `@plot_measure` and `@risk_measure` decorators