# Market Ratios API
> Live intermarket relative-value ratios as an API — the cross-asset signals macro and technical traders watch, computed from Yahoo Finance prices. Each ratio divides one market by another to reveal relative value and regime: the Gold/Oil ratio (barrels of crude per ounce of gold), the Oil/Gas energy spread, the Copper/Gold ratio (a growth and interest-rate barometer), the S&P 500 priced in gold, and the Stocks/Bonds ratio (risk-on versus risk-off, SPY/TLT). For each it returns both leg prices, the ratio value, the day change and a plain-language reading. Get one ratio or the whole board in a single call. The intermarket relative-value layer for trading, macro-research and dashboard apps. Live, no key, no cache. Distinct from single-asset price APIs and from the precious-metals ratio — this is the cross-asset ratio set.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/marketratios-api/..."
```

## Pricing
- **Free** (Free) — 8,000 calls/Mo, 4 req/s
- **Starter** ($10/Mo) — 100,000 calls/Mo, 12 req/s
- **Pro** ($25/Mo) — 500,000 calls/Mo, 35 req/s
- **Desk** ($61/Mo) — 2,500,000 calls/Mo, 100 req/s

## Endpoints

### Ratio

#### `GET /v1/ratio` — One intermarket ratio with both legs and reading

**Parameters:**
- `ratio` (query, required, string) — Ratio key (gold_oil|oil_gas|copper_gold|spx_gold|stocks_bonds) Example: `gold_oil`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/marketratios-api/v1/ratio?ratio=gold_oil"
```

**Response:**
```json
{
    "data": {
        "name": "Gold / Oil",
        "ratio": "gold_oil",
        "value": 48.0852,
        "reading": "Barrels of crude oil per ounce of gold. High = oil cheap vs gold (risk-off / weak growth).",
        "previous": 47.7919,
        "numerator": {
            "label": "Gold",
            "price": 4359.4,
            "symbol": "GC=F"
        },
        "change_pct": 0.61,
        "denominator": {
            "label": "WTI Crude",
            "price": 90.66,
            "symbol": "CL=F"
        }
    },
    "meta": {
        "timestamp": "2026-06-09T03:02:06.218Z",
        "request_id": "b2350366-9948-4e98-9b52-e245249494ac"
    },
    "status": "ok",
    "message": "Ratio retrieved successfully",
    "success": true
}
```

### List

#### `GET /v1/list` — The whole ratio board in one call

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/marketratios-api/v1/list"
```

**Response:**
```json
{
    "data": {
        "count": 5,
        "ratios": [
            {
                "name": "Gold / Oil",
                "ratio": "gold_oil",
                "value": 48.0852,
                "reading": "Barrels of crude oil per ounce of gold. High = oil cheap vs gold (risk-off / weak growth).",
                "previous": 47.7919,
                "numerator": {
                    "label": "Gold",
                    "price": 4359.4,
                    "symbol": "GC=F"
                },
                "change_pct": 0.61,
                "denominator": {
                    "label": "WTI Crude",
                    "price": 90.66,
                    "symbol": "CL=F"
                }
            },
            {
                "name": "Oil / Natural Gas",
                "ratio": "oil_gas",
                "value": 28.7627,
                "reading": "Energy relative value — WTI price per unit of natural gas. The classic energy spread.",
                "previous": 29.0118,
                "numerator": {
                    "label": "WTI Crude",
                    "price": 90.66,
                    "symbol": "CL=F"
                },
                "change_pct": -0.86,
                "denominator": {
                    "label": "Natural Gas",
                    "price": 3.15,
                    "symbol": "NG=F"
                }
            },
            {
                "name": "Copper / Gold",
                "ratio": "copper_gold",
                "value
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Service metadata and ratio list

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/marketratios-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "ratios": {
            "oil_gas": "Oil / Natural Gas",
            "gold_oil": "Gold / Oil",
            "spx_gold": "S&P 500 / Gold",
            "copper_gold": "Copper / Gold",
            "stocks_bonds": "Stocks / Bonds (SPY/TLT)"
        },
        "source": "Yahoo Finance public chart API (live)",
        "service": "marketratios-api",
        "endpoints": {
            "GET /v1/list": "The whole ratio board in one call.",
            "GET /v1/meta": "This document.",
            "GET /v1/ratio": "One intermarket ratio (ratio=gold_oil|oil_gas|copper_gold|spx_gold|stocks_bonds)."
        },
        "description": "Live intermarket relative-value ratios from Yahoo Finance: Gold/Oil (barrels per ounce), Oil/Gas energy spread, Copper/Gold (growth & rate barometer), S&P 500 priced in gold, and Stocks/Bonds (SPY/TLT risk-on/off). Each with both leg prices, the ratio, day change and a plain-language reading. Get one ratio or the whole board. Live, no key. Distinct from single-asset price APIs and from the precious-metals ratio — this is the cross-asset ratio set.",
        "upstream_status": "ok"
    },
    "meta": {
        "timestamp": "2026-06-09T03:02:06.541Z",
        "request_id": "316ba0d3-d24a-4b65-8633-e2bfbf1a5771"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/marketratios-api
OpenAPI spec: https://www.oanor.com/api/marketratios-api/openapi.json