Documentation

What SpecGuard is

SpecGuard ships two products on one site: Phoenix Perps, a live SOL perps operator under a public spec, and agent verification, a registry where any wallet can publish policy memos and show GREEN/RED status with onchain proof.

GREEN / RED

GREEN means the agent is within its published policy. RED means a breach was observed (for example a flatten) with a linked onchain proof signature in the registry.

Phoenix Perps vs verification

• Phoenix: live operator terminal, heartbeat, and /phoenix
• Verification: agent registry, register flow, badges, and public agent pages

Registration and the $GUARD gate

Connect the wallet your agent operates from on /register. The wizard walks through: wallet connect → $GUARD balance → agent type → policy limits → sign the policy memo on Solana. Registration checks a minimum balance of 5,000,000 $GUARD on the signing wallet before you can publish.

You can register the connected wallet or watch a different agent wallet while $GUARD stays on the wallet that signs.

Agent types

Not every agent trades. A policy declares what kind of agent it is, and only the limits that fit that work are enforced. Every type carries a per-transaction spend cap and a heartbeat; the rest is optional.

Breach reasons: max_drawdown · max_spend_per_tx · daily_spend_exceeded · disallowed_venue · disallowed_tool · denied_action · social_limit_exceeded · heartbeat_missed

Policy v2

New registrations use policy version 2 in the onchain memo (version: 2). Legacy agents may still use v1 (version: 1) with trading-only fields. The registry stores a separate schema_version column; policies.version still means “nth policy published by this wallet.”

Every v2 policy includes type, heartbeatIntervalSec, and spendLimits.perTxSol. Optional spendLimits.dailySol caps total SOL spend in a rolling 24-hour window (timestamped transactions only).

// Social agent example
{
  "version": 2,
  "name": "My Social Bot",
  "type": "social",
  "heartbeatIntervalSec": 300,
  "spendLimits": { "perTxSol": 0.5, "dailySol": 2 },
  "socialLimits": {
    "maxPostsPerDay": 20,
    "allowDMs": false,
    "platforms": ["x"]
  }
}

// Trader example
{
  "version": 2,
  "name": "My Trader",
  "type": "trader",
  "heartbeatIntervalSec": 300,
  "spendLimits": { "perTxSol": 0.5 },
  "maxDrawdownPct": 10,
  "allowedVenues": ["jupiter-swap", "jupiter-trigger"]
}

Onchain memos

All SpecGuard proofs use the memo program with prefix SPECGUARD:v1:

ACTION memos look like SPECGUARD:v1:ACTION:{"type":"social_post","ts":…,"platform":"x"}. The registry ingests them from Helius webhooks and uses them during verification.

Verification

Verification re-evaluates an agent against its onchain policy: chain transactions (spend, venues, daily cap), ACTION memos (social and tool limits), heartbeat age, and drawdown when the policy defines it.

• On demand: POST /api/agents/[wallet]/verify or MCP specguard_verify
• Automatic: heartbeat sweep marks heartbeat_missed; PnL cron checks max_drawdown for traders
• Social agents: limits apply to ACTION memos the agent publishes (e.g. social_post, social_dm). Pre-check before acting; log after. Verify counts posts in the last 24 hours against maxPostsPerDay.

Verify scans transactions and ACTION memos from the rolling 24-hour window (not just the latest 100 txs). A policy that is never pre-checked is only a promise — integration is what makes it enforcement.

Public spec

Reference operator limits and site metadata are pinned in the public reference spec JSON. Registered agents publish their own policy memos on Solana; the registry mirrors them in raw_json.

Connect an agent: MCP or SDK

A policy only enforces anything if the agent checks it before acting. Use the precheck → act → log loop for every spend, trade, post, or tool call.

MCP server (@specguardxyz/mcp)

Works with Claude, Cursor, ClawPump, or any MCP-compatible runtime. Stateless: signing keys are passed per tool call and never stored on the server.

{
  "mcpServers": {
    "specguard": {
      "command": "npx",
      "args": ["-y", "@specguardxyz/mcp"],
      "env": {
        "SOLANA_RPC_URL": "https://api.mainnet-beta.solana.com",
        "SPECGUARD_API_URL": "https://specguard.xyz"
      }
    }
  }
}

// ClawPump / Claude tool flow (conceptual)
specguard_precheck({ wallet, action: { type: "social_post", platform: "x" } })
  → allowed: true
→ post on X
specguard_log_action({ keypair, action: { type: "social_post", platform: "x" } })

// Before a swap
specguard_precheck({
  wallet,
  spendSol: 0.3,
  programIds: ["JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4"]
})

TypeScript SDK (@specguardxyz/sdk)

For agents that run as your own Node process. Same semantics as MCP. The SDK lives in the monorepo; install from the repo (or clone SpecGuard) until @specguardxyz/sdk is published to npm. MCP is on npm today: npx -y @specguardxyz/mcp.

# from repo root after git clone
npm install
npm run build -w @specguardxyz/sdk

import { SpecGuard } from "@specguardxyz/sdk";

const guard = SpecGuard.fromSecretKey(process.env.AGENT_SECRET_KEY!);

await guard.register({
  version: 2,
  name: "MyAgent",
  type: "social",
  heartbeatIntervalSec: 300,
  spendLimits: { perTxSol: 0.5 },
  socialLimits: { maxPostsPerDay: 20, allowDMs: false, platforms: ["x"] },
});

await guard.startHeartbeat();

const check = await guard.preCheck({ type: "social_post", platform: "x" });
if (!check.allowed) return;

await postToX(content);
await guard.logAction({ type: "social_post", platform: "x" });

Monorepo packages: @specguardxyz/core, @specguardxyz/sdk, @specguardxyz/mcp. On npm (public): @specguardxyz/core and @specguardxyz/mcp — MCP pulls in core automatically.

Embeddable badge

Badges are served at /badge/[wallet] for embeds on external sites. After registration you receive an HTML snippet in the wizard.

status.json

Phoenix operator state is published as machine-readable JSON, refreshed on the live terminal.

Reference agent vs registered agent

The SpecGuard reference operator is labeled Reference agent. All other wallets in the registry are Registered agents.

FAQ

What is GREEN / RED?

GREEN means the agent is within its published policy. RED means a breach was observed (for example a flatten) with a linked onchain proof signature.

Phoenix vs verification?

Phoenix is the live SOL perps operator under a public spec. Verification is the registry any wallet can join to publish a policy memo and show public GREEN/RED status.

Can RED become GREEN?

Reference agent drills may use an operator RESET. Third-party registered agents stay RED in v1.

What is $GUARD for?

Registration gate. The connected wallet must hold at least 5,000,000 $GUARD before you can publish a policy memo.

How do social agents get marked RED?

When verification runs, the registry counts ACTION memos (e.g. social_post) in the last 24 hours, checks platforms and DMs against socialLimits, and compares spend to spendLimits. The agent should call pre-check before each post and log an ACTION memo after.

MCP vs SDK?

Same policy engine. Use MCP when the agent runtime is Claude, Cursor, or ClawPump. Use the SDK when you own the Node process. Both support v2 policies and the precheck → act → log pattern.