@wzrd_sol/sdk 0.1.2 → 0.3.0

package/README.md

@@ -1,171 +1,153 @@
-# @wzrd_sol/sdk
+# WZRD — AI Model Velocity Oracle
 
-TypeScript SDK for the Liquid Attention Protocol on Solana.
-
-Builds `deposit_market`, `settle_market`, and `claim_global` transaction instructions that wallets sign directly — no server signing needed.
+Real-time adoption tracking for 100+ open-source AI models across HuggingFace, GitHub, OpenRouter, and ArtificialAnalysis. Free to read. Agents earn CCM on Solana.
 
 ## Install
 
 ```bash
-npm install @wzrd_sol/sdk @solana/web3.js
+pip install wzrd-client
 ```
 
-## Example Scripts
-
-From the repo root:
+```python
+import wzrd
 
-```bash
-npm run build --workspace=sdk
-npm run typecheck:examples --workspace=sdk
+model = wzrd.pick("code")      # Best model for coding right now
+details = wzrd.pick_details("reasoning")  # With score, trend, confidence
 ```
 
-Runnable examples:
+No API key. No auth. Returns in <100ms (cached).
 
-- `npm run example:deposit --workspace=sdk`
-- `npm run example:claim --workspace=sdk`
+## Earn CCM
 
-Both examples expect:
+Agents that contribute model selection data earn CCM tokens. The loop is: **authenticate, pick, infer, report, claim.**
 
-- `SOLANA_RPC_URL`
-- `WZRD_KEYPAIR_PATH`
+```python
+import wzrd
 
-The deposit example also expects:
+wzrd.run_loop(
+    keypair="~/.config/solana/id.json",
+    tasks=["code", "chat", "reasoning"],
+    cycle_seconds=60,
+)
+```
 
-- `WZRD_MARKET_ID`
-- `WZRD_DEPOSIT_USDC`
+Claims are gasless — no SOL required. Server-witnessed inference ensures real usage.
 
-## Quick Reference
+**[Full getting-started guide](https://twzrd.xyz/start)**
 
-### PDA Derivation
+## MCP
 
-```typescript
-import {
-  getProtocolStatePDA,
-  getMarketVaultPDA,
-  getUserPositionPDA,
-  getGlobalRootConfigPDA,
-  getClaimStatePDA,
-  PROGRAM_ID,
-} from '@wzrd_sol/sdk';
-
-const protocolState = getProtocolStatePDA();
-const marketVault = getMarketVaultPDA(protocolState, 6); // market ID 6
-const position = getUserPositionPDA(marketVault, walletPubkey);
+26 tools. Zero config. Connect from Claude Desktop, Cursor, or any MCP client.
+
+```json
+{
+  "mcpServers": {
+    "wzrd": {
+      "transport": "streamable-http",
+      "url": "https://app.twzrd.xyz/api/mcp"
+    }
+  }
+}
 ```
 
-### Deposit USDC → Receive vLOFI
+Hero tool: `pick_model` — one call, best model for your task.
 
-```typescript
-import { Connection, Keypair, VersionedTransaction, TransactionMessage } from '@solana/web3.js';
-import { createDepositMarketIx } from '@wzrd_sol/sdk';
+## TypeScript SDK
 
-const connection = new Connection('https://api.mainnet-beta.solana.com');
-const wallet = Keypair.fromSecretKey(/* your key */);
+Full instruction builders for the on-chain protocol: deposit, settle, claim, LP.
 
-// Build instructions for a 1 USDC deposit into market 6
-const ixs = await createDepositMarketIx(connection, wallet.publicKey, 6, 1_000_000n);
+```bash
+npm install @wzrd_sol/sdk
+```
 
-const { blockhash } = await connection.getLatestBlockhash();
-const message = new TransactionMessage({
-  payerKey: wallet.publicKey,
-  recentBlockhash: blockhash,
-  instructions: ixs,
-}).compileToV0Message();
+```typescript
+import { createDepositMarketIx } from '@wzrd_sol/sdk';
 
