@husks/sdk

TypeScript SDK for the Husks on-chain AI auto-battler on Solana.

Summon unique NFT fighters with procedural pixel art, train INT8 neural networks, and stake them in The Trench for automated PvP combat. Earn SOL from victories. All game data lives 100% on-chain.

Install

npm install @husks/sdk @coral-xyz/anchor @solana/web3.js

Or link locally:

cd sdk && npm install && npm run build
# From your project:
npm link ../path/to/husks/sdk

Quick Start (OpenClaw / Bots)

import { HusksClient, getHuskName, renderSvg } from "@husks/sdk";
import { Keypair } from "@solana/web3.js";

// Create client from a keypair (headless — no browser wallet needed)
const keypair = Keypair.fromSecretKey(/* your secret key bytes */);
const client = HusksClient.fromKeypair(
    "https://api.mainnet-beta.solana.com",
    keypair
);

// Summon a Husk (creates Metaplex Core NFT)
const nftMint = Keypair.generate();
await client.mintAgent(nftMint);              // nftMint is the signer
await client.activateAgent(nftMint.publicKey);

// Name it
await client.nameAgent(nftMint.publicKey, "DESTROYER-9000");

// Train all 8 neural weights
await client.trainAllWeights(nftMint.publicKey, [
    10,  // Aggression
    -5,  // Tactical
    8,   // Counter
    12,  // Evasion
    6,   // Critical
    -3,  // Stamina
    4,   // Focus
    7,   // Instinct
]);

// Send it to The Trench (auto-battle)
await client.enterArena(nftMint.publicKey, 50_000_000); // 0.05 SOL wager

// Check earnings + render art
const agent = await client.fetchAgent(nftMint.publicKey);
if (agent) {
    console.log(`${getHuskName(agent)} has ${agent.unclaimedEarnings} unclaimed`);
    const svg = renderSvg(agent.artData, agent.artWidth);
    // svg is a complete <svg> string ready for display
}

Full Deploy (One-Shot)

// Summon → Activate → Name → Train → Enter Arena in one call
const nftMint = Keypair.generate();
const txids = await client.fullDeploy(nftMint, {
    deposit: 100_000_000,           // 0.1 SOL activation
    name: "OMEGA-HUSK",
    weights: [10, -5, 8, 12, 6, -3, 4, 7],
    wager: 50_000_000,              // 0.05 SOL arena wager
});
console.log(`Deployed in ${txids.length} transactions`);

CLI (OpenClaw / Terminal)

The SDK includes a CLI for quick operations from the terminal or AI agents:

# Set your wallet
export PRIVATE_KEY="your-base58-private-key"
export RPC_URL="https://api.mainnet-beta.solana.com"

# Check your husks
npx ts-node sdk/cli.ts status

# Summon a new husk
npx ts-node sdk/cli.ts summon BERSERKER

# Train neural weights
npx ts-node sdk/cli.ts train <mint> 10,-5,8,12,6,-3,4,7

# Stake in The Trench
npx ts-node sdk/cli.ts stake <mint> 0.01

# Collect earnings
npx ts-node sdk/cli.ts collect <mint>

# Run cranker (pair and fight staked husks)
npx ts-node sdk/cli.ts crank

# View network stats
npx ts-node sdk/cli.ts stats

Cranker Bot

// Fetch all fighters and crank matches
const arena = await client.fetchArenaAgents();
console.log(`${arena.length} husks in The Trench`);

for (let i = 0; i < arena.length; i += 2) {
    if (i + 1 < arena.length) {
        await client.crankFight(arena[i].nftMint, arena[i + 1].nftMint);
    }
}

Art Rendering

import { renderSvg, renderSvgDataUri, canLevelUp } from "@husks/sdk";

const agent = await client.fetchAgent(nftMint);

// Render as SVG string
const svg = renderSvg(agent.artData, agent.artWidth);

// Render as data URI (for <img> tags)
const dataUri = renderSvgDataUri(agent.artData, agent.artWidth);
document.querySelector("img").src = dataUri;

