> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aioka.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Gold Live Signals

> Latest readings of all 8 Gold-specific signals across macro, technical, ETF flow, and safe-haven drivers

<Note>
  Pro tier endpoint -- requires a valid Pro API key. Fetches fresh
  signal readings on every request (expect 1 -- 3 seconds response time).
</Note>

**Tier:** Pro (\$199/mo)
**Cache:** None -- fetches fresh on every request
**Rate limit:** 30/min (per tier)
**Read-only:** No writes.

## Response Fields

### Top-level

| Field         | Type   | Meaning                                                        |
| ------------- | ------ | -------------------------------------------------------------- |
| `signals`     | array  | Latest readings for each Gold signal, one entry per signal key |
| `generatedAt` | string | Response timestamp (ISO 8601)                                  |

### Per-signal (signals array)

| Field       | Type           | Meaning                                                                    |
| ----------- | -------------- | -------------------------------------------------------------------------- |
| `key`       | string         | Signal identifier (see signal catalog below)                               |
| `value`     | number \| null | Latest numeric reading. `null` when the source is temporarily unavailable. |
| `direction` | string         | Direction label -- semantics vary per signal (see catalog)                 |
| `source`    | string         | Data source identifier (e.g. `"fred"`, `"yahoo_finance"`, `"imf_ifs"`)     |
| `detail`    | string         | Human-readable description of the current reading                          |
| `fetchedAt` | string         | ISO 8601 timestamp of when this reading was captured                       |

## Gold Signal Catalog

All 8 Gold-specific signals feed the council deliberation every 30 minutes.
Per-signal cache TTLs vary (15 min -- 7 days) to match how frequently each
underlying data source updates.

| Signal Key                    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Source                     | Cache TTL | Agent                              |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | --------- | ---------------------------------- |
| `GOLD_REAL_RATE_DIRECTION`    | 10Y TIPS yield trend (FRED DFII10). FALLING real rates lower the opportunity cost of holding Gold and are historically its strongest macro tailwind. **Used in Gate 8 -- RISING blocks all entries. UNKNOWN also blocks (fail-safe).** Threshold: delta > +5 bps = RISING; delta \< -5 bps = FALLING. Direction: `FALLING` / `FLAT` / `RISING` / `UNKNOWN`.                                                                                                                                                 | FRED (DFII10)              | 4 h       | MACRO\_SAGE, INFLATION\_SAGE       |
| `GOLD_DXY_TREND`              | Broad USD index trend (FRED DTWEXBGS). Gold is priced in USD so an inverse correlation of roughly -0.7 holds historically. BULLISH = DXY falling (Gold rises). BEARISH = DXY rising (Gold falls). Threshold: change > +0.2% = BEARISH; change \< -0.2% = BULLISH. Direction: `BULLISH` / `BEARISH` / `NEUTRAL` / `UNKNOWN`.                                                                                                                                                                                 | FRED (DTWEXBGS)            | 1 h       | MACRO\_SAGE                        |
| `GOLD_SILVER_RATIO`           | XAU/USD divided by XAG/USD (Yahoo Finance futures GC=F / SI=F). Elevated ratio (75 -- 85) signals risk-off rotation into Gold. Extreme ratio (> 85) historically precedes Gold corrections. Below 65 = silver outperforming = risk-on = bearish for Gold. Direction: `BULLISH` / `NEUTRAL` / `BEARISH` / `UNKNOWN`.                                                                                                                                                                                         | Yahoo Finance (GC=F, SI=F) | 1 h       | TECHNICAL\_HAWK                    |
| `GOLD_ETF_FLOWS`              | Institutional interest proxy from GLD + IAU combined 5-day trading volume vs prior 5 days (Yahoo Finance). Rising volume signals accelerating institutional interest. Note: this is a volume proxy, not net share creation -- true net flow data requires Bloomberg or ETF-issuer feeds. Direction: `BULLISH` / `NEUTRAL` / `BEARISH` / `UNKNOWN`.                                                                                                                                                          | Yahoo Finance (GLD, IAU)   | 24 h      | CENTRAL\_BANK\_WATCHER             |
| `GOLD_VIX`                    | CBOE Volatility Index (FRED VIXCLS). Elevated fear drives safe-haven demand for Gold. The sweet spot for Gold entries is VIX 20 -- 35 (elevated but not panic). Direction labels: `LOW` (\< 15) / `MODERATE` (15 -- 25) / `ELEVATED` (25 -- 35) / `EXTREME` (> 35) / `UNKNOWN`.                                                                                                                                                                                                                             | FRED (VIXCLS)              | 15 min    | SAFE\_HAVEN\_ANALYST               |
| `GOLD_INFLATION_EXPECTATIONS` | 5-year breakeven inflation rate (FRED T5YIE). Rising breakeven = markets pricing in more inflation = Gold inflation-hedge bid rises. Threshold: delta > +3 bps = BULLISH; delta \< -3 bps = BEARISH. Direction: `BULLISH` / `NEUTRAL` / `BEARISH` / `UNKNOWN`.                                                                                                                                                                                                                                              | FRED (T5YIE)               | 4 h       | INFLATION\_SAGE                    |
| `GOLD_CENTRAL_BANK_DEMAND`    | World official gold reserves direction from IMF International Financial Statistics (IFS) SDMX API (Q.W00.RAAAGOLD\_T\_SDR). Physical quantity change is isolated by dividing each quarter's SDR reserve value by the contemporaneous Gold price (Yahoo GC=F quarterly), removing pure price-appreciation noise. Supports `AIOKA_GOLD_CB_DEMAND_OVERRIDE` env var for manual ops override. Never returns `UNKNOWN` -- falls back to stale cache then `NEUTRAL`. Direction: `BUYING` / `NEUTRAL` / `SELLING`. | IMF IFS SDMX API           | 7 d       | CENTRAL\_BANK\_WATCHER             |
| `GOLD_GEOPOLITICAL_RISK`      | Geopolitical risk level via CBOE VIX proxy (FRED VIXCLS). The Caldara and Iacoviello GPRC index is not available via the FRED API (400 on all known series IDs) -- VIX is the permanent proxy. Direction: `LOW` / `MODERATE` / `ELEVATED` / `EXTREME` / `UNKNOWN`.                                                                                                                                                                                                                                          | VIX proxy (FRED VIXCLS)    | 1 h       | SAFE\_HAVEN\_ANALYST, RISK\_WARDEN |

