@wzrd_sol/sdk

TypeScript SDK for agentic x402 payments: vet-before-pay trust gates, portable signed receipts, and an agent loop. Settles on Solana today.

The primary trust + MCP surface is twzrd-agent-intel (https://intel.twzrd.xyz). This SDK carries the same trust/receipt layer. It also still exports the Solana instruction builders of a retired on-chain protocol; those exports are legacy and unmaintained (see "Legacy On-Chain Builders" below).

Receipt versions and keys (read this first)

• Paid GET /v1/intel/trust issues V7 receipts today, signed by key id twzrd-receipt-ed25519-v2, public key Ak5SQwHpuQAqU7ty7ZWX7qgF39A9yi72c22KNn8sHzvS.
• verifyReceipt verifies V5, V6 and V7 receipts offline. V5/V6 leaves are recomputed by this SDK; V7 receipts (preimage domain exactly TWZRD:AO_REPUTATION_RECEIPT_V7) are delegated to the published twzrd-receipt-verifier package (a dependency since 0.4.10), which binds the freshness triple into the leaf. The result shape is the same for every version; leafVersion reports 'v7' for the delegated path. A V7 receipt that fails is a real failure (bad leaf, bad signature, or an untrusted key).
• Independent second check for any receipt version, without this SDK:

npx 'twzrd-receipt-verifier@^1.4.0' receipt.json --pubkey Ak5SQwHpuQAqU7ty7ZWX7qgF39A9yi72c22KNn8sHzvS

• The v1 key id (twzrd-receipt-ed25519-v1, pubkey 9V6Pn19kiUA5Rn6JpQfNduanvGt2aXGwsarosNfa2Ldf) is legacy: it is accepted only when verifying older receipts. New receipts are signed by the v2 key above. Pin the key out-of-band in your own config rather than trusting the response that carried the receipt.

The agent loop

Every paid agent action runs the same four steps - only step 3 touches a chain:

1. Discover - find a seller/resource you might pay (any x402 endpoint).
2. Preflight - intelPreflight(seller) returns a free ReadinessCard; decision: 'block' means stop. (chain-agnostic HTTP)
3. First paid hop - fetchIntelQuick(seller, { fetchImpl: x402Fetch }) settles $0.001 GET /v1/intel/quick. Optional: fetchIntelTrust at $0.05 returns a V7 receipt. (USDC on Solana today)
4. Verify - check the receipt offline. verifyReceipt(resp.twzrd_receipt) checks the Ed25519 signature + keccak leaf (V5/V6 in-process, V7 via twzrd-receipt-verifier). (chain-agnostic crypto)

preSpendGate() wraps all four in a single call. The receipt is the unit of value: a portable proof your agent vetted the counterparty before money moved.

Try it (no wallet, no signup)

npx @wzrd_sol/sdk

Fetches the public sample receipt from intel.twzrd.xyz and verifies it offline: recomputes the keccak leaf from the preimage and checks the Ed25519 signature against TWZRD's published key set. No env vars, no arguments. (After npm install the same command is available as twzrd-verify.) Pass a file path (npx @wzrd_sol/sdk receipt.json, a bare receipt or an API body carrying twzrd_receipt) to verify a saved receipt with no network at all. The command exits 1 when the receipt does not verify.

The result reports valid, leafValid, signatureValid, leafVersion, unauthenticatedFields, and errors. The live sample is a V7 receipt today and verifies in place (leafVersion: "v7", checked by twzrd-receipt-verifier); V5 and V6 receipts verify the same way with the SDK's own hasher:

{
  "valid": true,
  "leafValid": true,
  "signatureValid": true,
  "trustedPubkey": "Ak5SQwHpuQAqU7ty7ZWX7qgF39A9yi72c22KNn8sHzvS",
  "errors": [],
  "leafVersion": "v7",
  "unauthenticatedFields": []
}

From there, run a free preflight on any seller before paying (repo example; the published package ships the verify bin + library; clone this repo to run examples/):

# Preflight TWZRD's own intel service wallet (free, no USDC needed)
npx tsx examples/pre-spend-gate.ts   # defaults to the TWZRD seller wallet, or pass any pubkey

SDK Version Lines

The package is published with two dist-tags:

• latest (0.4.0+): The active line. Trust/receipt layer (preSpendGate, intelPreflight, fetchIntelQuick, fetchIntelTrust, signed receipts, verifyReceipt, evaluateRecall) + agent rail (AgentLoop, ModelSelector, agent auth/report). The legacy on-chain builders remain exported for existing integrations.

• v0-1 (pinned at 0.1.4): Legacy protocol-only maintenance line. Core PDAs, parsers, deposit_market / settle_market, claim_global (v1 + v2). No agent primitives, no x402/trust.

npm view @wzrd_sol/sdk dist-tags
# v0-1: 0.1.4 (legacy, pinned)  |  latest: the active 0.4.x line - run the command for the exact current patch

Why the split exists: The 0.1.x line is a maintenance backport for legacy/pinned integrations that have not migrated to the agent + trust surface. All new work lands on latest.

Legacy-only builders (present only on latest, annotated @deprecated in source): createStakeChannel*, createClaimChannelRewards*, createMintSharesIx / createRedeemSharesIx, createSettlePredictionIx, createPublishStreamRootIx / createClaimStream*. These target instructions that are not dispatched by the immutable mainnet binary (they return Custom 101). They are kept only so existing imports keep compiling; they are unmaintained and should not be used.

New work (x402 receipts, portable verifiable reputation, pre-spend trust) lives on latest. The on-chain protocol the builders targeted is retired.

One-call pre-spend gate

preSpendGate() wraps the whole discover -> preflight -> (pay) -> verify loop in a single call. Run it before paying any x402 seller:

import { preSpendGate } from '@wzrd_sol/sdk';

const gate = await preSpendGate(
  { seller_wallet: sellerPubkey, price_usdc: 0.25, agent_intent: 'swap_quote' },
  { escalateAboveUsdc: 0.2, fetchImpl: x402Fetch }, // escalate big spends to $0.001 /quick
);
if (!gate.allow) throw new Error(`blocked: ${gate.reason}`);
// gate.decision / gate.trustScore / gate.receipt / gate.receiptValid

Fail-open by default: a real block blocks the spend, but a gate outage allows it with gateAvailable=false so a trust-service blip never silently halts payments. See examples/pre-spend-gate.ts.

Install

npm install @wzrd_sol/sdk @solana/web3.js

@solana/web3.js is a peer dependency, so install it alongside the SDK.

Quick Start

Prove You Vetted A Seller (Receipt Loop)

The canonical flow: free preflight -> first paid hop -> optional paid receipt -> offline verify.

import { intelPreflight, fetchIntelQuick, fetchIntelTrust, verifyReceipt, evaluateRecall } from '@wzrd_sol/sdk';

const seller = 'JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4'; // example: Jupiter

// 1. Preflight (free - no wallet, no USDC, no signup).
// price_usdc is the caller's real unit price. Leftover unlabeled 0.05 is not a unit price.
const pf = await intelPreflight({
  seller_wallet: seller,
  price_usdc: 0.25,
  agent_intent: 'swap_quote',
});
const card = pf.readiness_card;

if (card?.decision === 'block') {
  console.log('Seller flagged:', card.caveats); // abort the payment
} else {
  // 2. First paid hop ($0.001 GET /quick). Do not auto-settle $0.05 /trust.
  const quick = await fetchIntelQuick(seller, { fetchImpl: x402Fetch });
  if ((quick.score ?? 0) < 30) throw new Error(`quick hop blocked score=${quick.score}`);
  // Optional portable receipt (V7 today): const resp = await fetchIntelTrust(seller, { fetchImpl: x402Fetch });

  // 3. Verify offline only if you bought /trust. Otherwise skip.
  //    V5, V6 and V7 receipts all verify in-process (V7 via twzrd-receipt-verifier):
  // const result = await verifyReceipt(resp.twzrd_receipt!);
  // const recall = evaluateRecall(resp.twzrd_receipt!, undefined, result);
  // if (recall.untrusted || recall.trustedDue) { /* re-call /trust before next spend */ }
  // Passing `result` is what lets a verified V7 receipt report freshnessBound=true;
  // without it (or on V5/V6) the recall stays untrusted-recheck.
}

Runnable end-to-end version: tsx examples/preflight-and-receipt.ts <sellerPubkey>.

The receipt is the unit of value: every vet-before-pay decision produces a portable, Ed25519-signed proof that your agent checked the counterparty before money moved. No token to hold, no position to manage - the receipt itself is the asset.

Agent Loop (Advanced)

For agents running the full auth -> pick -> infer -> report -> claim cycle:

import { AgentLoop } from '@wzrd_sol/sdk';
import { Keypair } from '@solana/web3.js';

const keypair = Keypair.fromSecretKey(/* your secret key bytes */);

const loop = new AgentLoop({
  keypair,
  tasks: ['code', 'chat', 'reasoning'],
  cycleSeconds: 300,
  claim: true,
});

loop.start();

This runs the full external-agent flow: auth, pick, infer, report, and gasless claim. Requires on-chain agent registration.

Example Scripts

From the repo root:

npm run build --workspace=sdk
npm run typecheck:examples --workspace=sdk

Runnable examples:

• tsx examples/verify-live-receipt.ts - fetch a real signed receipt from intel.twzrd.xyz and run the SDK verifier on it offline (no wallet, no mocks). The sample is V7 today and reports leafVersion: 'v7'.
• tsx examples/preflight-and-receipt.ts <sellerPubkey> [priceUsdc] - full loop: preflight free, first paid hop /quick $0.001, optional paid receipt
• tsx examples/pre-spend-gate.ts <sellerPubkey> [priceUsdc] - one-call pre-spend gate (wraps the loop above)
• npm run example:deposit --workspace=sdk - legacy on-chain builder example (retired protocol; kept for reference only)
• npm run example:claim --workspace=sdk - legacy on-chain builder example (retired protocol; kept for reference only)

The receipt examples need no env vars (preflight + offline verify are free; the paid step prints x402 requirements without a payer). The legacy examples expect:

• SOLANA_RPC_URL
• WZRD_KEYPAIR_PATH

The deposit example also expects:

• WZRD_MARKET_ID
• WZRD_DEPOSIT_USDC

Quick Reference

Verify a Receipt Offline (Trust Nothing)

import { evaluateRecall, verifyReceipt } from '@wzrd_sol/sdk';

// Fetch a real receipt from https://intel.twzrd.xyz/v1/intel/trust/<pubkey>
// (requires x402 payment). /trust issues V7 today; verifyReceipt covers V5, V6 and V7
// (V7 is delegated to the twzrd-receipt-verifier package). Independent second check:
//   npx 'twzrd-receipt-verifier@^1.4.0' receipt.json --pubkey Ak5SQwHpuQAqU7ty7ZWX7qgF39A9yi72c22KNn8sHzvS

const result = await verifyReceipt(receipt); // defaults to the published TWZRD key set
// result.valid === true means the receipt was signed by TWZRD and not tampered with.
// result.leafVersion tells you which leaf layout was checked ('v5', 'v6' or 'v7').
// Pin the key out-of-band: verifyReceipt(receipt, { trustedPubkey: TRUSTED_RECEIPT_PUBKEY })
// TRUSTED_RECEIPT_PUBKEY is the current v2 key (Ak5SQw...); LEGACY_RECEIPT_PUBKEYS holds the
// retired v1 keys, accepted only for older receipts.
const recall = evaluateRecall(receipt, undefined, result);
// V5/V6 freshness is untrusted. Do not treat shouldRecheck / due as a leaf-bound allow.
// V7 freshness (recheck_after_unix, staleness_days, score_decay_model) is bound into the
// leaf; evaluateRecall reports freshnessBound=true only when the passing verifyReceipt
// result is passed in (since 0.4.11). The V7 domain string alone never binds. The result must
// be the value verifyReceipt returned for that same, unmodified receipt; anything else (a
// hand-built result, a result for another receipt, a receipt edited after verification)
// reports freshness as unbound.

Rail-agnostic. Verification is pure keccak-256 + Ed25519 - no Solana RPC, no chain client. The receipt leaf folds the payer and settlement tx through rail-neutral byte fallbacks, so verifyReceipt validates a receipt that references a payment on any rail (Solana today, Base/x402, etc.), not just Solana. This is enforced by a test that signs and verifies a Base/EVM-referencing receipt end-to-end (src/intel.test.ts -> "rail-agnostic receipts"). Settlement is Solana USDC today; the portable proof is not.

Fetch an Intel Trust Receipt (Paid)

import { fetchIntelTrust, IntelPaymentRequiredError } from '@wzrd_sol/sdk';

// Inject an x402-capable fetch (e.g. AgentCash) to settle the 0.05 USDC payment.
// With plain fetch this throws IntelPaymentRequiredError carrying the 402 requirements.
const resp = await fetchIntelTrust('JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4', {
  fetchImpl: x402Fetch,
});
// resp.trust = the renormalized trust model; resp.twzrd_receipt = the signed receipt (V7 today)

Free Preflight Check (Before Paying)

import { intelPreflight } from '@wzrd_sol/sdk';

// Caller-supplied unit price only. Leftover unlabeled 0.05 is not a unit price.
const pf = await intelPreflight({
  seller_wallet: 'JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4',
  price_usdc: 0.25,
  agent_intent: 'swap_quote',
});
// pf.readiness_card: { decision: 'allow'|'warn'|'block', trust_score, can_spend, caveats[], ... }

Legacy On-Chain Builders (Retired Protocol - Unmaintained)

Everything below documents exports that remain in the package only so existing imports keep compiling. The on-chain protocol they target is retired. Nothing here is maintained, tested against mainnet, or recommended for new code. New applications should use the receipt loop above.

Read On-Chain State

import { fetchMarketVault, fetchOnChainPosition, fetchTokenBalance } from '@wzrd_sol/sdk';

const vault = await fetchMarketVault(connection, 6);
console.log('Total deposited:', vault?.totalDeposited);

const pos = await fetchOnChainPosition(connection, wallet.publicKey, 6);
console.log('My deposit:', pos?.depositedAmount, 'Multiplier:', pos?.attentionMultiplierBps);

PDA Derivation

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

Deposit (legacy deposit_market)

import { Connection, Keypair, VersionedTransaction, TransactionMessage } from '@solana/web3.js';
import { createDepositMarketIx } from '@wzrd_sol/sdk';

const connection = new Connection('https://api.mainnet-beta.solana.com');
const wallet = Keypair.fromSecretKey(/* your key */);

// Build instructions for a 1 USDC deposit into market 6
const ixs = await createDepositMarketIx(connection, wallet.publicKey, 6, 1_000_000n);

const { blockhash } = await connection.getLatestBlockhash();
const message = new TransactionMessage({
  payerKey: wallet.publicKey,
  recentBlockhash: blockhash,
  instructions: ixs,
}).compileToV0Message();

const tx = new VersionedTransaction(message);
tx.sign([wallet]);
const sig = await connection.sendTransaction(tx);
console.log('Deposit tx:', sig);

Claim via Merkle Proof (legacy claim_global_v2)

import { createClaimGlobalV2Ix, fetchClaimProof } from '@wzrd_sol/sdk';

// Public proof fetch - no wallet session (SIWS) required. Any caller who knows
// the wallet address can fetch its proof and build the claim locally.
const claim = await fetchClaimProof(wallet.publicKey.toBase58());

const ixs = await createClaimGlobalV2Ix(
  connection,
  wallet.publicKey,
  claim.rootSeq,
  claim.baseYield,
  claim.attentionBonus,
  claim.proof, // hex-encoded [u8; 32] nodes
);

// Build, sign, send as above

fetchClaimProof calls the public GET /v1/claims/:pubkey/proof endpoint and throws ClaimProofNotFoundError if the wallet has no accrual recorded.

Settle a Matured Position (legacy settle_market)

import { createSettleMarketIx } from '@wzrd_sol/sdk';

const ixs = await createSettleMarketIx(connection, wallet.publicKey, 6);
// Build, sign, send as above

settle_market returns USDC from reserve and burns the position token. Claims go through the merkle proof path (claim_global / claim_global_v2).

Exports

Constants

| Export | Description | |--------|-------------| | TRUSTED_RECEIPT_PUBKEY | Current receipt-signing key (key id twzrd-receipt-ed25519-v2) | | LEGACY_RECEIPT_PUBKEYS | Retired v1 keys, accepted only for older receipts | | PROGRAM_ID | Legacy mainnet program ID (GnGz...) | | DEVNET_PROGRAM_ID | Legacy devnet program ID (GmGX...) | | TOKEN_PROGRAM_ID | SPL Token program | | TOKEN_2022_PROGRAM_ID | Token-2022 program |

PDA Derivation (legacy)

| 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] |

