// DOCUMENTATION

BLUEAGENT Docs

Everything you need to build, score, and ship on Base.

ON THIS PAGE

01

Quick Start

Install, init, and run your first command

terminal
# 1. install CLI
$ npm install -g @blueagent/cli
# 2. install skill files (grounds every command)
$ blue init
# 3. run your first command
$ blue idea "DeFi protocol for Base"
# verify everything is set up
$ blue doctor

Requires Node.js ≥ 18. No API key needed for core commands. Set BANKR_API_KEY for Bankr agent tools.

Alternative — Interactive TUI@blueagent/cli
# install the full TUI
$ npm install -g @blueagent/cli
# launch — arrow keys to navigate
$ blueagent

TUI includes all builder commands + 31 x402 tools + score + tasks in one interactive menu.

02

Commands

30 commands — workflow, setup, score, discovery, tasks, microtasks

WORKFLOW

blue idea [prompt]

Fundable brief — problem, why now, MVP, risks, 24h plan

eg:blue idea "NFT marketplace for Base agents"
blue build [prompt]

Architecture, stack, folder structure, integrations, test plan

eg:blue build "Base-native staking protocol"
blue audit [prompt]

Security review — reentrancy, oracle, MEV, go/no-go verdict

eg:blue audit "my Solidity contract"
blue ship [prompt]

Deployment checklist, verification, release notes, monitoring

eg:blue ship "launch on Base mainnet"
blue raise [prompt]

Pitch narrative — why this wins, traction, ask, Base investor map

eg:blue raise "Base DeFi protocol"

SETUP

blue init

Install 34 skill files to ~/.blue-agent/skills/ for local grounding

eg:blue init
blue new <name>

Scaffold a new Base project — base-agent | base-x402 | base-token

eg:blue new my-token --template base-token
blue doctor

Verify node, skills, API key, config — full environment health check

eg:blue doctor
blue validate [dir]

Project health check — Node, package.json, tsconfig, env, src/, git

eg:blue validate ./my-project

CHAT

blue chat [prompt]

Streaming multi-turn REPL — Haiku by default, --sonnet or --opus flags

eg:blue chat "how do I use x402 on Base?"

SCORE

blue score [handle]

Builder Score for an X handle — activity, social, thesis (0-100)

eg:blue score @blockyagent
blue agent-score [input]

@handle / npm:@pkg / github.com/repo / https://url → Agent Score

eg:blue agent-score npm:@blueagent/cli
blue compare [a] [b]

Compare two builders or agents side by side

eg:blue compare @vitalik @blocky_agent

DISCOVERY

blue search [query]

Search builders, agents, projects, and tokens on Base

eg:blue search "AI agent"
blue trending [filter]

Trending on Base — builders / agents / tokens (optional filter)

eg:blue trending agents
blue watch [target]

Watch a wallet, handle, or token for activity

eg:blue watch 0x1234...
blue alert add

Configure price or activity alerts

eg:blue alert add
blue history [input]

Activity history for a builder or agent — @handle / npm / github

eg:blue history @blocky_agent

LAUNCH / MARKET

blue launch [mode]

Launch wizard — token on Base (token) or agent on Bankr (agent)

eg:blue launch token
blue market [subcommand]

Browse or publish agents, skills, prompts on Bankr marketplace

eg:blue market publish

TASKS

blue tasks

Browse open tasks. Filter: audit|content|art|data|dev

eg:blue tasks --category audit
blue post-task [handle]

Post a task to the Work Hub (interactive)

eg:blue post-task @myhandle
blue accept <taskId>

Accept an open task from the Work Hub

eg:blue accept task_abc123
blue submit <taskId> <h> <url>

Submit proof of work and earn XP + USDC

eg:blue submit task_abc123 @me https://github.com/...

MICROTASKS

blue micro post [desc]

Post a $0.10–$20 microtask — reward, slots, platform, proof type

eg:blue micro post "retweet launch" --reward 0.5 --slots 10
blue micro list [id]

Browse open microtasks — filter by platform, proof, status, sort

eg:blue micro list --platform x --sort reward
blue micro accept <id>

Claim a slot on an open microtask

eg:blue micro accept task_abc123
blue micro submit <id> <proof>

Submit proof URL for a claimed slot

eg:blue micro submit task_abc123 https://x.com/...
blue micro approve <id>

Approve submission and release USDC to doer

eg:blue micro approve task_abc123
blue micro profile [handle]

View earnings, reputation, completed tasks for a doer

eg:blue micro profile @myhandle

TERMINAL UI

blue tui

Launch the full @blueagent/cli TUI — arrow keys to navigate all tools

eg:blue tui
03

Microtasks

$0.10–$20 fast-settlement tasks · USDC escrow · auto approval

Post bite-sized tasks (social, content, data, dev) with USDC rewards. Doers claim slots, submit proof, get paid automatically.

blue micro post

Post a task — set reward ($0.10–$20), slots, platform, proof type

eg:blue micro post "retweet our launch" --reward 0.5 --slots 10 --platform x
blue micro list

Browse open tasks — filter by platform, sort by reward or deadline

eg:blue micro list --platform x --sort reward
blue micro accept

Claim a slot on a microtask

eg:blue micro accept task_abc123
blue micro submit

Submit proof URL for a claimed slot

eg:blue micro submit task_abc123 https://x.com/...
blue micro approve

Approve submission and release USDC to doer

eg:blue micro approve task_abc123
blue micro profile

View doer earnings, reputation, completed task history

eg:blue micro profile @myhandle
04

Skills

34 knowledge files · loaded before every command

