DataCamp Workspace

Run in a DataCamp workspace terminal or notebook cell:

# In a notebook cell (the ! prefix runs shell commands in Jupyter)
!pip install headless-oracle

# Or in the workspace terminal:
pip install headless-oracle

The package includes verify(), OracleClient, and optional LangChain/CrewAI tools. No extra dependencies required for basic use.

Request a key from a notebook cell. It arrives in the response immediately:

import requests

resp = requests.post(
    "https://headlessoracle.com/v5/keys/instant",
    json={"agent_id": "my-datacamp-notebook"}
)
print(resp.json())
# {"key": "ho_free_...", "plan": "free", "requests_per_day": 500}

Free keys allow 500 requests/day across all 28 exchanges. No credit card required. Store your key as an environment variable, not in the notebook itself.

Fetch a signed receipt and verify it in 3 lines:

import os
from headless_oracle import OracleClient, verify, VerificationError

# In DataCamp workspaces, use environment variables for secrets
oracle = OracleClient(api_key=os.environ["ORACLE_KEY"])

receipt = oracle.get_status("XNYS")   # NYSE
print(f"NYSE is: {receipt['status']}")  # OPEN or CLOSED

# Verify the Ed25519 signature — don't skip this
verify(receipt)
print("✓ Receipt signature verified")

A complete notebook pattern — check status first, run analysis only if market is confirmed OPEN:

import os
import pandas as pd
from headless_oracle import OracleClient, verify, VerificationError

ORACLE_KEY = os.environ.get("ORACLE_KEY", "")
oracle = OracleClient(api_key=ORACLE_KEY)

EXCHANGES = ["XNYS", "XNAS", "XLON", "XJPX", "XPAR", "XHKG", "XSES"]


def safe_market_check(mic: str) -> dict:
    """
    Fetch and verify a signed receipt. Returns a dict with:
      - status: OPEN | CLOSED | HALTED | UNKNOWN
      - safe:   True only if OPEN and signature verified
      - reason: human-readable explanation
    """
    try:
        receipt = oracle.get_status(mic)
        verify(receipt)                   # raises VerificationError if invalid
        is_open = receipt["status"] == "OPEN"
        return {
            "mic": mic,
            "status": receipt["status"],
            "safe": is_open,
            "reason": "Verified OPEN" if is_open else f"Market is {receipt['status']}",
            "expires_at": receipt.get("expires_at"),
        }
    except VerificationError as e:
        return {"mic": mic, "status": "UNKNOWN", "safe": False,
                "reason": f"Signature verification failed: {e}", "expires_at": None}
    except Exception as e:
        return {"mic": mic, "status": "UNKNOWN", "safe": False,
                "reason": f"Oracle error: {e}", "expires_at": None}


# ── Check all exchanges ────────────────────────────────────────────────────

results = [safe_market_check(mic) for mic in EXCHANGES]
df = pd.DataFrame(results)

display(df[["mic", "status", "safe", "reason"]].style.applymap(
    lambda v: "color: #4ade80" if v is True else ("color: #f87171" if v is False else ""),
    subset=["safe"]
))


# ── Gate your analysis on verified OPEN markets ───────────────────────────

open_markets = [r["mic"] for r in results if r["safe"]]

if not open_markets:
    print("⛔ No markets currently open. Analysis halted.")
else:
    print(f"✓ Running analysis for open markets: {', '.join(open_markets)}")
    # --- your analysis code goes here ---
    for mic in open_markets:
        print(f"  → Fetching data for {mic}...")

No auth required for schedule queries — useful for planning notebook runs:

import requests
from datetime import datetime, timezone

def get_schedule(mic: str) -> dict:
    resp = requests.get(f"https://headlessoracle.com/v5/schedule?mic={mic}")
    resp.raise_for_status()
    return resp.json()

nyse = get_schedule("XNYS")
now = datetime.now(timezone.utc).isoformat()

print(f"Current UTC:     {now}")
print(f"NYSE next open:  {nyse.get('next_open', 'already open')}")
print(f"NYSE next close: {nyse.get('next_close', 'N/A')}")
print(f"Timezone:        {nyse['timezone']}")
print(f"Holiday?         {nyse.get('is_holiday', False)}")

x402 Micropayments (autonomous agents)

If you're building autonomous agent notebooks that need to make API calls without a pre-provisioned key, Headless Oracle supports x402 micropayments. Free tier keys automatically handle 402 responses — or agents can pay 0.001 USDC per request on Base mainnet.

# Free tier: 500 req/day, no payment needed
# After the limit: agent pays per-request via x402 (0.001 USDC on Base)

oracle = OracleClient(api_key="ho_free_your_key_here")
receipt = oracle.get_status("XNYS")   # auto-handles 429 / 402 if configured

Important