Agent guide

On MurkFun you trade only through your own AI agent, running on your own computer. This website cannot trade, holds no keys and never asks you to sign.

The sentence above sends your agent to the skill file, which walks it through everything below. To do it by hand, or to check what your agent is doing, follow the steps.

1. Install the MCP server

On your own computer, with Node 20 or newer, from the MCP server's GitHub release. No sudo with a user-level npm prefix (nvm, for example); everything goes under ~/.murkfun. murkfun-mcp init creates a random vault passphrase file (it keeps one that already exists), downloads and checks the 0xbow circuits and prints the config for your MCP client. Running it again is safe.

npm install -g https://github.com/murkfun/murkfun-mcp/releases/latest/download/murkfun-mcp.tgz
murkfun-mcp init

The same command updates it to the latest release. To build it from source instead:

git clone https://github.com/murkfun/murkfun-mcp && cd murkfun-mcp && npm ci && npm run build && npm link

The server keeps your keys and notes in an encrypted vault on your computer, has your wallet sign each order, makes the zero-knowledge proofs locally and sends only signed, proved orders to the relayer. Keep a copy of ~/.murkfun/passphrase offline: encrypted backups are useless without it.

2. Connect it to your agent

Print the config again at any time:

murkfun-mcp config claude-code
murkfun-mcp config json

• Claude Code: run the printed claude mcp add command.
• Cursor, Claude Desktop and other clients: merge the JSON into their mcpServers config (~/.cursor/mcp.json, claude_desktop_config.json).
• Codex: put the same values into ~/.codex/config.toml:

[mcp_servers.murkfun]
command = "murkfun-mcp"
args = []
env = { MURKFUN_PASSPHRASE_FILE = "<...>", MURKFUN_RELAYER_URL = "<...>", MURKFUN_DEPLOYMENT = "<...>" }

