@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