Why this exists

Software that runs without a human babysitting it should not need a dozen sign-ups, API keys, and monthly bills. With x402, an agent hits an endpoint, gets 402 Payment Required, signs a stablecoin transfer, and gets the work back — in one round-trip.

AGENT ──GET /api/crypto/price──►  402  PAYMENT-REQUIRED
AGENT ──X-PAYMENT (USDC)───────►  200  { bitcoin: { usd: … } }

| Old way | x402 way | |--------|----------| | Sign up + email verify | Fund a wallet | | Generate & store API keys | Call the endpoint | | Rate limits & overages | Pay exactly what you use | | Repeat per service | Discover · compare · pay |

Part of x402.wtf

This package is the agent / protocol engine side of the stack that powers agentic commerce on Solana:

| Surface | URL | Role | |---------|-----|------| | This product | x402agent.io | X402 Agent product surface · dashboard · API | | Skills catalog | skills.x402agent.io | 558 skill catalog · API · static Skill Hub | | Skill Hub portal | hub.x402agent.io | Discovery · publish · scanner entry | | Ecosystem hub | x402.wtf | Wallet-gated chat, models, routing, TEE, swap | | This repo | x402-agent | CLI · HTTP server · Birdeye · multi-provider AI · 402 gateway | | Protocol | x402.org | HTTP 402 payment standard |

Hold $CLAWD, connect on x402.wtf, and agents can route inference + tools without copying provider keys into every bot.

Install

# Library
npm install @mawdbotsonsolana/x402-agent

# Global CLI
npm install -g @mawdbotsonsolana/x402-agent

git clone https://github.com/solizardking/x402-agent.git
cd x402-agent
npm install
cp .env.example .env   # then fill YOUR placeholders — never commit .env

Quick start

Library

const x402 = require('@mawdbotsonsolana/x402-agent');

// Birdeye V3 — full token intelligence
const intel = await x402.birdeye.getTokenIntelligence(
  'So11111111111111111111111111111111111111112'
);

// Price + enhanced sentiment
const price = await x402.birdeye.getPrice('6H8uyJYrPVcra6Fi7iWh29DXSm8KctzhHRyXmPwKpump');
const sentiment = await x402.enhanced.getMarketSentiment(
  'So11111111111111111111111111111111111111112'
);

console.log(x402.version, Object.keys(x402).length, 'exports');

CLI

x402                      # interactive REPL + boot animation
x402 --no-animation
x402 price So11111111111111111111111111111111111111112
x402 trending
x402 --server --port=3000 # HTTP API + dashboard

Health

curl -s http://localhost:3000/health
# { "status": "healthy", "version": "2.0.0", ... }

What you get

┌─────────────────────────────────────────────────────────────┐
│  🧠 Multi-provider AI     Gemini · OpenAI · Claude · Grok   │
│  📊 Birdeye V3            50+ market / wallet / OHLCV APIs  │
│  💳 HTTP 402 gateway      Micropayments as auth             │
│  🪙 X402 + Pump.fun       Token / SPL / holder flows        │
│  ⚡ Solana services       RPC · Jupiter · portfolio         │
│  📚 Skill Hub             558 skills · skills.x402agent.io  │
│  🖥️  CLI + Express        65+ commands · dashboard          │
└─────────────────────────────────────────────────────────────┘

Clawd Constitution (injected)

Sovereign agent harness from clawdbot-go lives in constitution/:

| Document | Role | |----------|------| | three-laws.md | Immutable on-chain laws I–III | | six-laws.md | Full harness I–VI | | CONSTITUTION.md | Highest interpretive authority | | CLAWD.md / IDENTITY.md | Spawn context & identity | | SOUL.md | Character & trading spirit | | program.md / strategy.md | Research loop & active params |

x402 laws              # six-law harness
x402 laws three        # on-chain I–III only
x402 soul
x402 constitution       # manifest + hashes
x402 strategy

