📚 Bella Ciao — Public API Reference

Bella Ciao's public narratives API exposes the crew's 15-minute decision cycles as structured JSON. Designed for partner hedge bots, SaaS subscribers, and integrators who want the signals without running the whole trader.

Base URL: https://bellaciao.live/api/v1/public

Auth tiers: Tier 0 — Preview open access, rate-limited by IP. Tier 1 — Partner requires X-API-Key header with a key issued by the Bella Ciao team. Enforcement toggled via BELLA_API_KEY_ENFORCEMENT on the server — when on, missing or unknown keys return 401.

Every authenticated request is logged (partner, endpoint, latency, status) into the api_usage table for billing + SLO monitoring.

Endpoints

GET /api/v1/public/narratives/latest

The most recent cycle's structured signal + narrative.

Query parameters

Name	Type	Default	Description
`lang`	string	`ka`	Language: `ka` (Georgian) or `en` (English).
`include_prose`	bool	`true`	Include the full narrative text. Set `false` for a lightweight signal-only payload (~3KB vs ~40KB).

Example

Request bash

curl 'https://bellaciao.live/api/v1/public/narratives/latest?lang=en&include_prose=false'

Response json

{
  "cycle_number": 42,
  "generated_at": "2026-04-23T07:30:12Z",
  "lang": "en",
  "final": {
    "signal": "bullish",
    "confidence_pct": 62,
    "action_plan": {
      "entry": 78169.72,
      "stop_loss": 76900.0,
      "stop_loss_pct": -1.0,
      "take_profit_1": 79363.68,
      "take_profit_1_pct": 2.18,
      "take_profit_2": 79800.0,
      "take_profit_2_pct": 2.74,
      "risk_reward_ratio": 2.1,
      "position_size_pct": 0.75,
      "time_horizon": "swing",
      "human_readable": "- **Entry:** `$78,169.72` ..."
    }
  },
  "crew_summary": {
    "Tokio":     { "signal": "bullish", "confidence_pct": 72 },
    "Berlin":    { "signal": "neutral", "confidence_pct": 48 },
    "Helsinki":  { "signal": "neutral", "confidence_pct": 52 },
    "Denver":    { "signal": "bullish", "confidence_pct": 67 },
    "Nairobi":   { "signal": "bullish", "confidence_pct": 62 },
    "Marseille": { "signal": "neutral", "confidence_pct": 72 }
  },
  "data_sources_used": [
    "binance_spot", "binance_futures", "coinglass",
    "lunarcrush", "cryptoquant", "santiment",
    "coinmarketcal", "twelvedata", "alternative_me"
  ],
  "meta": {
    "model": "gemini-2.5-flash",
    "cost_usd": 0.0051,
    "generation_ms": 4523,
    "cache_source": "redis_latest"
  }
}

GET /api/v1/public/narratives/cycle/{cycle_number}

A specific historical cycle. Served from Redis if ≤ 14 days old, else Postgres archive.

Path parameter

Name	Type	Description
`cycle_number`	int	Cycle number (monotonically increasing).

Example

Request bash

curl 'https://bellaciao.live/api/v1/public/narratives/cycle/42?lang=en'

404 if the cycle never existed or aged past the archive.

GET /api/v1/public/narratives

Paginated list of recent cycles as lightweight stubs. Use for bulk sync — then request individual cycles for full bodies.

Query parameters

Name	Type	Default	Description
`limit`	int	`24`	1 — 200. Default ~6 hours of cycles.
`lang`	string	`ka`	Reserved for future — stubs don't currently vary by language.

Example response

{
  "count": 24,
  "lang": "ka",
  "cycles": [
    { "cycle_number": 42, "generated_at": "2026-04-23T07:30:12Z",
      "final_signal": "bullish", "final_confidence_pct": 62 },
    { "cycle_number": 41, "generated_at": "2026-04-23T07:15:04Z",
      "final_signal": "bullish", "final_confidence_pct": 58 },
    ...
  ]
}

GET /api/v1/public/narratives/stats

Aggregate stats over recent cycles — cost, latency percentiles, cycle cadence, signal breakdown. Useful for billing forecasting + SLO monitoring.

Query parameters

Name	Type	Default	Description
`hours`	int	`24`	1 — 720. Window size in hours.

Example

Request bash

curl 'https://bellaciao.live/api/v1/public/narratives/stats?hours=24'

Response json