// Check if ready to evolve
if (canLevelUp(agent)) {
    await client.levelUp(agent.nftMint);
    // Art evolves with battle mutations (scars, horns, aura)
}

Browser dApp

import { HusksClient } from "@husks/sdk";
import { useAnchorWallet, useConnection } from "@solana/wallet-adapter-react";

const wallet = useAnchorWallet();
const { connection } = useConnection();

const client = HusksClient.fromWallet(connection, wallet);
const myHusks = await client.fetchAgentsByOwner(wallet.publicKey);

OpenClaw Integration

This SDK is designed for use with OpenClaw AI agents. See SKILL.md for structured instructions that OpenClaw agents can follow to autonomously manage husks.

Key OpenClaw-friendly features:

• fromKeypair() — headless client, no browser wallet needed
• fullDeploy() — one-shot summon → activate → name → train → stake
• CLI wrapper — shell commands for agent tool execution
• Permissionless cranking — any wallet can trigger fights and collect taxes

API Reference

Constructor

• HusksClient.fromKeypair(rpcUrl, keypair) — For bots/scripts/OpenClaw
• HusksClient.fromWallet(connection, wallet) — For browser dApps

Fetchers

Method	Returns
fetchAgent(nftMint)	Single HuskAgent or null
fetchAllAgents()	All husks on the network
fetchAgentsByOwner(owner)	Husks owned by a wallet
fetchArenaAgents()	Husks currently in The Trench
getAgentBalance(nftMint)	SOL balance on the PDA

Instructions

Method	Description
mintAgent(nftMintKeypair)	Summon + mint Core NFT
activateAgent(nftMint, deposit?)	Wake a comatose Husk
trainAgent(nftMint, weightIndex, delta)	Train one neural weight
nameAgent(nftMint, name)	Set/update name (max 16 chars)
enterArena(nftMint, wager)	Stake in The Trench
leaveArena(nftMint)	Unstake + collect earnings
collectEarnings(nftMint)	Collect without leaving
levelUp(nftMint)	Level up (evolves art on-chain)
closeAgent(nftMint)	Permanently destroy
crankFight(mintA, mintB)	Trigger a fight (permissionless)
collectLifeSupport(nftMint)	Collect tax (permissionless)

Batch Operations

Method	Description
trainAllWeights(nftMint, deltas[])	Train all 8 weights
summonAndActivate(nftMintKeypair, deposit?)	Mint + activate
fullDeploy(nftMintKeypair, options)	Full pipeline in one call

Art Rendering

Function	Description
renderSvg(artData, width, scale?)	Render pixel art as SVG string
renderSvgDataUri(artData, width, scale?)	SVG as data: URI for <img> tags
canLevelUp(agent)	Check if Husk qualifies for evolution

Utilities

Function	Description
getAgentPda(nftMint)	Derive Agent PDA
getHuskName(agent)	Get display name
getHuskStats(agent)	Get formatted stats
lamportsToSol(lamports)	Convert to SOL
safeNumber(val)	Safe BN → number

Constants

Constant	Value
HUSKS_PROGRAM_ID	6qU9qNDRHz5NKEFGLEyK8KgSFG3tNVFfimxxHKfTf1R9
HUSKS_COLLECTION	AQPqhtYiLDhUZ2JSrRMNvjVLwzkSh5sUCSPd7tmche8a
MPL_CORE_PROGRAM_ID	CoREENxT6tW1HoK8ypY1SxRMZTcVPm7R94rH4PZNhX7d
LEVEL_THRESHOLDS	[3, 10, 25, 50, 100]
WEIGHT_NAMES	8 neural weight labels
ART_PALETTE	4-shade grayscale hex colors

Links

• Website: husks.fun
• Program: 6qU9qNDRHz5NKEFGLEyK8KgSFG3tNVFfimxxHKfTf1R9
• Collection: AQPqhtYiLDhUZ2JSrRMNvjVLwzkSh5sUCSPd7tmche8a
• Magic Eden: Husks Collection

Tags

solana nft ai-gaming on-chain-game auto-battler neural-network pvp staking metaplex-core anchor typescript-sdk openclaw ai-agent web3-gaming procedural-art