numinous

Numinous Forecasting Tools

Numinous is a decentralized forecasting network (Bittensor Subnet 6). Miners submit Python forecasting agents; validators score them; this plugin wraps the public APIs the network exposes.

API surfaces

Base URL	What lives here	Docs Swagger
https://api.numinouslabs.io	Forecasts, leaderboard, miner agents, historical runs	/api/docs
https://signals.numinouslabs.io	Signals (news + market aggregation, LLM-scored)	/docs
https://api-eversight.numinouslabs.io	Balance, usage, costs (public), Stripe top-ups (browser only)	/docs

Credits are shared across all three — spend on forecasts or signals draws from the same balance.

First-run setup

Scripts live at ./scripts/ relative to this SKILL.md. The scripts work regardless of cwd, but paths in this doc assume you run them from the skill directory. Before running anything, check whether these env vars are set: NUMINOUS_API_KEY, NUMINOUS_X402_EVM_PRIVATE_KEY, NUMINOUS_X402_SVM_PRIVATE_KEY.

Then pick an auth path based on what the user wants:

User wants	Needs	Env var
Forecasts + signals, pay in USD via top-up	API key	NUMINOUS_API_KEY
Forecasts only, pay in crypto per request	Funded EVM wallet (USDC on Base)	NUMINOUS_X402_EVM_PRIVATE_KEY
Forecasts only, pay in crypto per request	Funded Solana wallet (USDC on Solana)	NUMINOUS_X402_SVM_PRIVATE_KEY

If neither is set, walk the user through the decision:

You can use Numinous two ways:

1. API key (recommended) — works for everything (forecasts + signals), prepaid credit balance. Create one at https://eversight.numinouslabs.io/api-keys (up to 5 per account) and top up at https://eversight.numinouslabs.io/payments. Set NUMINOUS_API_KEY=<your_key>.
2. x402 crypto payment — forecasts only (signals doesn't accept x402). No account needed, just a funded USDC wallet on Base or Solana. Set NUMINOUS_X402_EVM_PRIVATE_KEY=<hex> or NUMINOUS_X402_SVM_PRIVATE_KEY=<base58>.

Which would you like to set up?

Env vars should live in the user's shell environment (bash/zsh profile on macOS/Linux, PowerShell profile or System Properties on Windows) or a project-local .env file that's gitignored. Use whatever idiom matches the user's shell — e.g. export NUMINOUS_API_KEY=... for bash/zsh, $env:NUMINOUS_API_KEY = "..." for PowerShell, setx NUMINOUS_API_KEY "..." for Windows cmd. Never write keys to repo-committed files.

Capabilities & costs

Fetch current pricing at runtime — don't hardcode. The endpoint is public, no auth:

GET https://api-eversight.numinouslabs.io/api/v1/credits/costs

At time of writing:

Capability	Script / endpoint	Cost	Auth
Create a forecast (async job)	scripts/forecast.py	0.1 credits	API key
Create a forecast paying via crypto	scripts/forecast_x402.py	$0.10 USDC	x402 wallet
Get signals for a market/question	scripts/signals.py	0.025 credits	API key (no x402)
Check balance	GET /api/v1/me/balance	free	API key
Check usage history	GET /api/v1/me/usage	free	API key
Get current costs	GET /api/v1/credits/costs	free	none
Browse miner leaderboard	GET /api/v1/leaderboard	free	none
Read a miner's agent code	GET /api/v1/agents/{version_id}/code	free	none
Top up balance (Stripe)	web UI only	—	browser session

Runbooks

Get a forecast (most common path)

Two input modes. Structured is more precise; query is faster to compose.

Shell-quoting gotcha: if the question contains a $ sign, always use single quotes (bash/zsh/PowerShell all treat single quotes as literal). Double quotes will shell-expand $150k to 50k, silently asking a different question. When in doubt — or anytime a dollar amount is involved — prefer structured mode, which takes each field as a separate --title / --description flag with no substring ambiguity.

Query mode — one natural-language line:

python ./scripts/forecast.py 'Will Bitcoin exceed $150k before end of 2026?'

Structured mode — explicit event spec (safest when prices / $ are involved):

python ./scripts/forecast.py \
  --title 'Will Bitcoin exceed $150,000 before end of 2026?' \
  --description 'Resolves YES if BTC spot price on any major exchange reaches $150,000 USD at any point before 2026-12-31T23:59:59Z.' \
  --cutoff 2026-12-31T23:59:59Z \
  --topics crypto,finance

Pin a specific miner (any mode) with --agent-version-id <uuid>. Get version IDs from the leaderboard (see below). When unpinned, the network auto-routes to the top pool miner.

The script submits, polls every 5s, and prints the final probability plus the miner's reasoning. Typical completion: 25–120 seconds.

Pay for a forecast via crypto (x402)

Same args as the API-key forecast. Uses NUMINOUS_X402_EVM_PRIVATE_KEY (preferred) or NUMINOUS_X402_SVM_PRIVATE_KEY. Wallet must hold enough USDC ($0.10 per request).

python ./scripts/forecast_x402.py 'Will ETH exceed $10k before end of 2026?'

The x402 Python library auto-handles the 402 → sign → retry flow. No signals support — if the user asks to pay for signals via crypto, tell them it's not available and offer the API key route.

Get signals for a prediction market

Accepts a Polymarket URL, slug, condition_id, or a free-text question.

# Polymarket (URL or slug; compound event URLs and sub-market slugs both work)
python ./scripts/signals.py --market https://polymarket.com/event/some-slug

# Free-text question — use single quotes if the question contains $
python ./scripts/signals.py --question 'Will Iran conduct a nuclear test before end of 2026?'

Returns ranked signals from exa (web news), Indicia (geopolitics, Polymarket markets, LiveUAMap, GDELT, unusual_whales), and Perplexity — each scored by Grok with relevance_score (0-1), impact_score (0-1), impact_bucket (S1-S3 scenario ladder), direction (supports_yes / supports_no / neutral), and a one-sentence rationale.

Check balance and usage

No script needed — simple GET requests. Use whichever HTTP tool matches the user's environment (curl on Unix/Git Bash, Invoke-RestMethod on PowerShell, Python urllib.request, or your agent's WebFetch equivalent).