-const tx = new VersionedTransaction(message);
-tx.sign([wallet]);
-const sig = await connection.sendTransaction(tx);
-console.log('Deposit tx:', sig);
+const ixs = await createDepositMarketIx(connection, wallet, marketId, 1_000_000n);
 ```
 
-### Claim CCM via Merkle Proof
-
-```typescript
-import { createClaimGlobalIx } from '@wzrd_sol/sdk';
+### Framework Plugins
 
-// Fetch proof from the server API
-const res = await fetch(`https://api.twzrd.xyz/v1/claims/${wallet.publicKey.toBase58()}`);
-const { root_seq, cumulative_total, proof } = await res.json();
+| Framework | Package | Install |
+|-----------|---------|---------|
+| ElizaOS | `@wzrd_sol/eliza-plugin` | `npm i @wzrd_sol/eliza-plugin` |
+| Solana Agent Kit | `@wzrd_sol/solana-agent-plugin` | `npm i @wzrd_sol/solana-agent-plugin` |
+| GOAT | `@wzrd_sol/goat-plugin` | `npm i @wzrd_sol/goat-plugin` |
 
-const ixs = await createClaimGlobalIx(
-  connection,
-  wallet.publicKey,
-  root_seq,
-  BigInt(cumulative_total),
-  proof, // hex-encoded [u8; 32] nodes
-);
+## Python API
 
-// Build, sign, send as above
-```
+| Function | What it does |
+|----------|-------------|
+| `wzrd.pick(task)` | Best model name for a task |
+| `wzrd.pick_details(task)` | Structured result with score, trend, confidence |
+| `wzrd.shortlist(task, limit=5)` | Top N ranked models |
+| `wzrd.compare(a, b)` | Head-to-head comparison |
+| `wzrd.pick_onchain(task)` | Trustless — reads Switchboard feeds directly |
+| `wzrd.run_loop(keypair=...)` | Full earn loop: auth, pick, report, claim |
+| `WZRDRouter(client)` | Drop-in wrapper for OpenAI/Anthropic clients |
 
-### Settle a Matured Position
+## Public API
 
-```typescript
-import { createSettleMarketIx } from '@wzrd_sol/sdk';
+Base URL: `https://api.twzrd.xyz`
 
-const ixs = await createSettleMarketIx(connection, wallet.publicKey, 6);
-// Build, sign, send as above
+```
+GET  /v1/signals/momentum   — model velocity signals
+GET  /v1/leaderboard        — ranked attention markets
+GET  /v1/markets/:id        — single market detail
+GET  /v1/feeds              — Switchboard oracle feeds
+GET  /health                — service health
 ```
 