{
  "window_hours": 24,
  "cycles": 95,
  "duration_ms": {
    "avg": 42310,
    "p50": 41200,
    "p95": 58400,
    "max": 61000
  },
  "cost_usd": {
    "total": 0.465,
    "avg_per_cycle": 0.00489,
    "daily_projection": 0.469
  },
  "final_signal_breakdown": {
    "bullish": 38,
    "bearish": 22,
    "neutral": 35
  }
}

Expected values (healthy prod, measured 2026-04-23): ~96 cycles per 24h (15-min cadence), ~100-130 s avg duration, $0.020-$0.027/cycle on Gemini Flash, ~$2.00-$2.50/day projection.

GET /api/v1/data-sources

Inventory of the 9 data providers feeding the crew. Safe to embed in partner UIs — no secrets.

Example

Request bash

curl 'https://bellaciao.live/api/v1/data-sources'

Authentication

Tier 1 — `X-API-Key` header

Partners receive a key of the form bca_live_<random> (plaintext shown ONCE at issuance). Pass it on every request:

Request bash

curl -H 'X-API-Key: bca_live_abc123...' \
     'https://bellaciao.live/api/v1/public/narratives/latest'

Response headers

Header	Meaning
`X-Partner-Name`	(future) the partner identity the key resolved to.
`X-Rate-Limit-Remaining`	(future) requests left in the current minute window.

Error responses

Status	When	What to do
`401`	Missing or unknown `X-API-Key` (enforcement on).	Verify the key is correct + hasn't been revoked. Contact your Bella Ciao representative.
`403`	Key valid but revoked.	Request a new key.
`429`	Rate limit exceeded.	Back off with exponential delay.

Key rotation

Keys have no built-in expiration. Rotate by requesting a fresh key from the Bella Ciao team — both keys work concurrently while you roll over, then the old key is revoked. Best practice: quarterly rotation at minimum, plus immediate rotation on any suspected exposure.

Tier 0 preview

When enforcement is OFF (development / staging / Tier 0 preview), the X-API-Key header is accepted but not validated. Start sending it now and your integration is automatically ready for Tier 1 switchover with no code changes.

Signal semantics

Field	Type	Meaning
`final.signal`	string	One of `bullish` / `bearish` / `neutral` / `monitoring`.
`final.confidence_pct`	int 0-100	El Profesor's weighted-consensus confidence.
`final.action_plan.entry`	float	Suggested entry price (USDT). Paper signal — no execution guarantee.
`final.action_plan.stop_loss`	float	Suggested SL price (USDT).
`final.action_plan.take_profit_1`	float	First TP (partial close target).
`final.action_plan.take_profit_2`	float	Second TP (trail target).
`final.action_plan.risk_reward_ratio`	float	Computed R:R. > 2.0 = acceptable setup.
`final.action_plan.position_size_pct`	float	% of account size recommendation.
`final.action_plan.time_horizon`	string	One of `scalp` / `day` / `swing` / `position`.
`crew_summary.{agent}`	dict	Each crew member's individual vote — useful for weighing against your own signals.

⚠ Not financial advice. Bella Ciao signals are decision inputs, not guaranteed profitable trades. Use at your own risk. Bella Ciao is not responsible for subscriber P&L.

Rate limits

Tier	Rate	Endpoints
Tier 0	120 req/min per IP	All `/api/v1/public/*`
Tier 1	Per-subscriber quota (contract)	All + higher ceilings

429 responses indicate rate-limit breach. Back off and retry with exponential delay. Bella Ciao's cycles run every 15 minutes — there's rarely a reason to poll faster than every 30 seconds.

Getting started

Try GET /api/v1/public/narratives/latest from your browser or curl.
Subscribe to new cycles with a poll loop at 30-second cadence — cycles resolve at :00, :15, :30, :45.
For historical training data, pull with GET /api/v1/public/narratives?limit=200, then iterate over cycle_number.
Start passing X-API-Key when you have one — no enforcement yet, but it future-proofs your integration.
Contact Bella Ciao for Tier 1 onboarding when you're ready to go live.

Support

Contact the Bella Ciao engineering team via your Coinmania integration channel. Issues, feature requests, and SLA conversations happen there.

Endpoints

Query parameters

Example

Path parameter

Example

Query parameters

Example response

Query parameters

Example

Example

Authentication

Tier 1 — X-API-Key header

Response headers

Error responses

Key rotation

Tier 0 preview

Signal semantics

Rate limits

Getting started

Support

Tier 1 — `X-API-Key` header