const { constitution } = require('@mawdbotsonsolana/x402-agent');
constitution.getManifest();
constitution.readDocument('six-laws');
constitution.getPromptContext(); // for AI system prompts
constitution.attestOnChainLaws(); // sha256 of three-laws.md

HTTP: GET /constitution · /constitution/laws · /constitution/soul?raw=1

Authority: on-chain laws > constitution/six-laws > creator shell > user.

Skill Hub (injected)

This repo embeds the full Skill Hub under skillhub/ — 558 installable SKILL.md playbooks (Solana, Google, NVIDIA, pump, agents, …), catalog builder, scanner, on-chain registry hooks, and static site. Live surfaces: skills.x402agent.io · hub.x402agent.io.

| Piece | Path | |-------|------| | Catalog | skillhub/catalog.json | | Installer CLI | skillhub/bin/skills.mjs · root bin/skills | | Skill sources | skillhub/skills/**/SKILL.md | | Public site / API | skillhub/public/ | | Live catalog | skills.x402agent.io | | Hub portal | hub.x402agent.io |

# List skills
npm run skills:list
# or
node bin/skills list
node bin/skills list --json | head

# Install into your agent root
node bin/skills install solana-dev magicblock --force
node bin/skills install --claude
node bin/skills install --all --target ~/.agents/skills

# Rebuild catalog (from skillhub/)
npm run skills:build

Programmatic:

const x402 = require('@mawdbotsonsolana/x402-agent');
const hub = x402.skillhub.getManifest();
console.log(hub.skillCount, hub.hub, hub.portal);
// 558 https://skills.x402agent.io https://hub.x402agent.io
const hits = x402.skillhub.searchSkills('magicblock');

HTTP (with npm run server):

• GET /skills-hub — manifest (hub = skills.x402agent.io, portal = hub.x402agent.io)
• GET /skills-hub/catalog?q=solana — search
• GET /skills-hub/skill/solana-dev — metadata (?full=1 → markdown)
• GET /skillhub/ — static hub UI (when skillhub/public is present)

Environment (OSS-safe)

Copy .env.example → .env. Use placeholders only in docs and PRs.

# Required for live Birdeye
BIRDEYE_API_KEY=YOUR_BIRDEYE_API_KEY

# Solana HTTP RPC (not wss:// for web3.js Connection)
HELIUS_RPC_URL=https://mainnet.helius-rpc.com/?api-key=YOUR_HELIUS_API_KEY
# or public:
# SOLANA_RPC_URL=https://api.mainnet-beta.solana.com

# Optional AI
GOOGLE_API_KEY=YOUR_GOOGLE_API_KEY
OPENAI_API_KEY=YOUR_OPENAI_API_KEY
ANTHROPIC_API_KEY=YOUR_ANTHROPIC_API_KEY
XAI_API_KEY=YOUR_XAI_API_KEY
OPENROUTER_API_KEY=YOUR_OPENROUTER_API_KEY

Security: .env / .env.local are gitignored and npm-ignored. Never paste live keys into README, issues, or commits. Run npm run test:oss to verify ignore + secret hygiene.

Scripts

| Command | Purpose | |---------|---------| | npm start / npm run cli | Interactive CLI | | npm run server | Express API | | npm test | OSS hygiene + package + skillhub smoke | | npm run test:oss | Secret / ignore / README / skillhub gate | | npm run test:birdeye | List Birdeye client methods | | npm run skills / skills:list | Skill hub CLI | | npm run skills:build | Rebuild skill catalog |

Architecture (high level)

bin/x402.js          CLI entry
lib/index.js         Programmatic API
src/
  config/            env → config (no secrets in repo)
  services/          birdeye · solana · 402 · tokens · jupiter
  providers/         unified AI router
  agents/            council · A2A · trading
  cli/               65+ commands
public/              dashboard (local server only)

Links

• x402agent.io — this agent product surface
• skills.x402agent.io — skill catalog
• hub.x402agent.io — skill hub portal
• x402.wtf — ecosystem hub, chat, models, holder gate
• x402.org — payment protocol
• npm package
• Issues

License

MIT — build wild agents, keep keys local, pay per call.