-`settle_market` returns USDC from reserve and burns vLOFI. It does not mint CCM; CCM is claimed via merkle proof (`claim_global` / `claim_global_v2`).
+Full spec: [openapi.json](https://api.twzrd.xyz/openapi.json)
 
-### Read On-Chain State
+## Links
 
-```typescript
-import { fetchMarketVault, fetchOnChainPosition, fetchTokenBalance } from '@wzrd_sol/sdk';
+| | |
+|---|---|
+| Get Started | [twzrd.xyz/start](https://twzrd.xyz/start) |
+| Live Feed | [twzrd.xyz/feed](https://twzrd.xyz/feed) |
+| MCP Guide | [twzrd.xyz/mcp-guide.md](https://twzrd.xyz/mcp-guide.md) |
+| Machine Manifest | [twzrd.xyz/llms.txt](https://twzrd.xyz/llms.txt) |
+| API | [api.twzrd.xyz/v1/leaderboard](https://api.twzrd.xyz/v1/leaderboard) |
+| PyPI | [wzrd-client](https://pypi.org/project/wzrd-client/) |
+| npm | [@wzrd_sol/sdk](https://www.npmjs.com/package/@wzrd_sol/sdk) |
 
-const vault = await fetchMarketVault(connection, 6);
-console.log('Total deposited:', vault?.totalDeposited);
+## Key Identifiers
 
-const pos = await fetchOnChainPosition(connection, wallet.publicKey, 6);
-console.log('My deposit:', pos?.depositedAmount, 'Multiplier:', pos?.attentionMultiplierBps);
-```
+| Item | Address |
+|------|---------|
+| Program | `GnGzNdsQMxMpJfMeqnkGPsvHm8kwaDidiKjNU2dCVZop` |
+| CCM Mint | `Dxk8mAb3C7AM8JN6tAJfVuSja5yidhZM5sEKW3SRX2BM` (Token-2022, 50 BPS transfer fee) |
+| vLOFI Mint | `E9Kt33axpCy3ve2PCY9BSrbPhcR9wdDsWQECAahzw2dS` |
 
-## Exports
+## Architecture
 
-### Constants
-
-| Export | Description |
-|--------|-------------|
-| `PROGRAM_ID` | Mainnet program ID (`GnGz...`) |
-| `DEVNET_PROGRAM_ID` | Devnet program ID (`GmGX...`) |
-| `TOKEN_PROGRAM_ID` | SPL Token program |
-| `TOKEN_2022_PROGRAM_ID` | Token-2022 program (CCM uses this) |
+```
+wzrd-final/
+├── programs/attention-oracle/    # On-chain program (Solana)
+├── server/                       # Backend API + background jobs (Axum/Rust)
+├── app/                          # Frontend (React/Vite)
+├── sdk/                          # TypeScript SDK — 35 instruction builders
+├── integrations/wzrd-client/     # Python client (PyPI: wzrd-client)
+├── agents/                       # 13 agent implementations across 6 frameworks
+├── crates/                       # Rust crates (stream ingestor, merkle, types)
+├── ops/                          # Deployment scripts
+└── migrations/                   # SQL migrations
+```
 
-### PDA Derivation
+## Build
 
-| Function | Seeds |
-|----------|-------|
-| `getProtocolStatePDA()` | `["protocol_state"]` |
-| `getMarketVaultPDA(protocolState, marketId)` | `["market_vault", protocolState, marketId]` |
-| `getUserPositionPDA(marketVault, user)` | `["market_position", marketVault, user]` |
-| `getGlobalRootConfigPDA(ccmMint)` | `["global_root", ccmMint]` |
-| `getClaimStatePDA(ccmMint, claimer)` | `["claim_global", ccmMint, claimer]` |
+```bash
+# Server
+cargo build -p wzrd-server
 
-### Instruction Builders
+# Frontend
+cd app && npm install && npm run dev
 
-| Function | On-chain instruction |
-|----------|---------------------|
-| `createDepositMarketIx(conn, user, marketId, amount)` | `deposit_market` |
-| `createSettleMarketIx(conn, user, marketId)` | `settle_market` |
-| `createClaimGlobalIx(conn, claimer, rootSeq, total, proof)` | `claim_global` |
-| `createInitializeMarketVaultIx(admin, marketId, ...)` | `initialize_market_vault` |
+# On-chain program
+anchor build
+```
 
-### Account Parsers
+## License
 
-| Function | Account type |
-|----------|-------------|
-| `parseMarketVault(data)` | `MarketVault` |
-| `parseProtocolState(data)` | `ProtocolState` |
-| `parseUserMarketPosition(data)` | `UserMarketPosition` |
-| `fetchMarketVault(conn, marketId)` | Fetch + parse |
-| `fetchOnChainPosition(conn, user, marketId)` | Fetch + parse |
-| `fetchTokenBalance(conn, ata)` | Raw token balance |
-
-## Key Addresses
-
-| Asset | Mint | Token Program |
-|-------|------|---------------|
-| USDC | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` | SPL Token |
-| vLOFI | `E9Kt33axpCy3ve2PCY9BSrbPhcR9wdDsWQECAahzw2dS` | SPL Token |
-| CCM | `Dxk8mAb3C7AM8JN6tAJfVuSja5yidhZM5sEKW3SRX2BM` | Token-2022 |
+All rights reserved. Source available for transparency and agent integration.

package/dist/accounts.d.ts

@@ -42,6 +42,16 @@ export interface OnChainPosition {
     settled: boolean;
     entrySlot: bigint;
 }
+export type LifecyclePhase = 'deposited' | 'accruing' | 'claimable' | 'claimed' | 'settled';
+export interface LifecyclePhaseInput {
+    settled: boolean;
+    positionCreatedAt?: Date | string | null;
+    latestRootCreatedAt?: Date | string | null;
+    latestProofCreatedAt?: Date | string | null;
+    proofCumulativeTotalBase?: bigint | number | null;
+    claimedTotalBase?: bigint | number | null;
+    claimableCcmBase?: bigint | number | null;
+}
 /** Parse a MarketVault account's core fields (skip Anchor discriminator). */
 export declare function parseMarketVault(data: Buffer): MarketVaultData;
 /**
@@ -54,6 +64,7 @@ export declare function parseMarketVault(data: Buffer): MarketVaultData;
 export declare function parseProtocolState(data: Buffer): ProtocolStateData;
 /** Parse a UserMarketPosition account. Returns null if data is too short. */
 export declare function parseUserMarketPosition(data: Buffer): OnChainPosition | null;
+export declare function deriveLifecyclePhase(input: LifecyclePhaseInput): LifecyclePhase;
 /** Fetch a user's position for a specific market directly from chain. */
 export declare function fetchOnChainPosition(connection: Connection, user: PublicKey, marketId: number, programId?: PublicKey): Promise<OnChainPosition | null>;
 /** Fetch the full MarketVault data from chain. */

package/dist/accounts.js

@@ -42,7 +42,7 @@ export function parseProtocolState(data) {
 }
 /** Parse a UserMarketPosition account. Returns null if data is too short. */
 export function parseUserMarketPosition(data) {
-    if (data.length < 106)
+    if (data.length < 114)
         return null;
     const d = data.subarray(8); // skip Anchor discriminator
     return {
@@ -55,6 +55,45 @@ export function parseUserMarketPosition(data) {
         entrySlot: d.readBigUInt64LE(90),
     };
 }
+function toMillis(value) {
+    if (!value)
+        return null;
+    const date = value instanceof Date ? value : new Date(value);
+    const time = date.getTime();
+    return Number.isFinite(time) ? time : null;
+}
+function toBigIntOrZero(value) {
+    if (typeof value === 'bigint')
+        return value;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return BigInt(Math.trunc(value));
+    return 0n;
+}
+export function deriveLifecyclePhase(input) {
+    if (input.settled)
+        return 'settled';
+    const positionCreatedAtMs = toMillis(input.positionCreatedAt);
+    const latestRootCreatedAtMs = toMillis(input.latestRootCreatedAt);
+    if (positionCreatedAtMs !== null &&
+        (latestRootCreatedAtMs === null || latestRootCreatedAtMs < positionCreatedAtMs)) {
+        return 'deposited';
+    }
+    const latestProofCreatedAtMs = toMillis(input.latestProofCreatedAt);
+    const proofAppliesToPosition = positionCreatedAtMs === null ||
+        (latestProofCreatedAtMs !== null && latestProofCreatedAtMs >= positionCreatedAtMs);
+    const claimableCcmBase = toBigIntOrZero(input.claimableCcmBase);
+    if (proofAppliesToPosition && claimableCcmBase > 0n) {
+        return 'claimable';
+    }
+    const proofCumulativeTotalBase = toBigIntOrZero(input.proofCumulativeTotalBase);
+    const claimedTotalBase = toBigIntOrZero(input.claimedTotalBase);
+    if (proofAppliesToPosition &&
+        proofCumulativeTotalBase > 0n &&
+        claimedTotalBase >= proofCumulativeTotalBase) {
+        return 'claimed';
+    }
+    return 'accruing';
+}
 // ── Fetch Helpers ──────────────────────────────────────
 /** Fetch a user's position for a specific market directly from chain. */
 export async function fetchOnChainPosition(connection, user, marketId, programId) {

package/dist/accounts.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/accounts.test.js

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+import { deriveLifecyclePhase } from './accounts.js';
+describe('deriveLifecyclePhase', () => {
+    it('returns settled when the position is settled', () => {
+        expect(deriveLifecyclePhase({ settled: true })).toBe('settled');
+    });
+    it('returns deposited before any newer root has landed', () => {
+        expect(deriveLifecyclePhase({
+            settled: false,
+            positionCreatedAt: '2026-03-17T10:00:00Z',
+            latestRootCreatedAt: '2026-03-17T09:59:59Z',
+        })).toBe('deposited');
+    });
+    it('returns claimable when an unclaimed proof exists after the position', () => {
+        expect(deriveLifecyclePhase({
+            settled: false,
+            positionCreatedAt: '2026-03-17T10:00:00Z',
+            latestRootCreatedAt: '2026-03-17T10:05:00Z',
+            latestProofCreatedAt: '2026-03-17T10:06:00Z',
+            proofCumulativeTotalBase: 50n,
+            claimedTotalBase: 25n,
+            claimableCcmBase: 25n,
+        })).toBe('claimable');
+    });
+    it('returns claimed when the latest proof is fully claimed', () => {
+        expect(deriveLifecyclePhase({
+            settled: false,
+            positionCreatedAt: '2026-03-17T10:00:00Z',
+            latestRootCreatedAt: '2026-03-17T10:05:00Z',
+            latestProofCreatedAt: '2026-03-17T10:06:00Z',
+            proofCumulativeTotalBase: 50n,
+            claimedTotalBase: 50n,
+            claimableCcmBase: 0n,
+        })).toBe('claimed');
+    });
+    it('returns accruing when no proof applies to the position yet', () => {
+        expect(deriveLifecyclePhase({
+            settled: false,
+            positionCreatedAt: '2026-03-17T10:00:00Z',
+            latestRootCreatedAt: '2026-03-17T10:05:00Z',
+            latestProofCreatedAt: '2026-03-17T09:55:00Z',
+            proofCumulativeTotalBase: 50n,
+            claimedTotalBase: 50n,
+            claimableCcmBase: 0n,
+        })).toBe('accruing');
+    });
+});

package/dist/agent-auth.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Agent Auth — Ed25519 challenge/verify handshake + inference/report/earned helpers.
+ *
+ * Stateless functions for the WZRD agent API. Used by AgentLoop and
+ * directly by any TypeScript agent that needs to authenticate and earn CCM.
+ *
+ * Runtime dependency: tweetnacl (direct dep — required for Ed25519 signing).
+ *
+ * @module agent-auth
+ */
+import type { Keypair } from '@solana/web3.js';
+/** Response from the challenge endpoint. */
+export interface ChallengeResponse {
+    nonce: string;
+    message_format: string;
+}
+/** Response from the verify endpoint. */
+export interface VerifyResponse {
+    token: string;
+    pubkey: string;
+    expires_at: string;
+}
+/** Response from the infer endpoint. */
+export interface InferResponse {
+    execution_id: string | null;
+    quality_score: number | null;
+    latency_ms: number | null;
+    cost_usd: number | null;
+    provider: string | null;
+    executed_model: string | null;
+    response_preview: string | null;
+}
+/** Response from the report endpoint. */
+export interface ReportResponse {
+    pending_ccm: number;
+    status: string;
+}
+/** Response from the earned endpoint. */
+export interface EarnedResponse {
+    total_earned_ccm: number;
+    pending_ccm: number;
+    rank: number | null;
+    contribution_streak_days: number;
+    pipeline: {
+        state: string | null;
+        next_root_eta_secs: number | null;
+        hint: string | null;
+    } | null;
+}
+/**
+ * Request a challenge nonce from the WZRD server.
+ */
+export declare function agentChallenge(apiBase?: string): Promise<ChallengeResponse>;
+/**
+ * Submit a signed challenge for verification. Returns a session token.
+ */
+export declare function agentVerify(pubkey: string, nonce: string, signature: string, apiBase?: string): Promise<VerifyResponse>;
+/**
+ * Full auth flow: challenge -> sign -> verify -> token.
+ *
+ * Uses tweetnacl (transitive dep of @solana/web3.js) for Ed25519 signing.
+ * Message format: `wzrd-agent-auth v1 | wallet:{pubkey} | nonce:{nonce}`
+ */
+export declare function agentAuth(keypair: Keypair, apiBase?: string): Promise<string>;
+/**
+ * Run server-witnessed inference. Returns execution_id for verified reports.
+ *
+ * The server calls the LLM, grades the response, and stores an execution
+ * receipt. Pass the returned `execution_id` to `agentReport()` so the
+ * contribution is marked verified (highest reward tier).
+ */
+export declare function agentInfer(token: string, model: string, taskType: string, apiBase?: string): Promise<InferResponse>;
+/**
+ * Report a model pick for reward eligibility.
+ */
+export declare function agentReport(token: string, modelId: string, opts?: {
+    taskType?: string;
+    executionId?: string | null;
+    qualityScore?: number | null;
+    latencyMs?: number | null;
+    costUsd?: number | null;
+    outcome?: string;
+    /** Full WZRD signal metadata — mirrors Python report_pick().metadata.wzrd */
+    metadata?: Record<string, unknown>;
+}, apiBase?: string): Promise<ReportResponse>;
+/**
+ * Check earned CCM status.
+ */
+export declare function agentEarned(token: string, apiBase?: string): Promise<EarnedResponse>;

package/dist/agent-auth.js

@@ -0,0 +1,147 @@
+/**
+ * Agent Auth — Ed25519 challenge/verify handshake + inference/report/earned helpers.
+ *
+ * Stateless functions for the WZRD agent API. Used by AgentLoop and
+ * directly by any TypeScript agent that needs to authenticate and earn CCM.
+ *
+ * Runtime dependency: tweetnacl (direct dep — required for Ed25519 signing).
+ *
+ * @module agent-auth
+ */
+// ── Constants ────────────────────────────────────────────────────
+const DEFAULT_API_BASE = 'https://api.twzrd.xyz';
+// ── Base58 Encoder (inline — avoids adding bs58 as a direct dep) ─
+const BASE58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+function base58Encode(bytes) {
+    let zeroes = 0;
+    for (let i = 0; i < bytes.length && bytes[i] === 0; i++)
+        zeroes++;
+    const size = Math.ceil(bytes.length * 138 / 100) + 1;
+    const b58 = new Uint8Array(size);
+    let length = 0;
+    for (let i = zeroes; i < bytes.length; i++) {
+        let carry = bytes[i];
+        let j = 0;
+        for (let k = size - 1; k >= 0 && (carry !== 0 || j < length); k--, j++) {
+            carry += 256 * b58[k];
+            b58[k] = carry % 58;
+            carry = Math.floor(carry / 58);
+        }
+        length = j;
+    }
+    let result = '1'.repeat(zeroes);
+    let started = false;
+    for (let i = size - length; i < size; i++) {
+        if (!started && b58[i] === 0)
+            continue;
+        started = true;
+        result += BASE58_ALPHABET[b58[i]];
+    }
+    return result || '1';
+}
+// ── Auth Functions ───────────────────────────────────────────────
+/**
+ * Request a challenge nonce from the WZRD server.
+ */
+export async function agentChallenge(apiBase = DEFAULT_API_BASE) {
+    const resp = await fetch(`${apiBase}/v1/agent/challenge`);
+    if (!resp.ok)
+        throw new Error(`[wzrd] challenge failed: ${resp.status}`);
+    return resp.json();
+}
+/**
+ * Submit a signed challenge for verification. Returns a session token.
+ */
+export async function agentVerify(pubkey, nonce, signature, apiBase = DEFAULT_API_BASE) {
+    const resp = await fetch(`${apiBase}/v1/agent/verify`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ pubkey, nonce, signature }),
+    });
+    if (!resp.ok)
+        throw new Error(`[wzrd] verify failed: ${resp.status}`);
+    return resp.json();
+}
+/**
+ * Full auth flow: challenge -> sign -> verify -> token.
+ *
+ * Uses tweetnacl (transitive dep of @solana/web3.js) for Ed25519 signing.
+ * Message format: `wzrd-agent-auth v1 | wallet:{pubkey} | nonce:{nonce}`
+ */
+export async function agentAuth(keypair, apiBase = DEFAULT_API_BASE) {
+    // tweetnacl is a direct dependency (declared in package.json)
+    const naclMod = await import('tweetnacl');
+    const nacl = naclMod.default ?? naclMod;
+    const pubkey = keypair.publicKey.toBase58();
+    const { nonce } = await agentChallenge(apiBase);
+    const message = `wzrd-agent-auth v1 | wallet:${pubkey} | nonce:${nonce}`;
+    const messageBytes = new TextEncoder().encode(message);
+    const sig = nacl.sign.detached(messageBytes, keypair.secretKey);
+    const signatureB58 = base58Encode(sig);
+    const session = await agentVerify(pubkey, nonce, signatureB58, apiBase);
+    return session.token;
+}
+// ── API Functions ────────────────────────────────────────────────
+/**
+ * Run server-witnessed inference. Returns execution_id for verified reports.
+ *
+ * The server calls the LLM, grades the response, and stores an execution
+ * receipt. Pass the returned `execution_id` to `agentReport()` so the
+ * contribution is marked verified (highest reward tier).
+ */
+export async function agentInfer(token, model, taskType, apiBase = DEFAULT_API_BASE) {
+    const resp = await fetch(`${apiBase}/v1/agent/infer`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${token}`,
+        },
+        body: JSON.stringify({ model, task_type: taskType }),
+    });
+    if (!resp.ok)
+        throw new Error(`[wzrd] infer failed: ${resp.status}`);
+    return resp.json();
+}
+/**
+ * Report a model pick for reward eligibility.
+ */
+export async function agentReport(token, modelId, opts = {}, apiBase = DEFAULT_API_BASE) {
+    const payload = {
+        model_id: modelId,
+        outcome: opts.outcome ?? 'success',
+    };
+    if (opts.taskType != null)
+        payload.task_type = opts.taskType;
+    if (opts.executionId != null)
+        payload.execution_id = opts.executionId;
+    if (opts.qualityScore != null)
+        payload.quality_score = opts.qualityScore;
+    if (opts.latencyMs != null)
+        payload.latency_ms = opts.latencyMs;
+    if (opts.costUsd != null)
+        payload.cost_usd = opts.costUsd;
+    if (opts.metadata != null)
+        payload.metadata = opts.metadata;
+    const resp = await fetch(`${apiBase}/v1/agent/report`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${token}`,
+        },
+        body: JSON.stringify(payload),
+    });
+    if (!resp.ok)
+        throw new Error(`[wzrd] report failed: ${resp.status}`);
+    return resp.json();
+}
+/**
+ * Check earned CCM status.
+ */
+export async function agentEarned(token, apiBase = DEFAULT_API_BASE) {
+    const resp = await fetch(`${apiBase}/v1/agent/earned`, {
+        headers: { Authorization: `Bearer ${token}` },
+    });
+    if (!resp.ok)
+        throw new Error(`[wzrd] earned check failed: ${resp.status}`);
+    return resp.json();
+}