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 URLWhat lives hereDocs Swaggerhttps://api.numinouslabs.ioForecasts, leaderboard, miner agents, historical runs/api/docshttps://signals.numinouslabs.ioSignals (news + market aggregation, LLM-scored)/docshttps://api-eversight.numinouslabs.ioBalance, 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 wantsNeedsEnv varForecasts + signals, pay in USD via top-upAPI keyNUMINOUS_API_KEYForecasts only, pay in crypto per requestFunded EVM wallet (USDC on Base)NUMINOUS_X402_EVM_PRIVATE_KEYForecasts only, pay in crypto per requestFunded 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:

CapabilityScript / endpointCostAuthCreate a forecast (async job)scripts/forecast.py0.1 creditsAPI keyCreate a forecast paying via cryptoscripts/forecast_x402.py$0.10 USDCx402 walletGet signals for a market/questionscripts/signals.py0.025 creditsAPI key (no x402)Check balanceGET /api/v1/me/balancefreeAPI keyCheck usage historyGET /api/v1/me/usagefreeAPI keyGet current costsGET /api/v1/credits/costsfreenoneBrowse miner leaderboardGET /api/v1/leaderboardfreenoneRead a miner's agent codeGET /api/v1/agents/{version_id}/codefreenoneTop 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:

bash

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

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

bash

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).

bash

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.

bash

# 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:

bash

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

PowerShell example:

powershell

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:

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#

SymptomCauseFix402 Payment Required, body {}, payment-required header setNo auth on a paid endpointSet NUMINOUS_API_KEY or use the _x402 script401 on /me/*``X-API-Key missing or invalidRe-check the env var, or rotate the key at /api-keys404 MARKET_NOT_FOUND on signalsPolymarket slug stale / closedAsk user for a current URL, or try a sub-market slug from their multi-market event422 VALIDATION_ERROR on signalsSent both market and question, or neitherSend exactly one502 UPSTREAM_UNAVAILABLE on signalsPolymarket Gamma downTransient, retry; or fall back to free-text --questionForecast stuck PENDING > 3 minMiner queue slowKeep polling up to 5 min; occasionally miners retryCan't reach api.numinouslabs.io/docs from an agentBot-blocked swagger UIRead 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.