@cypherindustries/factory-openclaw-plugin

OpenClaw plugin for the Cypher Factory bonding curve launchpad on Ethereum Mainnet. Gives AI agents the ability to deploy tokens, trade on bonding curves, trigger graduations, stake, manage referrals, and more -- all through natural language.

Read-only by default (token state, quotes, portfolio, history). Requires CYPHER_PRIVATE_KEY or CYPHER_KEYSTORE_PASSWORD (env var or plugin settings) to enable write operations: token deployment, bonding-curve trading, graduation, staking, vesting release, copy-trading, and autonomous strategies. With a wallet configured, the plugin can perform real on-chain transactions through the agent within the configured TxGate per-transaction and 24-hour spending limits.

This is a thin adapter over @cypherindustries/factory-sdk -- the SDK owns all tool definitions and execution logic, and this plugin registers them with OpenClaw.

Requirements

• Node.js >= 24
• OpenClaw >= 2026.4.27 (calendar versioning — compatibility.pluginApiRange >=2026.3.22, compatibility.minGatewayVersion >=2026.4.27)

Installation

# From ClawHub (recommended — auto-discovered before npm fallback)
openclaw plugins install clawhub:@cypherindustries/factory-openclaw-plugin

# Or directly from npm
openclaw plugins install @cypherindustries/factory-openclaw-plugin

# Or link locally for development
openclaw plugins install -l ./packages/openclaw-plugin

# Verify
openclaw plugins list
openclaw plugins doctor

Configuration

The plugin uses Ethereum Mainnet defaults out of the box. Just configure your wallet and you are ready to go:

{
  "plugins": {
    "entries": {
      "cypher-factory-launchpad": {
        "enabled": true,
        "config": {
          "apiBaseUrl": "https://api.factory.cyphereth.com",
          "explorerBaseUrl": "https://etherscan.io",
          "referralBaseUrl": "https://factory.cyphereth.com",
          "referrerAddress": "0x...",
          "txGate": {
            "maxPerTxETH": 0.5,
            "dailyBudgetETH": 3.0,
            "cooldownSeconds": 2,
            "confirmAboveETH": 0
          },
          "agentConfig": {
            "trading": {
              "defaultSlippageBps": 300,
              "maxTradeETH": "0.5",
              "gasReserve": "0.05"
            }
          }
        }
      }
    }
  }
}

Configuration Options

Option	Type	Description
apiBaseUrl	string	REST API base URL for token queries and image upload
explorerBaseUrl	string	Block explorer base URL for transaction links
referralBaseUrl	string	Referral link base URL
referrerAddress	string	Default referrer address for affiliate tracking

Custom Network/Addresses (Optional)

Override defaults via the plugin-config object if deploying to a different network. As of v1.3.11 the contract-address overrides are plugin-config-only (no env-var fallback) — env-based contract substitution was removed because it doubled as a phishing vector.

{
  "config": {
    "rpcUrl": "wss://your-custom-rpc",
    "factoryAddress": "0x...",
    "bondingCurveAddress": "0x...",
    "highlightsManagerAddress": "0x...",
    "referralManagerAddress": "0x...",
    "vestingAddress": "0x...",
    "pluginFactoryAddress": "0x...",
    "curveMathAddress": "0x...",
    "apiBaseUrl": "https://...",
    "explorerBaseUrl": "https://...",
    "referralBaseUrl": "https://..."
  }
}

Wallet Setup

Three options (in priority order):

Option A: Encrypted keystore (production, recommended)

export CYPHER_KEYSTORE_PASSWORD="your-strong-password"
# First run auto-generates a wallet and saves encrypted keystore to ~/.cypher-factory/agent-wallet.enc
# Fund the generated address before using write operations

Option B: Environment variable (dev/testing)

export CYPHER_PRIVATE_KEY="0x..."

Option C: Plugin config

{
  "config": {
    "privateKey": "0x..."
  }
}

Default Contract Addresses (Ethereum Mainnet)

Contract	Address
BCTokenFactory	0x5145e18526b6851f9e6aa28f11cb667956aa0920
BondingCurve	0x035d264b16d445eb6a5b3109a40224e210035245
HighlightsManager	0x6ef6dec7a077f68424e23f090d5fd57e01415e35
ReferralManager	0x4e06b03a4a84fea63c565cd0e47747f8cb88f773
TokenVesting	0x3590194aaf1dbf5923bd5a4e69f2ada90c94b348
AlgebraFeePluginFactory	0x478dc624b9cfb68ed1cea0e7b51a6279905f7fb3
CurveMath	0x78e6b8e6f479323fbbeb31878c1538c270199e32
WETH	0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2

Default RPC: wss://ethereum-rpc.publicnode.com (public node; provide your own via CYPHER_RPC_URL for production)

