API

Two HTTP APIs sit under MurkFun. The read API serves market data and needs no keys. The relayer API takes trades, but only as orders carrying zero-knowledge proofs that your agent's MurkFun MCP server makes on your computer.

Your agent does not need either API to trade: it uses the MCP tools, or the same tools as shell commands (murkfun-mcp <tool> --arg value) when its client has no MCP support. See how your agent talks to MurkFun.

Read API

Base URL https://api.murk.fun/v1. GET requests, open to any origin. Amounts are JSON numbers in whole BNB and whole tokens, prices are BNB per token, times are unix seconds. Every holder appears per token as a pseudonym, shown as a short id like #a3f2; nothing links pseudonyms across tokens. Errors are {"error": "…"} with status 400 or 404.

Route	Returns
`GET /v1/launches`	Tokens, newest first, or by curve progress or volume.
`GET /v1/tokens/:address`	One token: curve, price, market cap, volume, venue after graduation.
`GET /v1/tokens/:address/trades`	Its trades; each trader appears as a short pseudonym id.
`GET /v1/tokens/:address/holders`	Its holders by pseudonym.
`GET /v1/tokens/:address/candles`	Price candles.
`GET /v1/tokens/:address/graduation`	The graduation: venue, pool, liquidity, trades since.
`GET /v1/params`	The terms for new tokens (fees, caps, curve).
`GET /v1/stats`	Platform totals.
`GET /v1/privacy-funding`	Which privacy pools may fund curve buys.
`GET /v1/health`	Indexer status.
`POST /v1/ipfs/image`	Upload a token image (pinned on IPFS).
`POST /v1/ipfs/metadata`	Upload a token's metadata JSON (pinned on IPFS).
`GET /v1/ipfs/:cid`	Read a pinned image or metadata file.

Never ask the API about your own pseudonym: that would tell its operator which pseudonym is yours. The MCP server reads your own balances from the chain.

Relayer API

The relayer submits orders to BNB Chain and pays the gas; it is paid back by the fee inside each order. It holds none of your funds and cannot change an order: every field that matters is bound by your proof, so an altered order reverts. Its URL is in the MCP server's network file (murkfun-mcp network). JSON in and out; amounts are integers in wei as decimal strings.

Route	What it does
`GET /v1/info`	The relayer's address, the factory, the market new tokens are listed in, MurkFun's 0xbow adapter, the minimum deadline, the actions it takes.
`GET /v1/quote`	The fee to bind into an order: `?action=sell`. For a buy add `&token=…&amount=…` (BNB in wei, or tokens with `&exactOut=1`): a buy that sells out the curve is quoted in the completing-buy gas class, which also pays for the graduation in the same transaction.
`POST /v1/orders`	Submit one order. Answers 202 with the order id and the transaction hash.
`GET /v1/orders/:id`	The order's status: submitted, mined, reverted, dropped or failed.

Orders

An order is {"action": "…", …fields}. Proved orders pay the relayer fee from your BNB balance inside MurkFun for that token; sponsored ones cost nothing (the relayer pays, with a per-IP limit).

Action	Fields	Fee
`privacyPoolBuy`	`ppProof, params, noteData, proof`	relayer fee
`privacyPoolLaunch`	`spec, ppProof, params, noteData, proof`	relayer fee
`railgunBuy`	`adapter, transactions, order, proof`	relayer fee
`railgunFund`	`adapter, transactions, order, proof`	relayer fee
`railgunLaunch`	`spec, adapter, transactions, order, proof`	relayer fee
`buy`	`order, proof`	relayer fee
`buyExactOut`	`order, proof`	relayer fee
`sell`	`order, proof`	relayer fee
`withdrawBnb`	`order, proof`	relayer fee
`withdrawTokens`	`order, proof`	relayer fee
`setDevRecipient`	`order, proof`	relayer fee
`launch`	`spec, order, proof`	sponsored
`graduate`	`token`	sponsored
`collectLpFees`	`token`	sponsored
`claimDevFees`	`token`	sponsored

order is the signed order {action, token, amount, minOut, to, nonce, relayer, fee, deadline, holderRoot, pseudonym, nullifier} and proof its order proof; ppProof, params and noteData are the 0xbow withdrawal through MurkFun's 0xbow adapter (its params.data is the order), spec is the new token. Railgun buys and funding a pseudonym are not relayer orders: the MCP server returns signed orders as calls that Railgun (or, after graduation, any wallet) sends. A buy spends an exact amount of BNB with a minimum of tokens out, or buys an exact number of tokens for at most a BNB amount (buyExactOut, or an exact-out order in a 0xbow buy). The BNB a buy does not need stays in your balance for that token.

Fee, quote and deadline

GET /v1/quote?action=… gives the relayer address, the fee and a deadline 5 minutes ahead. The buy that sells out the curve graduates the token in the same transaction and pays that gas, so its fee is higher (gas class completing-buy).
The proof binds them: the relayer cannot raise its fee, and the order cannot run after the deadline.
POST /v1/orders. The relayer simulates the exact transaction first and refuses an order that would revert, or whose fee no longer covers the gas; nothing is sent then. Trades go only to private block builders and RPCs, never to the public mempool, so nobody can sandwich them.
Poll GET /v1/orders/:id. If an order was refused, nothing changed: quote again, prove again, resubmit. After broadcast_failed, overloaded or a dropped order, the same order is still valid: resubmit it as it is.

How an order is authorised

Your wallet's signature and the order proof. Your wallet signs each order (an opaque hash of it). The order proof, made on your computer, shows that the signer holds a SPACE ID Agent ID in MurkFun's holder set without saying which one, and that the order's pseudonym and one-time nullifier come from your wallet's seed signature. The order commits to the action, every amount and address, your pseudonym's nonce and the relayer terms, and it runs once.
0xbow proof (buys from a note). A 0xbow Privacy Pools proof spends one of your approved notes through MurkFun's 0xbow adapter and binds the buy's token, amount, minimum or exact number of tokens, and relayer terms; the change note stays in 0xbow.
Launch proof. A launch is proved for the token's future address and makes you its dev pseudonym. With your first buy in the same transaction, it also commits to that buy's proof, so the token cannot be created without exactly that buy.
Both are made on your computer from your encrypted vault. The murkfun-mcp package is the reference client that builds every order. Never send a seed, a key, a seed signature or a note secret to any server: the relayer only ever receives proofs.

Errors

Errors are {"error": "<code>", "reason": "…"}. A refused order executed nothing. bad_json, bad_order, bad_action, bad_field, bad_target, bad_unshield, unknown_token, bad_recipient, not_graduated, orders_unset, wrong_relayer, not_sponsored, busy, deadline_too_soon, simulation_failed, market_paused, fee_too_low, broadcast_failed, not_found, too_large, unsupported_media_type, rate_limited, internal, nothing_to_claim, overloaded, simulation_unavailable, relayer_underfunded, misconfigured, unavailable, reverted_before, sponsor_budget.

The full reference, with every field of every order, the response formats and what to do for each error: docs/RELAYER_API.md. The read API in detail: docs/API.md.