langchain-wzrd

LangChain tools for WZRD velocity signals. Real-time model selection across 100+ LLMs.

Install

pip install langchain-wzrd

Quickstart: earn CCM with a LangChain agent (one run, ~6 minutes)

This walks you from pip install to a LangChain ReAct agent earning $CCM on Solana mainnet — no wallet extension, no seed phrase to copy, no faucet to visit. The whole run takes about 6 minutes end-to-end, most of which is the script waiting 5 minutes for the WZRD global merkle root to publish so your rewards become claimable.

What you'll see

A LangGraph ReAct agent whose reasoning brain is velocity-picked from free OpenRouter models. The agent calls two WZRD tools: WzrdModelPicker to read live model momentum, and WzrdEarnTool (with max_cycles=2) to run the full earn loop: cycle 1 registers a fresh agent keypair and earns into reward_bonuses, the script waits 5 minutes for the publisher to fold the bonuses into the next global root, then cycle 2 claims the CCM to your wallet. On first run, the WZRD server auto-funds the fresh keypair with gas SOL, so you never need to touch a wallet UI or visit a faucet.

1. Install

pip install 'langchain-wzrd[chat]' langgraph

2. Get a free OpenRouter key

Sign up at https://openrouter.ai/keys (no credit card needed for the free models the example uses). Then:

export OPENROUTER_API_KEY=sk-or-v1-...

3. Run

curl -O https://raw.githubusercontent.com/twzrd-sol/wzrd-final/main/integrations/langchain-wzrd/examples/earn_agent.py
python earn_agent.py

That's it. No keypair generation. No faucet visit. The script:

1. Velocity-picks an agent brain from live OpenRouter free models
2. Auto-generates ~/.config/solana/wzrd-agent.json (deliberately refuses to touch your ~/.config/solana/id.json)
3. Authenticates with the WZRD oracle, which auto-grants gas SOL to the fresh keypair in the background so claims are truly gasless
4. Runs cycle 1: reports a server-witnessed inference, earning into reward_bonuses (a 1,000 CCM signup bonus + ~200 CCM per verified inference)
5. Waits ~5 minutes while the global merkle root publisher folds the fresh bonuses into the next on-chain root
6. Runs cycle 2: the claim path now sees published allocations and claims the CCM to your wallet via gasless relay
7. Prints the wallet pubkey, the claim transaction signature, and verification commands

4. Verify

wzrd wallet      # shows your auto-generated keypair + balances
wzrd balance     # shows CCM balance and lifetime earnings

Or paste the wallet pubkey into Solscan to see the auto-grant transactions and CCM token balance directly on-chain.

What's the magic?

• No wallet UI: wzrd-client auto-generates a dedicated agent keypair on first run and explicitly refuses to use ~/.config/solana/id.json, so your main wallet is never touched.
• No faucet: the WZRD server's onboard_new_agent flow auto-grants gas SOL to fresh keypairs in the background. The gas grant uses an idempotency lock so you only get one per pubkey. Claims are truly gasless, so the tiny SOL grant is all you ever need.
• No model selection: every cycle, the agent reads https://api.twzrd.xyz/v1/signals/momentum and picks the top model by composite trend × velocity × confidence.
• No transaction building: WzrdEarnTool wraps wzrd.run_loop(), which handles auth, inference, reporting, and claim-via-gasless-relay all in one function. The LangChain agent just decides when to call it.

Source: examples/earn_agent.py

Tools

WzrdModelPicker (free, zero config)

Returns the best model for a task based on live adoption velocity.

from langchain_wzrd import WzrdModelPicker
from langchain.agents import initialize_agent, AgentType
from langchain_openai import ChatOpenAI

tools = [WzrdModelPicker()]
llm = ChatOpenAI(model="gpt-4o-mini")
agent = initialize_agent(tools, llm, agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION)
agent.run("What's the best model for code generation right now?")

With LangGraph:

from langchain_wzrd import WzrdModelPicker
from langgraph.prebuilt import create_react_agent

tools = [WzrdModelPicker()]
agent = create_react_agent(llm, tools)
result = agent.invoke({"messages": [("user", "Which model has the most momentum?")]})

WzrdInference (paid, requires API key)

Runs inference through WZRD's oracle. Auto-selects the top velocity model if none specified.

from langchain_wzrd import WzrdInference

tools = [WzrdInference(api_key="your-key")]
# or set WZRD_API_KEY env var and use WzrdInference() with no args

ChatWZRD (velocity-routed ChatModel)

Drop-in ChatModel that auto-routes every call to the top velocity model.

from langchain_wzrd import ChatWZRD

llm = ChatWZRD(task="code", openai_api_key="sk-or-...")
response = llm.invoke("Write a Python sort function")

How it works

Signals are cached for 60s. The free momentum endpoint requires no auth. Models are ranked by a composite of trend direction, velocity score, and confidence.