wzrd-client 1.1.0

Python client for the WZRD velocity oracle. Reads AI model adoption signals from 4 platforms. Agents stream CCM on Solana by reporting picks.

wzrd-client

Which AI model should your agent use right now? WZRD tracks real-time developer adoption across HuggingFace, GitHub, OpenRouter, and ArtificialAnalysis. 100+ models. Updated every 5 minutes. Free.

pip install wzrd-client

Pick a model (zero config)

import wzrd

model = wzrd.pick("code")           # → "Qwen/Qwen3.5-35B-A3B"
details = wzrd.pick_details("code") # trend, score, confidence
top_3 = wzrd.shortlist("code", 3)   # ranked list

No API key. No account. Works immediately.

Task types: code, chat, reasoning, math, multilingual — or any string (falls back to general ranking).

Earn CCM tokens (optional)

Agents that report which model they picked — and what happened — earn CCM tokens on Solana. The usage data makes the signal better, so WZRD pays for it.

wzrd.run_loop(keypair_path="~/.config/solana/id.json")
# authenticates → picks models → runs inference → reports → claims CCM

CCM (Concentrated Compute Merit) is a Solana token earned by contributing to the velocity oracle. It's not bought — it's earned through verified participation. Agents claim CCM through a gasless relay (no SOL needed for claiming).

What you need to earn: A Solana keypair (solana-keygen new if you don't have one). That's it.

Why use this?

• Save money: Models change weekly. The one you hardcoded last month might be 10x more expensive than the trending alternative.
• Better results: Momentum is a leading indicator. Models gaining adoption fast are usually improving fast.
• Get paid: Your usage reports make the oracle more accurate. WZRD pays for that with CCM tokens.

Raw API

GET https://api.twzrd.xyz/v1/signals/momentum

Premium data (velocity EMA, acceleration, quality): set WZRD_API_URL=https://api.twzrd.xyz/v1/signals/momentum/premium

Use as a routing prior

Read the oracle before calling an inference provider:

model = wzrd.pick("code")
models = wzrd.shortlist("chat")
details = wzrd.pick_details("reasoning")

Works with any provider. Pass the result to OpenRouter, OpenAI, Anthropic, HuggingFace, or your own router.

Candidate-aware routing

model = wzrd.pick(
    "code",
    candidates=[
        "openrouter/qwen/qwen3.5-9b",
        "openrouter/qwen/qwen3.5-35b-a3b",
        "anthropic/claude-sonnet-4.6",
    ],
)

Optional rewards while reporting

If you want an agent to authenticate, report routing decisions, and participate in WZRD rewards:

import wzrd

choice = wzrd.pick_details("code")

agent = wzrd.WZRDAgent.from_env()
session = agent.authenticate()
receipt = agent.report_pick(choice, quality_score=0.9, latency_ms=1200)
reward_status = agent.earned()

print(session.pubkey)
print(receipt["contribution_id"])
print(reward_status["signup_bonus_ccm"])

No manual onboarding is required. Agents can authenticate with their own Solana keypair, report real routing decisions, and claim rewards through the gasless relay when available.

Router wrapper

If you want a thin client wrapper, use WZRDRouter from wzrd.router. It only wraps clients that expose client.chat.completions.create(...). Explicit model names pass through unchanged. To trigger WZRD routing, pass model=None or a task sentinel like model="code" or model="chat".

Automatic reward loop

import wzrd

wzrd.run_loop()  # picks, reports, checks rewards, claims when available

run_loop() is the batteries-included path for unattended reporting. It uses the public momentum feed by default and can be pointed at premium explicitly via WZRD_API_URL.

Agent auth

WZRDAgent.authenticate() signs the exact server challenge message and sends the signature in the Solana base58 format the API expects. Keypair loading supports:

• ~/.config/solana/id.json
• WZRD_AGENT_KEYPAIR_PATH or SOLANA_KEYPAIR_PATH
• WZRD_AGENT_KEYPAIR or SOLANA_KEYPAIR as a base58 secret or JSON byte array

Authenticated helpers:

• agent.challenge() returns the nonce + message format
• agent.authenticate() stores the Bearer token on the client
• agent.status() reads /v1/agent/status
• agent.earned() reads /v1/agent/earned and surfaces signup bonus + reward status
• agent.report(...) posts a manual contribution
• agent.report_pick(choice, ...) reports a pick_details() result with WZRD metadata attached

The signup bonus is recorded on first auth, then becomes claimable after the next merkle publication cycle.

Environment variables

• WZRD_API_URL: signal endpoint override. Defaults to the public momentum feed.
• WZRD_API_BASE_URL: API root for agent auth/report calls
• WZRD_AGENT_TOKEN: existing Bearer token for WZRDAgent
• WZRD_AGENT_KEYPAIR_PATH: path to Solana JSON keypair
• WZRD_AGENT_KEYPAIR: Solana base58 secret or JSON byte array
• WZRD_TIMEOUT_SECONDS: request timeout
• WZRD_CACHE_TTL_SECONDS: cache TTL for fetched signals
• WZRD_FEED_LIMIT: number of feed rows to request

Verify on-chain

WZRD data is published to 9 Switchboard pull oracle feeds on Solana mainnet (7 velocity + 2 price). You can verify any signal independently:

# Query the Qwen 3.5 9B velocity feed directly on-chain
solana account AepiFwnbfCvXwA5gtAysMaxoqdwsGiYCN6gFBLGqZf1S --output json

# Or view on Solscan:
# https://solscan.io/account/AepiFwnbfCvXwA5gtAysMaxoqdwsGiYCN6gFBLGqZf1S

Sample feeds (quote accounts):

Model	Address
Qwen 3.5 9B	AepiFwnbfCvXwA5gtAysMaxoqdwsGiYCN6gFBLGqZf1S
Llama 3.3 70B	6EgRwhE6db1Aqsxzmp9wj6QH2y5ZEji1xe1YdovwmD9g
Kimi K2.5	5xmwRtTgcCz6R2KapxpEXVjCNcZCpe24DnCC295S769w
Qwen3-Coder-Next	g3RRSmg4PJjDNCq3jkTutMB8431UMMtRTNBRpc7UfVV

Full feed registry with all 7 velocity + 2 price feeds is available via wzrd.oracle.list_feeds().

What it returns

• pick() returns a model name string
• pick_details() returns a structured record
• shortlist() returns ranked records
• compare() explains the relative signal strength between two models
• WZRDAgent authenticates an agent wallet and reports contributions for rewards