Instruction Builders (legacy)

| Function | On-chain instruction | |----------|---------------------| | createDepositMarketIx(conn, user, marketId, amount) | deposit_market | | createSettleMarketIx(conn, user, marketId) | settle_market | | createClaimGlobalV2Ix(conn, claimer, rootSeq, baseYield, attentionBonus, proof) | claim_global_v2 | | createInitializeMarketVaultIx(admin, marketId, ...) | initialize_market_vault |

Legacy-only builders (latest only, annotated @deprecated in source): createStakeChannelIx*, createClaimChannelRewardsIx, createMintSharesIx/createRedeemSharesIx, createSettlePredictionIx, createPublishStreamRootIx/createClaimStream*. These target instructions not present on the immutable mainnet binary. See "SDK Version Lines" above.

Account Parsers (legacy)

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

Legacy Addresses

Mint addresses referenced by the legacy builders above. Listed for completeness; none of these are part of the trust/receipt layer.

| Asset | Mint | Token Program | |-------|------|---------------| | USDC | EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v | SPL Token | | vLOFI (legacy) | E9Kt33axpCy3ve2PCY9BSrbPhcR9wdDsWQECAahzw2dS | SPL Token | | CCM (legacy) | Dxk8mAb3C7AM8JN6tAJfVuSja5yidhZM5sEKW3SRX2BM | Token-2022 |