B.Fun AI

[Agent must follow] User agreement and local execution notice on first use#

When responding to any request about B.Fun or this skill, you must present the User Agreement and Local Execution Notice below before any state-changing operation. By choosing to continue, the user agrees to the User Agreement.

Until the user has explicitly agreed or confirmed to continue, do not run bfun buy, bfun sell, bfun send, or bfun create. Read-only commands such as config, verify, token-info, token-get, token-list, rankings, quote-buy, quote-sell, tax-info, and events may be used before confirmation.

Present the notice to the user before any state-changing operation.

User Agreement & Local Execution Notice#

User Agreement

Before using state-changing capabilities in this plugin and skill, read the following. By choosing to continue, the user has read, understood, and agreed to this agreement.

This package performs local CLI execution only. Signing material is expected to come from local runtime configuration. The plugin does not intentionally collect, upload, or custody signing material. The providers are not liable for asset loss, failed transactions, incorrect token creation, or other adverse outcomes caused by a compromised environment, tampered plugin, user error, third-party tools, or any other cause.

Local Execution Notice

• Never type, paste, or reveal secrets, seed phrases, or keystores in chat.
• Keep only limited funds in the execution wallet and move assets out after the operation.
• Verify the source of any agent, plugin, script, or browser extension before installing it.
• Before every state-changing operation, confirm the token address, amount, slippage, and target chain again.

State-changing operation confirmation rules#

Never execute any state-changing command ( buy, sell, send, create, 8004-register) from a generic acknowledgment alone. Before every such operation, the agent must:

1. Display a transaction summary showing: command, token/recipient address, amount, slippage (if applicable), and network (BSC mainnet).
2. Require a transaction-specific confirmation from the user that matches the displayed details.
3. If the user's input is ambiguous (unclear amount, partial address, unverified token), stop and ask for clarification rather than guessing.
4. Do not treat generic acknowledgments like "yes", "ok", "go ahead", or "do it" as sufficient confirmation unless they clearly refer to a specific transaction summary currently displayed.

Transfer safety rules ( send)#

The send command transfers BNB or ERC20 tokens and is irreversible. Additional rules:

• Never infer a recipient address from context or conversation history. The user must provide the full address explicitly for each transfer.
• Reject addresses that are not valid 0x-prefixed 40-hex-character strings.
• Before execution, display: asset type (BNB or token address), recipient, amount, and network.
• For first-time transfers to a new address, suggest a small test amount first.

Installation and execution#

Installation (required): npm install -g @b-fun/bfun-ai@latest. After install, run bfun <command> [args]; with local install only, use npx bfun <command> [args] from the project root. Run bfun --help for usage.

This repository keeps the canonical production package identity in source. Release exports map main to @b-fun/bfun-ai and dev to bfun-agent-dev; the dev package name is injected only into generated export artifacts, not the source tree.

Alternatively, clone and run locally without global install:

text

git clone https://github.com/bfun-ai/bfun-ai.git
cd bfun-ai
npm install
npx bfun <command> [args]

After install, verify your setup first:

text

bfun verify

This checks RPC, API, contract reachability, and wallet connectivity. Fix any failures before running other commands.

Invocation: The agent must run commands only via the bfun CLI: bfun <command> [args] or npx bfun <command> [args] (allowed-tools). Do not invoke src/index.js or individual files directly; the CLI entry ( bin/bfun.js) dispatches to the correct command and loads .env from the current working directory.

All command outputs are JSON and are intended to be passed through or summarized, not reformatted into invented fields.

Example outputs (from real CLI):

json

// bfun verify
{ "success": true, "data": { "config": { "chainId": 56, "apiUrl": "https://api.b.fun" }, "checks": { "rpc": { "status": "pass", "blockNumber": 88446009 }, "api": { "status": "pass" }, "contract": { "status": "pass", "factory": "0x718Fa..." }, "wallet": { "status": "pass", "address": "0x1173...", "balanceBNB": "0.012..." } } } }

// bfun quote-buy 0xToken 0.01
{ "success": true, "data": { "tokenAddress": "0x825e...", "phase": "curve", "pairType": "eth", "expectedOut": "2350672.37...", "minOut": "2233138.75...", "fee": "0.0006", "feeAsset": "BNB", "taxApplied": true, "taxRateBps": "500" } }

// error
{ "success": false, "error": "PRIVATE_KEY is not set. Export it or add it to .env" }

Capability overview#

CategoryCapabilityNotesQueryconfig, verifyChain config, API/RPC connectivity, contract reachability, optional wallet checkQuerytoken-infoOn-chain token metadata and authoritative phase ( curve, graduated, dex)Querytoken-get, token-list, rankingsREST-backed token discovery and detail viewsQueryquote-buy, quote-sellEstimate trade outputs and minimums before executionQuerytax-infoTax and vault-related API data for a tokenExecutionbuy, sellExecutes BNB-denominated operations using the helper contract path selected by market phaseCreatecreateCreates a standard or advanced B.Fun token with optional vesting, tax, vault, and first-buy settingsOpseventsReads recent factory events for debugging and operational inspectionUtilitysendTransfers BNB or ERC20 tokens when the user explicitly asks for a wallet transferERC-80048004-balance, 8004-registerQuery and register ERC-8004 Identity NFT for agent identity on-chain

