Oracle-X API

Oracle-X

Oracle-X is a self-hosted financial intelligence terminal: a FastAPI backend that pulls equities and digital assets into one universe, keeps a vector memory of what it has seen, and reasons over both through an LLM layer the operator chooses. This skill is the read side of that backend.

Prerequisite: an instance has to be running. This skill talks to a server; it is not a data source of its own. If nothing answers, say so — do not fall back to remembered prices. A number invented for a trading question is worse than no number.

Setup

Two environment variables, and neither belongs in a file you write:

Confirm the instance is alive before the first real call:

curl -sf "${ORACLE_X_URL:-http://localhost:8000}/api/system/health" | head -c 400

/api/system/health is passive — it reports what the last real call to each upstream did and issues no requests of its own, so polling it costs nothing. A category reporting degraded there explains an empty payload downstream better than any retry will.

If the connection is refused, tell the user the terminal is not running and stop. If a specific category is down, answer with what the healthy categories returned and name the gap.

Choosing an endpoint

Most requests are one call. Find the row, read the endpoint's full parameters in references/endpoints.md, call it.

Anything not in this table is in references/endpoints.md — read that before inventing a path. Guessed URLs return 404s that look like missing data.

Rules that keep the answer honest

These matter more than endpoint coverage, because the failure they prevent is the one that costs the user money.

Report what the API returned, and nothing else. A 404 from /api/price or /api/technical means the symbol could not be resolved — the backend deliberately refuses to emit a placeholder. Say "the terminal has no price for that symbol" rather than supplying one from memory.

Do not recompute what the terminal computed. /api/technical already builds zones per timeframe and scores them by confluence. Deriving your own support level from candles produces a number that contradicts what the user sees on their own screen, which is worse than not answering.

Reach for /api/chat deliberately. It runs the full planner and costs an LLM call on the operator's own provider budget. For "what is BTC trading at", call /api/price. For "should I be worried about this setup", the chat endpoint is the right tool — it has the same data plus the memory and the reasoning. Check GET /api/chat/status first; it says whether a provider is actually serving.

Timestamps are part of the answer. Most payloads carry one. Market data without a time is a claim about now that may be about an hour ago; quote it.

Send the symbol in the form the endpoint expects. Crypto pairs are BTCUSDT or BINANCE:ETHUSDT; equities are the plain ticker with ?type=stock where the route takes one. A 404 on a symbol you believe exists is usually the wrong form rather than missing data — references/endpoints.md records which routes care.

Fan out rather than asking one endpoint to do everything. There is no single "tell me about X" call. A full read on an asset is four independent requests — price, technicals, leverage, memory — and since none depends on another they cost one round trip when issued together. references/recipes.md has the sequence.

Long-running work: the job pattern

Analysis and chat generation take minutes, so they are not held open on a connection. Three endpoints follow the same shape — start, then poll:

Poll on an interval of a few seconds and give up after a couple of minutes with an explanation, rather than blocking indefinitely. examples/03_chat_job.py implements this loop.

Authentication

Most of what an agent needs is open on a default instance: prices, technicals, news, macro, chains, liquidations, ownership, RAG. Authentication is needed only for endpoints scoped to a person — chat, watchlist, and starting an analysis job.

Send the JWT as Authorization: Bearer $ORACLE_X_TOKEN. Read it from the environment; never write it into a file, a URL, or a log line. If it is absent and the user's question needs an authenticated endpoint, ask them for it rather than falling back to an unauthenticated call that will 401.

A 404 on GET /api/chat/jobs/{job_id} may mean the job belongs to someone else — the backend answers 404 rather than 403 there on purpose, so do not read it as "the job vanished".

references/auth.md covers where a token comes from and how to test one.

A first call

BASE="${ORACLE_X_URL:-http://localhost:8000}"

curl -sf "$BASE/api/price/BTCUSDT"
curl -sf "$BASE/api/technical/AAPL"
curl -sf "$BASE/api/rag/query?q=bitcoin%20halving%20price%20behavior&symbol=BTC"
curl -sf -H "Authorization: Bearer $ORACLE_X_TOKEN" \
     -H 'Content-Type: application/json' \
     -d '{"message":"How does the current BTC setup compare to March?"}' \
     "$BASE/api/chat"

Symbols follow the venue: crypto pairs are BTCUSDT or BINANCE:ETHUSDT, equities are the plain ticker, AAPL. Passing AAPL where a pair is expected used to route an equity through the crypto path; the backend now decides by inspecting the symbol, but sending the right form is still cheaper.

When something goes wrong

Reference files

Read these on demand rather than upfront:

• references/endpoints.md — every allowlisted endpoint with its parameters, request body and response fields. Generated from the running schema, so it matches the deployed API. Consult it before any call that is not a plain path from the table above.
• references/auth.md — obtaining and using a token, and which endpoints need one.
• references/recipes.md — the multi-step reads: a full asset workup, a news-to-thesis pass, a macro-plus-chains regime check.
• examples/ — runnable Python (httpx) for the client, the job polling loop, and a complete asset workup.