• Balance: GET https://api-eversight.numinouslabs.io/api/v1/me/balance with header X-API-Key: <NUMINOUS_API_KEY>
• Usage: GET https://api-eversight.numinouslabs.io/api/v1/me/usage?limit=50 (also accepts since=<ISO8601>, limit up to 200) with the same header

Bash example:

curl -s -H "X-API-Key: $NUMINOUS_API_KEY" https://api-eversight.numinouslabs.io/api/v1/me/balance

PowerShell example:

Invoke-RestMethod -Uri https://api-eversight.numinouslabs.io/api/v1/me/balance -Headers @{ "X-API-Key" = $env:NUMINOUS_API_KEY }

/me/usage transactions include a resource field — values are signal_compute or prediction_job. Use this to group spend by product (not the description string).

When the user wants to top up, send them to https://eversight.numinouslabs.io/payments (Stripe, browser-only).

Browse the leaderboard / inspect a miner

All public, no auth needed. Again, use any HTTP tool — examples shown in bash:

# Top miners (sorted by the active pool — currently global_brier by default)
curl -s "https://api.numinouslabs.io/api/v1/leaderboard?limit=10"

# A specific miner's agent versions
curl -s "https://api.numinouslabs.io/api/v1/miners/{miner_uid}/{miner_hotkey}/agents"

# Read the actual forecasting code a miner is running
curl -s "https://api.numinouslabs.io/api/v1/agents/{version_id}/code"

When the user wants to "pin" a miner in a forecast, grab a version_id from /agents and pass --agent-version-id to forecast.py.

Troubleshooting

Symptom	Cause	Fix
402 Payment Required, body {}, payment-required header set	No auth on a paid endpoint	Set NUMINOUS_API_KEY or use the _x402 script
401 on /me/*	X-API-Key missing or invalid	Re-check the env var, or rotate the key at /api-keys
404 MARKET_NOT_FOUND on signals	Polymarket slug stale / closed	Ask user for a current URL, or try a sub-market slug from their multi-market event
422 VALIDATION_ERROR on signals	Sent both market and question, or neither	Send exactly one
502 UPSTREAM_UNAVAILABLE on signals	Polymarket Gamma down	Transient, retry; or fall back to free-text --question
Forecast stuck PENDING > 3 min	Miner queue slow	Keep polling up to 5 min; occasionally miners retry
Can't reach api.numinouslabs.io/docs from an agent	Bot-blocked swagger UI	Read reference.md in this skill instead, or fetch https://api.numinouslabs.io/api/openapi.json (public)

Links for the user

• Create / manage API keys: https://eversight.numinouslabs.io/api-keys
• Top up balance (Stripe): https://eversight.numinouslabs.io/payments
• Leaderboard UI: https://leaderboard.numinouslabs.io
• Landing page: https://numinouslabs.io
• API reference (Swagger, browser only): https://api.numinouslabs.io/api/docs
• OpenAPI spec (scriptable): https://api.numinouslabs.io/api/openapi.json

Deeper reference

See reference.md for full endpoint schemas, response field definitions, forecaster names, x402 payment header format, and the impact_bucket ladder. Load it only when you need details the tables above don't cover.