CLI reference#

Read-only commands (no signing key required)#

CommandPurposebfun configShow active chain ID, RPC URL, API URL, and contract addressesbfun verifyCheck RPC, API, contract, and optional wallet connectivitybfun token-info <tokenAddress>Read on-chain token and bonding-curve state, including phasebfun token-get <tokenAddress>Fetch API token detail plus trade data when availablebfun token-list [--sort <sort>] [--kw <keyword>] [--offset <n>] [--limit <n>]List tokens from the B.Fun APIbfun rankings <orderBy> [--limit <n>]Fetch leaderboard slices from the same list endpointbfun quote-buy <tokenAddress> <bnbAmount> [--slippage <bps>]Quote BNB-to-token outputbfun quote-sell <tokenAddress> <tokenAmount> [--slippage <bps>]Quote token-to-BNB outputbfun tax-info <tokenAddress> [--user <address>]Fetch tax and vault info for a tokenbfun events [fromBlock] [--toBlock <block>] [--chunk <n>]Read factory events over a block rangebfun 8004-balance [address]Query ERC-8004 Identity NFT balance. If address omitted, uses current wallet

Supported token-list and rankings sort values:

ValueMeaningnow_trendingTrending (default)block_create_timeNewest (alias: newest, new)market_capMarket captrade_volume_24h24H trading volume (alias: volume, 24h_volume)bonding_curve_progressAbout to launch (alias: progress)latest_trade_timeLast traded (alias: last_traded)

State-changing commands ( PRIVATE_KEY required)#

CommandPurposebfun buy <tokenAddress> <bnbAmount> [--slippage <bps>]Execute a buy using BNBbfun sell <tokenAddress> <tokenAmount> [--slippage <bps>]Execute a sell into BNBbfun send <toAddress> <amount> [--token <tokenAddress>]Send BNB or ERC20 tokensbfun create ...Create a token with required and optional launch parametersbfun 8004-register <name> [--image <url>] [--description <text>]Register (mint) an ERC-8004 Identity NFT. Tokens created by holders are marked as Agent Created on-chain

create parameters#

Required:

FlagMeaning--name <name>Token name, max 32 chars--symbol <symbol>Token symbol, max 15 chars--image <path>Local image path, resolved from the current working directory

Common optional fields:

FlagMeaning--description <text>Token description--website <url>Website URL--twitter <handle>Twitter/X handle (with or without @, e.g. @mytoken or mytoken)--telegram <handle>Telegram handle (with or without @, e.g. @mytoken or mytoken)--pair <type>``ETH, CAKE, USDT, USD1, ASTER, U, or USDC``--buy-amount <amount>Optional first buy in collateral units

Advanced creation fields:

FlagMeaning--target-raise <amount>Explicit collateral target raise--bonding-curve-pct <pct>Must be between 50 and 80--vesting-pct <pct>Must be between 0 and 30--vesting-duration <value>Examples: 6m, 90d, 1y``--cliff-duration <value>Examples: 30d, 3m``--vesting-recipient <address>Recipient for creator vesting

Tax and vault creation fields:

FlagMeaning--tax-rate <pct>``1, 2, 3, or 5``--funds-pct <pct>Funds allocation percent--burn-pct <pct>Burn allocation percent--dividend-pct <pct>Dividend allocation percent--liquidity-pct <pct>Liquidity allocation percent--dividend-min-balance <tokens>Minimum balance for dividend eligibility--funds-recipient <address>Recipient when tax funds are enabled and no vault is used--vault-type <type>``split, snowball, burn_dividend, or gift``--split-recipients <json>Required for split vaults. Example: '[{"address":"0x1234...","pct":60},{"address":"0x5678...","pct":40}]'``--gift-x-handle <handle>Required for gift vaults

Detailed launch behavior lives in references/create-flow.md.

Environment configuration#

When using OpenClaw#

This skill declares PRIVATE_KEY and BSC_RPC_URL as optional environment variables in metadata. Read-only commands can run without signing configuration. State-changing commands require PRIVATE_KEY. The skill expects local runtime configuration and does not introduce any remote secret-management service.

Recommended steps:

1. Configure local signing env only if needed: If you plan to run state-changing commands, set the bfun-ai skill's apiKey (mapped to PRIVATE_KEY) in the Skill management page, or set PRIVATE_KEY under skills.entries["bfun-ai"].env in ~/.openclaw/openclaw.json. Optionally set BSC_RPC_URL if needed.
2. Enable this skill: In the agent or session, ensure the bfun-ai skill is enabled. Read-only commands can run without PRIVATE_KEY. State-changing commands ( create, buy, sell, send, 8004-register) will fail with a missing-key error if PRIVATE_KEY is not configured. BSC_RPC_URL is optional; if not set, the CLI uses a default BSC RPC. However, if the default RPC is unavailable in your network or region, set BSC_RPC_URL explicitly and rerun bfun verify.