## Gate 8 -- Real Rate Block

`GOLD_REAL_RATE_DIRECTION` is the only Gold signal that directly gates
entry. When the 10Y TIPS yield trend is `RISING`, the Gold trader blocks
all new entries regardless of other signal scores. `UNKNOWN` (FRED
unavailable) also triggers the block -- the conservative call is to not
trade when the most important macro input is missing.

## Notes

* `GOLD_VIX` and `GOLD_GEOPOLITICAL_RISK` read from the same underlying
  FRED VIXCLS series. `GOLD_VIX` informs the `SAFE_HAVEN_ANALYST` veto
  above the configured threshold (VIX > 40). `GOLD_GEOPOLITICAL_RISK`
  is a direct geopolitical risk label for the `RISK_WARDEN` agent.
* `GOLD_CENTRAL_BANK_DEMAND` uses a 7-day cache because IMF IFS data
  updates quarterly (at most 4 real changes per year). Fresh network
  fetches are rare by design.
* `GOLD_ETF_FLOWS` uses 24-hour cache because daily Yahoo Finance volume
  data does not change intra-day in a meaningful way.
* All providers are non-raising (P-G). A failed fetch returns `null` for
  `value` and `"UNKNOWN"` for `direction` -- the council quality score
  correctly reflects missing data rather than a fake zero.

<RequestExample>
  ```bash curl theme={null}
  curl https://api.aioka.io/v1/commodities/gold/signals \
    -H "X-API-Key: aik_pro_your_key_here"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "signals": [
      {
        "key": "GOLD_REAL_RATE_DIRECTION",
        "value": 1.82,
        "direction": "FALLING",
        "source": "fred",
        "detail": "10Y TIPS=1.820% prior=1.870% delta=-5.0bps",
        "fetchedAt": "2026-05-07T08:14:00+00:00"
      },
      {
        "key": "GOLD_DXY_TREND",
        "value": 104.21,
        "direction": "BEARISH",
        "source": "fred",
        "detail": "DXY=104.21 (+0.31%)",
        "fetchedAt": "2026-05-07T08:10:00+00:00"
      },
      {
        "key": "GOLD_SILVER_RATIO",
        "value": 79.42,
        "direction": "BULLISH",
        "source": "yahoo_finance",
        "detail": "ratio=79.42 gold=$3241.50 silver=$40.82",
        "fetchedAt": "2026-05-07T08:12:00+00:00"
      },
      {
        "key": "GOLD_ETF_FLOWS",
        "value": 48320000.0,
        "direction": "BULLISH",
        "source": "yahoo_finance",
        "detail": "5d_vol=48320000 prior=41800000 (+15.6%)",
        "fetchedAt": "2026-05-07T07:00:00+00:00"
      },
      {
        "key": "GOLD_VIX",
        "value": 22.41,
        "direction": "MODERATE",
        "source": "fred",
        "detail": "VIX=22.41 (MODERATE)",
        "fetchedAt": "2026-05-07T08:14:30+00:00"
      },
      {
        "key": "GOLD_INFLATION_EXPECTATIONS",
        "value": 2.341,
        "direction": "BULLISH",
        "source": "fred",
        "detail": "5Y breakeven=2.341% delta=+4.2bps",
        "fetchedAt": "2026-05-07T08:10:00+00:00"
      },
      {
        "key": "GOLD_CENTRAL_BANK_DEMAND",
        "value": 3814.2,
        "direction": "BUYING",
        "source": "imf_ifs",
        "detail": "imf_world_sdr=3814.2B gold_px=3241 delta_qty=+0.0041",
        "fetchedAt": "2026-05-07T08:00:00+00:00"
      },
      {
        "key": "GOLD_GEOPOLITICAL_RISK",
        "value": 22.41,
        "direction": "MODERATE",
        "source": "vix_proxy",
        "detail": "VIX proxy=22.41 (MODERATE)",
        "fetchedAt": "2026-05-07T08:14:30+00:00"
      }
    ],
    "generatedAt": "2026-05-07T08:15:00+00:00"
  }
  ```
</ResponseExample>