Skip to main content

Program endpoints

Gaia exposes two surfaces: a gated product API for entitled subscribers, and a keyless preview for marketing and evaluation. Both share the base URL:

https://signals.btcalpha.com.au

Gated product API​

Every gated endpoint requires an X-API-Key header and the gaia entitlement on that key. Without the entitlement the key is rejected even if it is valid for the signal feed.

Method & pathPurpose
GET /v1/programProgram manifest — alias, tiers, weights, deployment_state, window bounds.
GET /v1/program/basket?view=reference|personalThe current basket. reference = canonical weights/prices; personal = scaled to your profile equity.
GET /v1/program/deploys?since=<seq>Every deployment after <seq> — the pull backstop for the basket.
GET /v1/program/performance?benchmark=dca|hodl|lump_sumPublished performance vs the chosen benchmark (avg cost basis, advantage, % cheaper).
PUT /v1/program/profileSet your accumulation profile (equity, contribution cadence) used by view=personal.
POST /v1/program/simulateRun the full basket over a window against your profile and get the benchmark table back.

:::note Entitlement is per-key X-API-Key alone is not enough — the key must carry the gaia entitlement. A signal-feed key without it gets 403. See error codes. :::

Keyless preview​

The preview surface needs no API key. It is rate-limited and input-bounded (simulate inputs are clamped to sane ranges) because it is public marketing. It is enough to reproduce every sales-page number.

Method & pathPurpose
GET /v1/program/previewThe reference basket + the full benchmark table, keyless.
POST /v1/program/preview/simulateRun a bounded simulation (your equity + cadence) keyless.

GET /v1/program/preview​

curl https://signals.btcalpha.com.au/v1/program/preview
{
  "schema_version": "1.0", "alias": "gaia",
  "deployment_state": "accumulating",
  "instrument": "BTC-USDT-SPOT",
  "window": { "bars": "4H", "start_close": 12920.0 },
  "tiers": [
    { "tier": "core", "weight": 0.60 },
    { "tier": "cyclical", "weight": 0.20 },
    { "tier": "tactical", "weight": 0.20 }
  ],
  "avg_cost_basis": 7172.66,
  "benchmarks": {
    "dca":       { "value": 15462.0, "advantage_bps": 5360, "pct_cheaper": 53.6 },
    "vwap":      { "value": 28819.0, "advantage_bps": 7510, "pct_cheaper": 75.1 },
    "lump_sum":  { "value": 12920.0, "advantage_bps": 4450, "pct_cheaper": 44.5 },
    "hodl":      { "value": 12920.0, "advantage_bps": 4450, "pct_cheaper": 44.5 }
  },
  "pct_capital_cheapest_quartile": 0.41,
  "tv_status": "provisional"
}

POST /v1/program/preview/simulate​

curl -X POST https://signals.btcalpha.com.au/v1/program/preview/simulate \
  -H "Content-Type: application/json" \
  -d '{ "equity_usd": 100000, "contribution_cadence_bars": 84 }'
{
  "schema_version": "1.0", "alias": "gaia",
  "input": { "equity_usd": 100000, "contribution_cadence_bars": 84 },
  "total_usd_deployed": 100000.0,
  "total_btc_accumulated": 13.943,
  "avg_cost_basis": 7172.66,
  "benchmarks": {
    "dca":      { "value": 15462.0, "pct_cheaper": 53.6 },
    "vwap":     { "value": 28819.0, "pct_cheaper": 75.1 },
    "lump_sum": { "value": 12920.0, "pct_cheaper": 44.5 },
    "hodl":     { "value": 12920.0, "pct_cheaper": 44.5 }
  }
}

:::note Bounded inputs equity_usd and contribution_cadence_bars are clamped to bounded ranges on the keyless surface. The shape of the response is identical to the gated POST /v1/program/simulate; only the input ceilings differ. :::

Benchmark methodology

Reproduce every number above from this keyless preview.

The data model

The deployment object behind every basket row.