coinbellai 0.1.0

Official Python SDK for the CoinBell AI crypto prediction API

CoinBell AI — Python SDK

Embed CoinBell AI crypto price forecasts into your Python application.

Install

pip install coinbellai

Quickstart

from coinbellai import Client

client = Client(api_key="cb_live_...")  # or set COINBELL_API_KEY

# predict() submits the job and polls until it's done (~120s typical).
result = client.predict("bitcoin", duration=7, model="nova-pulse")

print(result["prediction"])           # full forecast object
print(result["completedAt"])

Get an API key from the CoinBell dashboard → Settings → API Keys.

Async (submit + poll)

Predictions take ~120s, so the API is asynchronous. predict() blocks and polls for you; if you'd rather manage it yourself (job queues, webhooks, UIs):

job = client.submit("bitcoin", duration=7, model="nova-pulse")
print(job["id"], job["status"])       # -> "...", "queued"

# later — poll yourself, or use client.wait(job["id"])
status = client.get_prediction(job["id"])
if status["status"] == "completed":
    print(status["prediction"])

predict()

Argument	Type	Default	Notes
symbol	str	—	CoinGecko coin id, e.g. "bitcoin", "ethereum"
duration	int	7	Forecast horizon in days (1–90)
model	str	"nova-spark"	nova-spark (1cr), nova-pulse (3cr), nova-cortex (10cr)
current_price	float	None	Optional; fetched server-side if omitted
language	str	"en"	"en" or "zh"
context	str	None	Optional free-text to steer the analysis

Configuration

• COINBELL_API_KEY — used when api_key is not passed.
• COINBELL_BASE_URL — override the API base URL (self-host / staging).

Errors

from coinbellai import (
    AuthenticationError,       # 401 — bad/missing/revoked key
    InsufficientCreditsError,  # 402 — not enough credits
    RateLimitError,            # 429 — has .retry_after
    APIError,                  # other 4xx/5xx
    CoinBellError,             # base class
)

try:
    client.predict("bitcoin")
except InsufficientCreditsError as e:
    print("Top up credits:", e.body)
except RateLimitError as e:
    print("Slow down, retry after", e.retry_after, "s")

Zero runtime dependencies (stdlib urllib only). Python 3.8+.