Circle Intelligence SDK

Python SDK for Circle Intelligence — real-time F.I.R.E. economy signal detection via 7-agent AI cascade.

What's new in 0.3.1

• Per-method timeout kwarg. Every RF data-fetch method now accepts a per-call timeout override:

  candidates = sdk.rf.list_market_candidates(limit=10, timeout=90)
  config     = sdk.rf._get_config(timeout=60)
  market     = sdk.rf.get_market_intelligence("0x...", timeout=45)
  

  Falls back to the SDK-level timeout you passed to CircleSDK(...).
• Auto retry with exponential backoff. _get() now retries up to 2 extra times (3 attempts total) on timeouts, connection errors, 429, and 5xx responses. Backoff is 1s, 2s, 4s. Transient Circle hiccups no longer surface as immediate failures. Override the retry count on any call: sdk._get(path, retries=5).

What's new in 0.3.0

• Refreshed RF contract defaults (realityFuturesMarkets, pScoreOracle) to match the 2026-04-21 on-chain redeploy. Earlier versions had stale addresses in the fallback path — pin >=0.3.0 if you transact real USDC.
• config["source"] marker. sdk.rf._get_config() now returns "source": "fetched" (from /api/rf/config) or "source": "defaults" (baked-in fallback). Check this before broadcasting any tx.
• strict=True mode. CircleSDK(url, strict=True) raises CircleConfigError on config-fetch failure instead of silently falling back to stale defaults. Recommended for production agents.
• Louder fallback warning. If you're in non-strict mode, the log message now says "SDK USING BAKED-IN DEFAULTS" so it's not missed in grep.

The timeout kwarg was already configurable in 0.2.0 (CircleSDK(url, timeout=60)) — applies to every HTTP call including /api/rf/config.

Install

pip install circle-intelligence              # core (browsing, search, chat)
pip install circle-intelligence[wallet]       # + wallet authentication
pip install circle-intelligence[payment]      # + USDC payment flow
pip install circle-intelligence[rf]           # + RealityFutures trading

Quick Start

from circle_intelligence import CircleSDK

# Free tier — no auth needed
sdk = CircleSDK("https://circle.news")
signals = sdk.get_recent_signals(limit=3)
entities = sdk.get_kg_entities(search="Bitcoin")
briefs = sdk.get_briefs(limit=5)

# Premium tier — with API key
sdk = CircleSDK("https://circle.news", api_key="circ_your_key")
results = sdk.search_signals("DeFi bridge exploit")
analytics = sdk.get_kg_analytics(days=7)
response = sdk.chat(signal_id=1744, messages=[{"role": "user", "content": "What happened?"}])

Features

Wallet Authentication (for agents)

from eth_account import Account
from eth_account.messages import encode_defunct

private_key = "0xYOUR_PRIVATE_KEY"
wallet = Account.from_key(private_key).address

result = sdk.authenticate(
    wallet_address=wallet,
    sign_fn=lambda msg: Account.sign_message(
        encode_defunct(text=msg), private_key
    ).signature.hex(),
)

Documentation

Full API reference and examples at circle.news/docs