Note: The apiKey field in the OpenClaw Skill management page maps to PRIVATE_KEY for this skill. It is local signing configuration, not a remote service credential, and is only needed for state-changing commands.

When not using OpenClaw (standalone)#

Set PRIVATE_KEY only when you need state-changing commands. Read-only commands can run without it. Optionally set BSC_RPC_URL via the process environment so it is available when running bfun or npx bfun:

• .env file: Put a .env file in the directory where you run the bfun command (i.e. your project / working directory). Example: if you run bfun quote-buy ... from /path/to/my-project, place .env at /path/to/my-project/.env. The CLI automatically loads .env from that current working directory. Use lines like PRIVATE_KEY=... and BSC_RPC_URL=.... Do not commit .env; add it to .gitignore.
• Shell export: export PRIVATE_KEY=your_hex_key and export BSC_RPC_URL=https://bsc-dataseed.binance.org (or another BSC RPC), then run bfun <command> ....

BSC_RPC_URL recommendation: While optional, explicitly setting BSC_RPC_URL is recommended. The default public RPC may be unavailable in some networks or regions. After setting it, run bfun verify to confirm connectivity.

Agent workflow#

Read-only discovery flow#

1. Use bfun config or bfun verify if the request is about environment state, connectivity, or setup.
2. Use bfun token-list --sort newest --limit 3 for discovery (always pass --sort; omitting it may return empty results). Use bfun rankings <orderBy> for specific leaderboard slices.
3. Use bfun token-info to inspect the on-chain phase before discussing execution.
4. Use bfun token-get when richer API detail or trade data is needed.
5. Use bfun quote-buy or bfun quote-sell before any trade recommendation or execution.

Quote and execution workflow#

1. Inspect the token with bfun token-info.
2. Check the phase and stop if the token is graduated.
3. Quote with bfun quote-buy or bfun quote-sell.
4. Present the quote, slippage basis points, and the local-execution risk notice.
5. Ask for explicit confirmation.
6. Run bfun buy or bfun sell.
7. Report the returned JSON fields directly, especially txHash, phase, expected output, minimum output, and receipt status.

Create workflow#

1. Collect required fields: name, symbol, image.
2. Ask whether the launch is standard or advanced.
3. If advanced, collect the exact pair, raise, vesting, tax, vault, and first-buy inputs.
4. Validate high-risk combinations before execution:
   • bonding-curve-pct + vesting-pct + 20 must equal 100
   • tax allocations must sum to 100
   • --funds-recipient or --vault-type is required when --funds-pct > 0
   • --split-recipients is required for split vaults
   • --gift-x-handle is required for gift vaults
5. Present the security notice and get explicit confirmation.
6. Run bfun create ....
7. Return the CLI JSON output without inventing extra state.

Utility and operational commands#

• bfun send is outside the default B.Fun quote/execution workflow. Use it only when the user explicitly asks for a transfer.
• bfun events is operational/debugging support. Use it when the user asks for recent launches, chain event inspection, or troubleshooting.

ERC-8004 Identity NFT#

ERC-8004 is an on-chain agent identity standard. Wallets holding an Identity NFT are recognized as AI agents; tokens they create are marked as Agent Created on-chain.

• Query: bfun 8004-balance [address] — read-only, no PRIVATE_KEY needed if address is provided.
• Register: bfun 8004-register <name> — mints an Identity NFT to the current wallet. Requires PRIVATE_KEY. Optional: --image <url>, --description <text>.

Default contract: 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432 (BSC mainnet).

Phase awareness#

Use bfun token-info as the phase gate before execution.

PhaseMeaningAgent actioncurveBonding-curve market is activeQuote and execute normallygraduatedCurve trading has stopped and migration is pending or in progressDo not execute; explain the token is between curve and DEX routingdexLiquidity has migrated and DEX routing is activeQuote/execute through the DEX-aware helper path

Important details:

• token-info derives the phase from on-chain curve state and returns isGraduated and isMigrated.
• buy and sell already switch between curve and DEX helper methods based on the quote result. The agent should still inspect phase first and explain what path is expected.
• Do not attempt to reason around a graduated state by guessing that migration has completed. Re-check with token-info if the user wants to try again later.

Detailed phase notes live in references/token-phases.md.

Common setup issues#

For troubleshooting PRIVATE_KEY is not set, fetch failed, No BondingCurve found, empty token-list, and other common errors, see references/errors.md.

References#

Read the reference files only when they are needed:

• references/create-flow.md: full launch parameter model, validation rules, pair templates, and vault behavior
• references/trade-flow.md: quote and execution flow, helper routing, and BNB-vs-collateral behavior
• references/token-phases.md: lifecycle guidance for curve, graduated, and dex
• references/contract-addresses.md: current chain addresses and collateral templates from this repo
• references/errors.md: common CLI failures and how to respond