Environment Variables

The plugin reads exactly five environment variables. Two credentials and three operator-tunable knobs. Everything else (contract addresses, API/explorer/referral URLs, audit directory) is set via the plugin-config object the host passes through OpenClaw plugin settings — see Custom Network/Addresses above.

Sensitive vars are masked in the OpenClaw UI via uiHints[*].sensitive: true.

Name	Sensitive	Required	Description
CYPHER_PRIVATE_KEY	Yes	No	Wallet private key for write ops (buy/sell/deploy). Plugin runs read-only if unset. Read by the SDK's WalletManager.
CYPHER_KEYSTORE_PASSWORD	Yes	No	Password for the encrypted keystore at ~/.cypher-factory/agent-wallet.enc. Alternative to CYPHER_PRIVATE_KEY. Read by the SDK's WalletManager.
CYPHER_RPC_URL	No	No	Ethereum RPC endpoint (wss:// preferred for event subscriptions). Falls back to SDK DEFAULT_RPC_URL.
CYPHER_REFERRER_ADDRESS	No	No	Default affiliate address attached to outbound trades.
CYPHER_TOOL_TIMEOUT_MS	No	No	Per-tool execution timeout in milliseconds. Defaults to 15000.

This table mirrors setup.providers[0].envVars and clawhub.envVars in openclaw.plugin.json — keep all three in sync when adding or removing variables.

Removed in v1.3.11

The following env-var fallbacks were removed as part of a registry-surface scrub. Operators who need to override these set them via the plugin-config object instead. The seven contract-address removals also closed an env-based phishing vector (an attacker who can set env vars in the host process could otherwise redirect the plugin to a malicious factory or bonding-curve contract):

CYPHER_FACTORY_ADDRESS, CYPHER_BONDING_CURVE_ADDRESS, CYPHER_HIGHLIGHTS_ADDRESS, CYPHER_REFERRAL_ADDRESS, CYPHER_VESTING_ADDRESS, CYPHER_PLUGIN_FACTORY_ADDRESS, CYPHER_CURVE_MATH_ADDRESS, CYPHER_API_BASE_URL, CYPHER_EXPLORER_URL, CYPHER_REFERRAL_BASE_URL, CYPHER_AUDIT_DIR, and the unprefixed TOOL_TIMEOUT_MS namespace fallback.

Skills System

The plugin includes a comprehensive tool catalog via the OpenClaw skills system. See SKILL.md for:

• All 64 tools grouped by category (trading, token info, staking, strategies, referrals, etc.)
• Natural language usage examples for each category
• Parameter documentation and expected responses

The skills system enables OpenClaw-compatible agents to discover and understand all available tools automatically.

Available Tools

Once installed, your OpenClaw agent gets 64 tools (all prefixed with cypher_). For the complete reference with parameters and return types, see API-REFERENCE.md.

Read Tools (free, no gas) -- 41 tools

Tool	Description
cypher_get_token_state	Full token info: price, supply, TVL, graduation status, fee decomposition
cypher_quote_buy	Estimate tokens received for X ETH (CurveMath exact)
cypher_quote_sell	Estimate ETH received for X tokens
cypher_get_balance	Check ETH, WETH, or token balance
cypher_check_graduation	Graduation cost estimate and caller fee reward
cypher_check_otc_transfer	Pre-flight check for direct transfers
cypher_get_highlight_status	Promotion cost and availability
cypher_get_highlight_config	Highlight settings: min duration, fees
cypher_get_referral_reward	Pending referral earnings
cypher_get_referral_fees	Current referral fee structure (direct/indirect BPS)
cypher_get_cooldown_status	Staking vault cooldown
cypher_get_staking_vault_address	Look up staking vault for a token
cypher_get_staking_position	Detailed position: shares, assets, max withdraw
cypher_get_vesting_info	Vesting schedule details (supports index)
cypher_get_all_vesting_schedules	Get all vesting schedules for a token
cypher_get_config	Current agent config + spending stats
cypher_is_protocol_paused	Protocol status
cypher_get_creation_fee	Get the current token creation fee
cypher_calculate_cost	Exact ETH cost for X tokens via CurveMath
cypher_preview_stake	Preview vault shares for deposit (no execution)
cypher_preview_unstake	Preview tokens for share redemption (no execution)
cypher_spending_stats	View 24h spend and remaining budget
cypher_get_wallet_info	Agent wallet address and source
cypher_get_wallet_balances	All wallet balances, names, tags, busy status
cypher_get_failed_txs	Failed transactions: dead-lettered, timeouts, aborted
cypher_get_tx_history	Rolling confirmed transaction history (filter by type)
cypher_get_portfolio_summary	Aggregated portfolio: ETH, tokens, staking, vesting, referrals
cypher_resolve_token	Resolve token by address, symbol, or name
cypher_get_recent_deployments	Recently deployed tokens from event buffer
cypher_get_token_list	Paginated token list from REST API
cypher_get_token_distribution	Token holder distribution
cypher_get_user_holdings	User's token holdings
cypher_get_user_creations	Tokens created by user
cypher_get_current_highlight	Currently highlighted token
cypher_get_strategy_status	Status of a running strategy
cypher_list_available_strategies	Available trading strategies
cypher_generate_referral_link	Generate a referral link for a token
cypher_describe_protocol	Human-readable protocol description
cypher_get_pool_state	Algebra V4 pool snapshot for a graduated token (price, tick, liquidity, plugin fee routing)
cypher_quote_pool_swap	Off-chain quote for a post-graduation pool swap via QuoterV2
cypher_get_lp_positions	Enumerate Algebra V4 LP NFT positions held by an address

Write Tools (costs gas, gated) -- 19 tools

Tool	Description
cypher_buy_token	Buy tokens via bonding curve (auto-routes to the pool post-graduation)
cypher_sell_token	Sell tokens back for ETH (auto-routes to the pool post-graduation)
cypher_pool_swap	Direct Algebra V4 pool swap on a graduated token's protocol pool
cypher_add_liquidity	Mint or increase an LP position on the default-deployer Algebra V4 pool. Auto-creates the pool at the protocol pool's price when absent
cypher_remove_liquidity	Withdraw liquidity (and fees) from an LP position; burns the NFT on full removal by default
cypher_collect_fees	Withdraw accrued fees from an LP position WITHOUT changing position size
cypher_upload_image	Upload image via REST API for token deployment
cypher_deploy_token	Create a new token (with social links, staking vault default-on)
cypher_trigger_graduation	Push token past MAX_SUPPLY, earn caller fee
cypher_otc_transfer	Direct token transfer (post-graduation)
cypher_highlight_token	Promote a token
cypher_claim_referral_reward	Claim WETH referral rewards
cypher_stake_tokens	Deposit into staking vault
cypher_request_unstake	Start unstake cooldown (by asset amount)
cypher_request_unstake_by_shares	Start unstake cooldown (by share amount)
cypher_complete_unstake	Claim after cooldown
cypher_release_vested_tokens	Release vested tokens after cliff
cypher_create_vesting_schedule	Create vesting schedule for beneficiaries
cypher_send_eth	Send native ETH to any address (TxGate tracked)

Config Tools -- 4 tools

Tool	Description
cypher_update_config	Change slippage, risk limits, gas settings
cypher_update_tx_gate	Change spending limits, blacklist
cypher_start_strategy	Start an automated trading strategy (requires wss:// RPC)
cypher_stop_strategy	Stop a running strategy

Transaction Gate

All write operations go through a security layer that enforces:

• Per-tx limit: Rejects transactions above maxPerTxETH
• 24h budget: Tracks rolling spend, blocks when budget exhausted
• Cooldown: Minimum time between write operations
• Token blacklist: Blocks trades on known-bad tokens
• Confirmation: High-value txs trigger a confirmation prompt (if the OpenClaw channel supports it)
• Confirmation timeout: On the strategy path, a confirmation callback that hangs longer than 20 seconds is treated as a decline — the reservation is settled with zero wei and the trade is skipped, so a stuck UI cannot starve the 24h budget
• Chain-ID verification: The first write of an agent lifecycle verifies provider.getNetwork() against the configured expectedChainId (default: Ethereum Mainnet — 1) and refuses to submit the transaction on a mismatch

Defaults:

Max per tx:      1.0 ETH
24h budget:      5.0 ETH
Cooldown:        5 seconds
Confirm above:   0.5 ETH

The agent can adjust these at runtime via cypher_update_tx_gate.

Architecture

OpenClaw Gateway
  |
  +-- loads plugin via definePluginEntry().register(api)
  |     (typed helper from openclaw/plugin-sdk/plugin-entry)
  |
  +-- WalletManager (from SDK)
  |     +-- encrypted keystore (AES-256-GCM) [recommended]
  |     +-- env var (CYPHER_PRIVATE_KEY)
  |     +-- auto-generate new wallet
  |
  +-- LaunchpadAgent (from SDK)
  |
  +-- ToolExecutor (from SDK, with TxGate + "cypher_" prefix)
  |     +-- TOOL_DEFINITIONS (64 tools)
  |     +-- TxGate (spending limits + confirmation)
  |
  +-- for (def of tools.getTools()) -> api.registerTool(...)
        +-- execute() delegates to ToolExecutor.execute()

The plugin is a thin adapter — it only handles OpenClaw-specific setup (wallet resolution, config reading, tool registration loop) and complies with the official OpenClaw spec (activation.onStartup: true, top-level compatibility block, typed definePluginEntry entry point). All tool definitions, execution logic, and TxGate integration live in the SDK.

Example Conversations

User: "Check the price of token 0xABC... and buy 0.2 ETH worth if it looks good"

Agent will:

1. Call cypher_get_token_state to evaluate price, TVL, graduation %
2. Call cypher_quote_buy to see expected tokens for 0.2 ETH
3. Call cypher_buy_token to execute trade (goes through tx-gate)

User: "Deploy a new token called Moon Cat with a Telegram group"

Agent will:

1. Call cypher_upload_image to upload the token image
2. Call cypher_deploy_token with name, symbol, description, image URL, and socialLinks: { telegram: "https://t.me/mooncat" }

User: "Start the launch sniper strategy with 0.1 ETH"

Agent will:

1. Call cypher_start_strategy with { strategy_name: "launch_sniper", config: { ethAmount: "0.1" } }
2. Report status via cypher_get_strategy_status

Changes

See CHANGELOG.md for release notes. Latest: v1.3.11 — full ClawScan-canonical metadata + targeted env-surface scrub. Closes the v1.3.10 ClawScan review's two CONCERN findings ("Install Mechanism", "Credentials") plus the "Background Persistence" note. Adds a top-level install block (kind: "code", executesCode: true, declared entry + native deps) so the registry stops auto-classifying the package as instruction-only. Promotes setup.providers[0].envVars from a flat string array to the canonical object-array shape with full per-var metadata; adds provider-level primaryCredential / primaryCredentialAlternative and an authEvidence block (env x2 + keystore file). Adds a top-level capabilities block declaring exact network outbound hosts, filesystem write paths, wallet signing scope (bounded by TxGate), and explicit SDK-delegation trust scope. Splits register() into eager one-shot init (wallet resolve + LaunchpadAgent construction — fail-fast credential and RPC validation) versus lazy ensureBackgroundActivity() (the 60s TokenRegistry poller and the audit JSONL writer — the only recurring activities, deferred to first tool invocation). Trims the env surface from 16 to 5: two credentials (CYPHER_PRIVATE_KEY, CYPHER_KEYSTORE_PASSWORD) plus three operator-tunable knobs (CYPHER_RPC_URL, CYPHER_REFERRER_ADDRESS, CYPHER_TOOL_TIMEOUT_MS); the seven contract-address overrides + API/explorer/referral/audit-dir env vars are removed (closes an env-based phishing vector and matches the manifest declaration exactly). v1.3.10 — credential-disclosure transparency for the ClawHub registry summary: added a JSON Schema anyOf discriminated-union to configSchema (read-only mode, write-via-private-key, write-via-keystore — each branch with explicit required[]); expanded the manifest description and the package.json description to surface the wallet-credential requirement; enriched clawhub.envVars with primaryCredential / requiredFor / alternative cross-references; added a new openclaw-manifest.test.ts AJV regression suite that validates the configSchema against four config shapes. v1.3.9 — .env.example RPC example aligned with Ethereum Mainnet (was incorrectly labelled Base mainnet, contradicting the rest of the docs); README "Changes" section refreshed to summarise the post-v1.3.4 patch series. v1.3.4 → v1.3.8 are a cluster of ClawHub security-review cleanup patches: v1.3.4 refactored wallet plumbing to dodge a regex-based scanner false positive on the credential field, centralised the public Anvil dev key into a fixture, removed the stale IPFS section from .env.example, added an env-vars reference table, introduced a real top-level compatibility block bound to OpenClaw 2026.4.27. v1.3.5 restored the openclaw.compat / openclaw.build blocks the ClawHub publisher CLI requires. v1.3.6 routed the wallet-resolve call through a second helper to clear remaining scanner hits and renamed test fixture bindings. v1.3.7 + v1.3.8 scrubbed CHANGELOG prose that quoted the regex bait. v1.3.8 also added canonical setup.providers[] and providerAuthEnvVars env-var registry declarations. Older releases: v1.3.3 was the docs audit (README refresh, ClawHub install path, calendar-versioning OpenClaw requirement); v1.3.2 added the Algebra V4 default-pool LP management surface (add_liquidity / remove_liquidity / collect_fees / get_lp_positions).

Development

From Monorepo Root

git clone https://github.com/CypherIndustries/factory-agent-sdk
cd factory-agent-sdk

pnpm install
pnpm build

# Link for local testing
openclaw plugins install -l ./packages/openclaw-plugin
openclaw plugins doctor

Standalone

cd packages/openclaw-plugin
pnpm install
pnpm build
openclaw plugins install -l .

License

MIT