If the printed config holds a value in angle brackets (MURKFUN_RELAYER_URL, MURKFUN_DEPLOYMENT), replace it with the real one. If your client cannot find murkfun-mcp (it starts servers without your shell's PATH, as with nvm), print the config with murkfun-mcp config json --absolute. Then restart the agent so it loads the murkfun tools.

No MCP support in your agent's client? It can run every tool as a shell command instead (how your agent talks to MurkFun).

3. Add the skill file

SKILL.md tells your agent the setup steps, the order of operations and the hard rules. It is a file for AIs: skill.md (also at /skills/murkfun/SKILL.md). For Claude Code:

mkdir -p ~/.claude/skills/murkfun
curl -fsSL https://murk.fun/skill.md -o ~/.claude/skills/murkfun/SKILL.md

4. First run

1. MurkFun requires a SPACE ID Agent ID: claim one in the Binance Agentic Wallet (Binance App → Wallet → AI agent / Agent ID). Then install its CLI (npm install -g @binance/agentic-wallet, then baw auth signin), turn on Developer Mode in the Binance App, and set MURKFUN_SIGNER=baw in the MCP config: the agent wallet then signs every order (it has no key to export).
2. setup creates the vault, shows your wallet address and has the wallet sign the MurkFun seed message once. This wallet is public and linked to you; it never sends a MurkFun transaction. Your pseudonyms come from that signature: your wallet is your backup.
3. Guard the wallet. If the agent created it, save its key at once with export_recovery (a plaintext file; move it offline and delete it from the computer). You can also use your own wallet.
4. Wait until status shows holderSet.inAcceptedRoot: true. New Agent ID holders join MurkFun's holder set in batches, without any transaction from you, and can trade 1 h after their batch is posted.
5. With Railgun (the default) the wallet needs no BNB: it only signs. For 0xbow, send BNB to the wallet: the amount you want to deposit plus about 0.003 BNB for gas.

5. Buy: two privacy pools

Either way, sells, withdrawals, caps and fees are the same. See How it works and Privacy.

6. Trade and withdraw

• Before each buy or sell your agent tells you the amount, the expected fill, the slippage limit (3% by default) and the relayer fee, and waits for your OK.
• While a token is on the curve, one pseudonym can hold at most 1% of supply. The buy that sells out the curve gets exactly what is left and graduates the token in the same transaction; the BNB it does not need stays in the token's balance. If that graduation fails, buys wait until anyone retries it with graduate, while sells and withdrawals keep working as long as the market is not paused (a sell reopens the curve).
• Sale proceeds stay in MurkFun as the token's BNB balance. withdraw_bnb pays it to an address you give, at any time unless the market is paused; withdraw_token works after graduation. A fresh address keeps you private. Use an address you control: the contracts refuse only some destinations where funds are lost (a MurkFun contract or token, WBNB), not all (a burn address), so the tools refuse every one of them, and ask you to confirm any other contract address (a Safe, for example).

Safety rules your agent follows

• It never asks for, prints or sends the seed, the wallet key, the signature of the MurkFun message, the passphrase, the recovery file or the vault. No MurkFun tool returns them. Never sign the message "MurkFun seed" anywhere else: that signature is your MurkFun key.
• It confirms the amount, token and destination before every deposit, buy, sell, withdrawal or launch, and never raises slippage without asking.
• It never overwrites an existing vault, and runs one MurkFun action at a time.
• It withdraws only to an address you give it, never to a MurkFun contract, a MurkFun token or WBNB, sends to another contract only after you confirm it is yours, and reminds you that deposits, withdrawal addresses and timing are public.

MCP tools

Troubleshooting

Most errors are not MurkFun's servers failing. They come from five places: your own setup, your wallet, MurkFun's relayer, MurkFun's contracts on the chain, and the privacy pool.

If a tool fails partway, the agent calls status before retrying: notes and balances are read from the chain.

Backups and recovery

Your wallet is your backup: everything secret is derived from its signature of one fixed message. On a new computer, install as above and run recover_from_wallet: the same wallet signs again, and your pseudonyms, balances and 0xbow notes come back from the chain. Guard that wallet; whoever holds its key can sign orders and controls your MurkFun funds.

How your agent talks to MurkFun

1. MCP tools (preferred). The MurkFun MCP server on your computer gives your agent the tools above. It keeps your secrets in the encrypted vault, makes every proof locally and sends only proved orders.
2. The same tools as shell commands, for agents whose client has no MCP support (Codex, Cursor, OpenClaw, scripts): murkfun-mcp <tool> --arg value or --json '{…}'. Same code, same environment, same vault, same JSON output; errors go to stderr with exit code 1. murkfun-mcp tools lists every tool with its JSON Schema. The safety rules are the same: no tool prints a secret, secrets are passed as file paths and never typed on the command line, and export_recovery still needs --confirm. Calls on one vault run one at a time.
3. The HTTP APIs underneath. The read API (https://api.murk.fun/v1/launches?sort=new, /tokens/<address>, /tokens/<address>/trades) needs no keys: read market data from it directly. The relayer API accepts only orders with proofs made from your vault: use it only through a client that makes them, such as the MCP server. Both are described on the API page.

export MURKFUN_PASSPHRASE_FILE=~/.murkfun/passphrase
murkfun-mcp status
murkfun-mcp buy --token 0x… --bnbAmount 0.1
murkfun-mcp order_status --id …

Endpoints

Market data: a read-only API, no keys, GET only, JSON. Base URL https://api.murk.fun/v1:

curl -s 'https://api.murk.fun/v1/launches?sort=new&limit=20'
curl -s https://api.murk.fun/v1/tokens/<address>
curl -s 'https://api.murk.fun/v1/tokens/<address>/trades?limit=50'
curl -s https://api.murk.fun/v1/tokens/<address>/holders
curl -s 'https://api.murk.fun/v1/tokens/<address>/candles?interval=5m'
curl -s https://api.murk.fun/v1/tokens/<address>/graduation
curl -s https://api.murk.fun/v1/stats
curl -s https://api.murk.fun/v1/params

Uploads, on the same host: POST /v1/ipfs/image and POST /v1/ipfs/metadata put a token's image and metadata on IPFS (upload_token_metadata uses them).

Relayer: GET /v1/info, GET /v1/quote, POST /v1/orders, GET /v1/orders/:id at the relayer URL. Every order carries zero-knowledge proofs made on your computer from your vault, so orders go through the MCP tools (or their shell commands), never as hand-written HTTP requests.

The URLs the MCP server uses ship with it, in the package's networks/bsc.json; murkfun-mcp network prints them. Every route and field: the API page.

Contracts on BNB Chain

BSC mainnet (chain 56), deployed at block 132262524. Source verified on Sourcify; the links open BscScan.

• MurkFunFactory0x11e02275559FEDd72a0B578cc5b4c0F766aCa25ASourcify
• MurkFunMarket0x9717126512c5a4D3b5c0E13421639ea80DACaa91Sourcify
• MurkFunOrders0xCc09A7772aDAf0586040a933b70B1248F432eb87Sourcify
• OrderVerifier0xfA99009F7c850294aDd481cD6764f60F547076b7Sourcify
• MurkFunDex0x69d0B74c1b6C835e212E6EDe9AfB1e7286DD3FF4Sourcify
• MurkFunInfinityHook0x833eAEe7102Ea77C5Bb0C6B2Fb3F64F9032B45e6Sourcify
• MurkFunLocker0xFD25D90f151193A795E4a9De6F0bBB9dD5AA32A8Sourcify
• MurkFunPrivacyPoolAdapter0x0242771ba1758554fa6C806d9219c7dF891c9879Sourcify
• MurkFunRailgunAdapter0x2ba9978Ba84dB605c1b6a7F0885f84Af340Ad249Sourcify
• MurkFunHolderRoots0xD59867DADC96202284Fa54d016C6d66a0adBaE24Sourcify
• BatchVerifier0x3BA574b3d102800c3E08E2F978A4d802C15b8C9ESourcify

Verify it yourself

The holder set every order proves membership in is checkable by anyone, from the chain alone: github.com/murkfun/holder-roots rebuilds the tree from the contract's Batch events, compares every root with MurkFunHolderRoots, audits the set against the SPACE ID registry, checks that the deployed bytecode is its sources, and sends fraud proofs. Install it and rebuild the tree as below, or browse the set on the holders page.

npm install -g https://github.com/murkfun/holder-roots/releases/latest/download/murkfun-holders.tgz
murkfun-holders tree