> ## 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.
# Bitcoin Cycle Context
> Where Bitcoin sits in its market cycle: phase, Pi Cycle Top, halving timing and on-chain valuation
This endpoint is public — no API key required. Powers the Cycle Intelligence card on
aioka.io/live and the `/cycle` Telegram command.
**Tier:** Public ✅
**Cache:** 5 min (Redis response cache)
**Read-only:** Never writes to any trading table.
> ⚠️ Cycle context is market information, not financial advice.
## Response Fields
| Field | Type | Meaning |
| - | - | - |
| `cyclePhase` | string | Deterministic phase: `BEAR_BOTTOM` / `EARLY_BULL` / `MID_BULL` / `LATE_BULL` / `TOP_SIGNAL` / `UNKNOWN` (`UNKNOWN` when the signals do not fit one phase, e.g. MVRV-Z below 0 while NUPL is still above 0.25) |
| `cyclePhaseVerdict` | string | Verdict implied by the phase (`STRONG_BUY` … `STRONG_AVOID`; `HOLD` for `UNKNOWN`) |
| `mvrvZ` | number \| null | MVRV Z-score (Coin Metrics) |
| `nupl` | number \| null | Net Unrealized Profit/Loss |
| `sopr` | number \| null | Spent Output Profit Ratio |
| `piCyclePhase` | int \| null | Pi Cycle Top phase code 0–4 |
| `piCyclePhaseName` | string \| null | `BOTTOM_ZONE` / `EARLY_BULL` / `MID_BULL` / `LATE_BULL` / `TOP_SIGNAL` |
| `piCycleGapPct` | number \| null | Gap between the 111-day MA and 2× the 350-day MA (fraction) |
| `piCycleDaysToCross` | int \| null | Estimated days until the two averages cross; `-1` = diverging / already crossed |
| `piCycleMa111` | number \| null | 111-day moving average of BTC (USD) |
| `piCycleMa3502x` | number \| null | 2 × 350-day moving average of BTC (USD) |
| `blockHeight` | int \| null | Current Bitcoin block height |
| `daysSinceHalving` | int \| null | Days since the April 2024 halving |
| `daysToNextHalving` | int \| null | Estimated days to the next halving |
| `halvingPhase` | string \| null | `HALVING_RECENT` / `HALVING_EARLY` / `HALVING_MID` / `HALVING_LATE` |
| `plainExplanation` | string | 2–3 sentence plain-English summary (cycle agent, or a deterministic fallback) |
| `lastUpdated` | string | ISO 8601 time the response was built |
| `lastCouncilVerdictAt` | string \| null | Time of the most recent BTC council verdict |
```bash curl theme={null}
curl https://api.aioka.io/v1/cycle/status
```
```json 200 theme={null}
{
"cyclePhase": "UNKNOWN",
"cyclePhaseVerdict": "HOLD",
"mvrvZ": -0.65,
"nupl": 0.354,
"sopr": 0.974,
"piCyclePhase": 0,
"piCyclePhaseName": "BOTTOM_ZONE",
"piCycleGapPct": -0.543,
"piCycleDaysToCross": null,
"piCycleMa111": 70984.25,
"piCycleMa3502x": 155409.43,
"blockHeight": 970446,
"daysSinceHalving": 906,
"daysToNextHalving": 552,
"halvingPhase": "HALVING_LATE",
"plainExplanation": "BTC sits 906 days past the April 2024 halving, beyond the window in which earlier cycle peaks fired. On-chain valuation looks cheap while holders are still in profit, so the phase is unclear: hold and wait for clearer signals.",
"lastUpdated": "2026-10-08T05:20:46Z",
"lastCouncilVerdictAt": "2026-10-08T05:22:57Z"
}
```
## OpenAPI
````yaml GET /v1/cycle/status
openapi: 3.1.0
info:
title: AIOKA Intelligence API
description: |
## AI-powered crypto market intelligence
AIOKA Intelligence API provides real-time access to our AI Council verdicts,
market signals, regime detection, and Ghost Trader entry signals.
### Tiers
- **Free**: 100 calls/day — Verdict + Regime
- **Basic** ($49/mo): 1,000 calls/day — + Signals
- **Pro** ($199/mo): 10,000 calls/day — + Council + Ghost
### Authentication
Pass your API key in the `X-API-Key` header:
```
X-API-Key: aik_free_xxxxxxxxxxxx
```
### Get your API key
`POST /v1/keys/generate` (free tier, no credit card)
contact:
name: AIOKA Support
url: https://docs.aioka.io/
email: api@aioka.io
license:
name: Commercial
url: https://aioka.io/terms
version: 1.0.0
servers:
- url: https://api.aioka.io
description: Production — AIOKA Intelligence API
security: []
paths:
/v1/cycle/status:
get:
tags:
- BTC Cycle Context
summary: BTC Cycle Context
description: >-
Aggregated Bitcoin cycle context: deterministic CYCLE_PHASE classifier,
Pi Cycle Top status (Sprint 364), halving timing (Sprint 365
mempool.space),
on-chain valuation (MVRV_Z + NUPL + SOPR from Coin Metrics), and the
latest CYCLE_ANALYST agent plain-English narrative.
**Tier:** Public ✅
**Cache:** None -- always live from market_data
**Use:** aioka.io/live Cycle Intelligence card + /cycle Telegram command
Read-only -- never writes to any trading table.
operationId: get_cycle_status_v1_cycle_status_get
responses:
'200':
description: Live BTC cycle context
content:
application/json:
schema:
$ref: '#/components/schemas/CycleStatusResponse'
'429':
description: Rate limit exceeded
security: []
components:
schemas:
CycleStatusResponse:
properties:
cyclePhase:
type: string
title: Cyclephase
description: >-
BEAR_BOTTOM | EARLY_BULL | MID_BULL | LATE_BULL | TOP_SIGNAL |
UNKNOWN
cyclePhaseVerdict:
type: string
title: Cyclephaseverdict
description: >-
Deterministic verdict from the phase classifier (STRONG_BUY ->
STRONG_AVOID)
mvrvZ:
anyOf:
- type: number
- type: 'null'
title: Mvrvz
nupl:
anyOf:
- type: number
- type: 'null'
title: Nupl
sopr:
anyOf:
- type: number
- type: 'null'
title: Sopr
piCyclePhase:
anyOf:
- type: integer
- type: 'null'
title: Picyclephase
piCyclePhaseName:
anyOf:
- type: string
- type: 'null'
title: Picyclephasename
piCycleGapPct:
anyOf:
- type: number
- type: 'null'
title: Picyclegappct
piCycleDaysToCross:
anyOf:
- type: integer
- type: 'null'
title: Picycledaystocross
description: '-1 sentinel = diverging / already crossed'
piCycleMa111:
anyOf:
- type: number
- type: 'null'
title: Picyclema111
piCycleMa3502x:
anyOf:
- type: number
- type: 'null'
title: Picyclema3502X
blockHeight:
anyOf:
- type: integer
- type: 'null'
title: Blockheight
daysSinceHalving:
anyOf:
- type: integer
- type: 'null'
title: Dayssincehalving
daysToNextHalving:
anyOf:
- type: integer
- type: 'null'
title: Daystonexthalving
halvingPhase:
anyOf:
- type: string
- type: 'null'
title: Halvingphase
plainExplanation:
type: string
title: Plainexplanation
description: 2-3 sentence non-trader summary of the current cycle position
lastUpdated:
type: string
format: date-time
title: Lastupdated
lastCouncilVerdictAt:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Lastcouncilverdictat
description: >-
Most recent BTC council verdict timestamp (CYCLE_ANALYST agent runs
as part of each council convene). NULL until first council fires.
type: object
required:
- cyclePhase
- cyclePhaseVerdict
- plainExplanation
- lastUpdated
title: CycleStatusResponse
description: Aggregated Bitcoin cycle context.
example:
blockHeight: 895000
cyclePhase: MID_BULL
cyclePhaseVerdict: HOLD
daysSinceHalving: 380
daysToNextHalving: 1085
halvingPhase: HALVING_EARLY
lastCouncilVerdictAt: '2026-05-24T09:30:00+00:00'
lastUpdated: '2026-05-24T10:00:00+00:00'
mvrvZ: 2.4
nupl: 0.58
piCycleDaysToCross: 240
piCycleGapPct: -0.18
piCycleMa111: 95000
piCycleMa3502x: 115000
piCyclePhase: 2
piCyclePhaseName: MID_BULL
plainExplanation: >-
BTC sits mid-cycle, about 12 months past the April 2024 halving.
Valuation is elevated but not euphoric -- typical hold zone.
sopr: 1.04
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.