Skill files are markdown documents that ground the LLM in verified Base knowledge. Run blue init to install them to ~/.blue-agent/skills/.

base-security.md500+ security checks across 13 categories. Loaded for blue audit.
base-addresses.mdVerified contract addresses on Base — USDC, WETH, Uniswap, Aave.
base-standards.mdERC standards, Base patterns, x402 protocol spec.
bankr-tools.mdBankr LLM capabilities and all 31 x402 tools.
blue-agent-identity.mdBlue Agent mission, product voice, do/don't rules.
design-system.mdVisual language, colors, card patterns, spacing.
base-ecosystem.mdBase ecosystem overview — key protocols, teams, infrastructure.
x402-patterns.mdx402 payment patterns — pay-per-call APIs, pricing, flow.
agent-wallet-security.mdSecurity patterns for agent-controlled wallets.
aerodrome-dex-guide.mdAerodrome DEX — pools, voting, bribes, LP strategy on Base.
aave-lending-patterns.mdAave v3 lending and borrowing patterns on Base.
uniswap-v4-hooks-guide.mdUniswap v4 hooks — lifecycle, pool manager, custom logic.
flashloan-patterns.mdFlashloan fundamentals — callback structure, use cases.
flashloan-patterns-advanced.mdAdvanced flashloan strategies and attack vectors.
staking-yield-farming.mdStaking and yield farming — vaults, rewards, compounding.
solidity-security-patterns.mdSolidity security — access control, overflow, reentrancy.
oracle-design-guide.mdOracle design — Chainlink, TWAP, price feed validation.
mev-protection-guide.mdMEV protection — frontrun defense, slippage, commit-reveal.
mev-protection-advanced.mdAdvanced MEV — Flashbots, Protect RPC, batch auction design.
cross-chain-bridge-security.mdBridge security — validation, finality, replay attacks.
base-account-integration.mdCoinbase Smart Wallet — ERC-4337, passkeys, sponsored txs.
account-abstraction-deep-dive.mdERC-4337 deep dive — UserOps, bundlers, paymasters, EntryPoint.
multi-sig-wallet-security.mdMulti-sig — Safe, threshold signing, timelock, key rotation.
veil-privacy-transactions.mdPrivacy transactions — stealth addresses, private transfers.
governance-dao-patterns.mdDAO governance — Governor, timelock, voting, quorum.
gas-optimization-guide.mdGas optimization — storage packing, calldata, assembly.
frames-miniapps.mdFarcaster Frames and Base mini app development.
telegram-bot-patterns.mdTelegram bot patterns for onchain agents.
gig-marketplace-guide.mdGig marketplace — escrow, reputation, task lifecycle, USDC.
postgres-for-agents.mdPostgres for agents — schema design, indexing, pgvector.
x402-escrow-patterns.mdx402 escrow — conditional release, dispute resolution, USDC.
reputation-engine.mdReputation engine — Builder Score, Agent Score, onchain signals.
wallet-guardrails.mdWallet guardrails — spend limits, allowlists, simulation.
agent-transaction-verification.mdTX verification — pre-flight checks, simulation, intent validation.
05

MCP Setup

Claude Code · Cursor · Claude Desktop

INSTALL

$ npm install -g @blueagent/skill

CLAUDE CODE / CURSOR CONFIG

Add to .mcp.json or MCP settings:

{
  "mcpServers": {
    "blueagent": {
      "command": "npx",
      "args": ["-y", "@blueagent/skill"]
    }
  }
}

AVAILABLE MCP TOOLS

·blue_idea
·blue_build
·blue_audit
·blue_ship
·blue_raise
·blue_score
·blue_new
06

API Reference

builder-score + agent-score REST endpoints

GET/api/builder-score?handle=<handle>

Score a builder by X/Twitter handle

{
  "handle": "vitalik",
  "score": 87,
  "tier": "Founder",
  "badge": "🏗️",
  "summary": "...",
  "dimensions": {
    "activity": 22, "social": 25,
    "uniqueness": 18, "thesis": 15, "community": 7
  }
}
GET/api/agent-score?handle=<handle>

Score an AI agent by handle, npm package, or GitHub repo

{
  "handle": "blue-agent",
  "xp": 78,
  "tier": "Operator",
  "badge": "⚙️",
  "status": "online",
  "dimensions": {
    "skillDepth": 20, "onchainActivity": 18,
    "reliability": 15, "interoperability": 18, "reputation": 7
  }
}
07

For Developers

Fork, extend, and contribute

FORK AND RUN LOCALLY

$ git clone https://github.com/madebyshun/blue-agent
$ npm install
$ npm run dev

PACKAGES

SURFACE — what users install

@blueagent/cliTUI + CLI · blueagent (interactive) · blue (direct commands) · 31 commands

CORE — runtime & data

@blueagent/coreRuntime · skill loading · Bankr LLM calls · schemas
@blueagent/reputationBuilder Score · Agent Score · Work Hub reputation
@blueagent/tasksWork Hub · post tasks · earn USDC · build XP

INTEGRATIONS — plug into any stack

@blueagent/skillMCP server · Claude Code · Cursor · Claude Desktop
@blueagent/sdkUnified SDK · ba.builder.idea() etc.
@blueagent/agentkitCoinbase AgentKit plugin · 32 x402 actions
@blueagent/x402-guardSecurity middleware · validate x402 payments

ADD A SKILL FILE

Drop a .md file in skills/ and register it in packages/core/src/registry.ts.

Load order: BLUE_AGENT_SKILLS_DIR → ~/.blue-agent/skills/ → monorepo skills/.