Skip to main content

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.

Pro tier endpoint — requires a valid Pro API key. Fetches fresh signal readings on every request (expect 1 — 3 seconds response time).
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

FieldTypeMeaning
signalsarrayLatest readings for each Gold signal, one entry per signal key
generatedAtstringResponse timestamp (ISO 8601)

​
Per-signal (signals array)

FieldTypeMeaning
keystringSignal identifier (see signal catalog below)
valuenumber | nullLatest numeric reading. null when the source is temporarily unavailable.
directionstringDirection label — semantics vary per signal (see catalog)
sourcestringData source identifier (e.g. "fred", "yahoo_finance", "imf_ifs")
detailstringHuman-readable description of the current reading
fetchedAtstringISO 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 KeyDescriptionSourceCache TTLAgent
GOLD_REAL_RATE_DIRECTION10Y 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 hMACRO_SAGE, INFLATION_SAGE
GOLD_DXY_TRENDBroad 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 hMACRO_SAGE
GOLD_SILVER_RATIOXAU/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 hTECHNICAL_HAWK
GOLD_ETF_FLOWSInstitutional 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 hCENTRAL_BANK_WATCHER
GOLD_VIXCBOE 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 minSAFE_HAVEN_ANALYST
GOLD_INFLATION_EXPECTATIONS5-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 hINFLATION_SAGE
GOLD_CENTRAL_BANK_DEMANDWorld 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 API7 dCENTRAL_BANK_WATCHER
GOLD_GEOPOLITICAL_RISKGeopolitical 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 hSAFE_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.
curl https://api.aioka.io/v1/commodities/gold/signals \
  -H "X-API-Key: aik_pro_your_key_here"

{
  "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"
}