<p align="center">
  <img src="docs/logo.svg" alt="pump-mcp-bundler logo" width="88" />
</p>

# pump-mcp-bundler

A local operator console and MCP server for coordinated pump.fun trades. Build transactions with pump.fun's official SDK, sign with encrypted local wallets in Rust, and submit atomic Jito bundles.

**Buy with 2–4 wallets. Sell with 2–4 wallets. Launch with a developer, mint key, and 1–4 buyers.**

> Execution uses real Solana mainnet funds. Review every preview, simulate before executing, and never risk funds you cannot afford to lose. No privacy, profit, or inclusion guarantee is made.

![Operator overview](docs/screenshots/overview.png)

## What is included

- **Operator dashboard:** wallet management, buy/sell, launch, preview, simulation, explicit execution, confirmation, and persistent history.
- **Encrypted wallets:** Argon2id and AES-256-GCM, restrictive file permissions, public keys only outside the executor.
- **Coordinated buys:** official-SDK transactions on the bonding curve or PumpSwap.
- **Coordinated sells:** independent percentages per wallet with sequential price-impact accounting on active SOL-paired bonding curves.
- **Token launches:** create plus optional developer buy and 1–4 buyer transactions, with developer and mint signatures held locally.
- **Safe execution lifecycle:** immutable previews, signature-verified simulation, explicit submission, duplicate-submission protection, and explorer links.
- **Real status tracking:** Jito bundle status plus Solana signature confirmation, failure, expiry, and not-found handling.
- **Restart recovery:** non-secret bundle records persist across executor restarts.
- **Pump MCP:** Code Mode `search` and `execute`, official pump.fun API routes, direct curve reads, RPC, metadata pinning, and unsigned single-wallet trades.

Not included: Binance funding, volume automation, wallet-link obfuscation, or “stealth” claims.

## Architecture

![Architecture](docs/architecture.svg)

- **Svelte dashboard** provides the local operator interface.
- **Pump MCP** validates requests and builds unsigned official-SDK transactions.
- **Rust executor** stores encrypted keys, retains immutable previews, simulates, signs, submits to Jito, and refreshes confirmation.
- **Solana RPC and Jito** provide chain state, simulation, submission, and confirmation.

Private keys never enter the dashboard, Pump MCP, Code Mode sandbox, or persistent bundle history. The executor listens only on `127.0.0.1`; every executor route requires its own bearer token. The dashboard API is loopback-only and uses `MCP_BEARER_TOKEN`.

A remote Cloudflare Worker cannot reach the executor on your computer. Run both processes locally for bundle execution.

## Quickstart

### Requirements

- Bun 1.2 or newer
- Stable Rust and Cargo
- A Solana mainnet RPC URL
- An RPC provider supporting `simulateBundle` for launches and coordinated sells; Helius mainnet RPC supports it
- Funded wallets for real execution

### Configure

```sh
bun install
cp .dev.vars.example .dev.vars
```

Edit `.dev.vars`:

```dotenv
MCP_BEARER_TOKEN=replace-with-a-long-random-token
RPC_URL=https://mainnet.helius-rpc.com/?api-key=YOUR_KEY
EXECUTOR_URL=http://127.0.0.1:8787
EXECUTOR_TOKEN=replace-with-a-different-long-random-token
```

Optional settings include `PUMP_API_KEY`, `PINATA_JWT`, `LOOKUP_TABLES`, and `PUMP_OPENAPI_URL`. See `.dev.vars.example` and `wrangler.toml`.

### Start the executor

From `executor/`:

```sh
export WALLET_PASSPHRASE='use-a-strong-unique-passphrase'
export EXECUTOR_TOKEN='the-executor-token-from-dev-vars'
export RPC_URL='the-same-mainnet-rpc-url'
cargo run
```

Optional executor configuration:

| Variable | Default | Purpose |
|---|---|---|
| `WALLET_DIR` | `wallets/` | Encrypted wallet records |
| `STATE_FILE` | `data/bundles.json` | Non-secret previews, submissions, and history |
| `JITO_ENDPOINTS` | Jito mainnet regions | Comma-separated submission fallback endpoints |

### Start Pump MCP and the dashboard

From the repository root:

```sh
bun run dev
```

Open **http://localhost:8790** and enter `MCP_BEARER_TOKEN`. The token is kept only in `sessionStorage` and is removed when the browser session ends.

For frontend hot reload, run `bun run dev:web` and use http://127.0.0.1:5173.

### Connect an AI client

```sh
claude mcp add --transport http pump-bundler http://localhost:8790/mcp \
  --header "Authorization: Bearer <MCP_BEARER_TOKEN>"
```

Any streamable-HTTP MCP client that supports a bearer header can connect to `/mcp`.

## Wallets

Generate wallets in the dashboard or from `executor/`:

```sh
export WALLET_PASSPHRASE='your-wallet-passphrase'
cargo run -- wallet generate --id dev
cargo run -- wallet generate --id mint
cargo run -- wallet generate --id buyer-a
cargo run -- wallet generate --id buyer-b
cargo run -- wallet list
```

![Wallet management](docs/screenshots/wallets.png)

- IDs may contain letters, numbers, `_`, and `-`.
- Generation never overwrites an existing ID.
- Fund public addresses manually; the application does not withdraw from an exchange.
- The `mint` role is only a new token keypair and needs no funds.
- Developer and buyer wallets need enough SOL for purchases, rent, fees, and the Jito tip on the last transaction.
- Wallet secrets are never returned by an API or written to bundle history.

## Buy and sell

### Coordinated buy

Select an existing mint, 2–4 wallets, SOL per wallet, slippage, priority fee, and tip. The preview shows per-wallet quotes and total planned SOL.

![Buy preview](docs/screenshots/buy-preview.png)

MCP request:

```js
async () => codemode.request({
  method: "POST",
  path: "/bundle/preview",
  body: {
    mint: "TOKEN_MINT",
    walletIds: ["buyer-a", "buyer-b"],
    amountPerWallet: 0.05,
    slippage: 10,
    priorityFee: 0.0001,
    jitoTipLamports: 1000000
  }
})
```

### Coordinated sell

Select an active SOL-paired bonding-curve mint and 2–4 wallets. Each wallet has its own percentage from greater than 0 through 100. Quotes account for preceding sells and enforce the configured slippage.

![Sell preview](docs/screenshots/sell-preview.png)

```js
async () => codemode.request({
  method: "POST",
  path: "/sell/preview",
  body: {
    mint: "TOKEN_MINT",
    sells: [
      { walletId: "buyer-a", percentage: 50 },
      { walletId: "buyer-b", percentage: 100 }
    ],
    slippage: 10,
    priorityFee: 0.0001,
    jitoTipLamports: 1000000
  }
})
```

Coordinated sells currently reject graduated, Mayhem, non-SOL-quote, cashback, and zero-balance coins. Ordinary unsigned `/trade` sells remain available for other supported venues.

## Coordinated token launch

A launch is one ordered atomic bundle:

1. Create the token and optionally make a developer buy.
2. Buy from each of 1–4 selected buyer wallets.
3. Pay the Jito tip from the last transaction.

Developer and mint sign the create transaction inside the Rust executor. Buyer quotes account for the developer buy and all preceding buyer purchases.

![Launch preview](docs/screenshots/launch-preview.png)

A nonzero developer buy needs an address lookup table:

```sh
bun run lookup-table --keypair /path/to/operator-wallet.json
bun run lookup-table --keypair /path/to/operator-wallet.json --yes
```

Set the resulting `LOOKUP_TABLES` value in `wrangler.toml`. Alternatively use `devBuySol: 0` when no developer purchase is wanted.

Pin an image and metadata with `POST /metadata`, or provide another valid `ipfs://` or HTTPS metadata URI. Then preview:

```js
async () => codemode.request({
  method: "POST",
  path: "/launch/preview",
  body: {
    devWalletId: "dev",
    mintWalletId: "mint",
    buyerWalletIds: ["buyer-a", "buyer-b"],
    devBuySol: 0.5,
    amountPerWallet: 0.05,
    slippage: 10,
    priorityFee: 0.0001,
    jitoTipLamports: 1000000,
    tokenMetadata: {
      name: "Example",
      symbol: "EXAMPLE",
      uri: "ipfs://METADATA_CID"
    }
  }
})
```

Launches are SOL-paired, have Mayhem mode disabled, require distinct wallet roles, and cannot buy enough to complete the bonding curve.

## Preview, simulate, execute, confirm

![Execution status](docs/screenshots/execution-status.png)

The dashboard guides the same lifecycle exposed through MCP:

```text
preview → simulate → explicit execute → submitted → confirmed / failed / expired / not-found
```

- **Preview:** transactions and quotes are fixed. Nothing is signed or submitted.
- **Simulate:** the executor signs the exact retained messages in memory. Launches and coordinated sells use sequential `simulateBundle`; ordinary buys use `simulateTransaction`.
- **Execute:** available only after successful simulation and explicit mainnet confirmation.
- **Submitted:** Jito accepted a bundle ID. This does not prove inclusion.
- **Confirmed:** Jito or Solana reports confirmed/finalized execution.
- **Failed:** a provider reports an execution error.
- **Expired:** the transaction blockhash expired without confirmation.
- **Not found:** no provider has a record yet. Recheck before taking any recovery action.

Status responses include the bundle ID, signatures, optional confirmation slot/error, and Solscan links in the dashboard. Never rebroadcast blindly after an uncertain result.

![Bundle history](docs/screenshots/history.png)

History is stored in `STATE_FILE` without private keys, tokens, passphrases, or RPC URLs. Previews and submissions survive executor restarts. A recovered preview still needs valid blockhashes and successful simulation before it can execute.

## Other MCP capabilities

- 67 official pump.fun Developer API operations with an approved `PUMP_API_KEY`.
- Direct curve reads at `GET /curve/{mint}`.
- Allow-listed Solana RPC through `POST /rpc`.
- Unsigned single-wallet buy, sell, and create through `POST /trade`.
- IPFS image and metadata pinning through `POST /metadata` with `PINATA_JWT`.

See `GET /openapi.json` or `src/spec.ts` for the full route surface.

## Troubleshooting

**The dashboard token is rejected.** Use `MCP_BEARER_TOKEN`, not `EXECUTOR_TOKEN` or `WALLET_PASSPHRASE`.

**The executor is unavailable.** Confirm it is running on `127.0.0.1:8787`, both processes use the same `EXECUTOR_TOKEN`, and `EXECUTOR_URL` is loopback HTTP.

**Launch or sell simulation fails with an unknown method.** Use an RPC provider that supports `simulateBundle`; plain `simulateTransaction` support is not enough for dependent transactions.

**Create plus dev buy exceeds packet size.** Configure `LOOKUP_TABLES` or set `devBuySol: 0`.

**A wallet has insufficient funds.** Include purchase amount, associated-token-account rent, network/priority fees, and the final Jito tip in your funding calculation.

**A bundle stays submitted or not found.** Acceptance does not guarantee landing. Poll status and inspect signatures before deciding what to do next.

**A preview disappeared or cannot execute.** Check `STATE_FILE`, file permissions, and blockhash validity. Recovered previews must still pass simulation.

## Security and limitations

- Keep the dashboard and executor on loopback. Do not expose them to a shared or public network.
- Anyone with the MCP bearer token can request local wallet generation and bundle execution while the executor is running.
- Encryption protects wallet files at rest; an unlocked executor or compromised operating system can still access keys.
- Bundle participants are publicly visible on-chain. This project makes no unlinkability claim.
- Simulation does not guarantee inclusion or future state.
- Jito execution targets Solana mainnet; no Jito devnet workflow is provided.
- Automated tests and screenshots use mocks. They do not execute a real token launch or spend real SOL.

## Development and verification

```sh
bun test
bun run typecheck
bun run build
bunx playwright install chromium
bun run test:e2e
bun run screenshots

cd executor
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test
```

Browser tests use stateful API mocks. Rust tests use mock Solana/Jito servers. See `CONTRIBUTING.md` for project layout and change guidelines.

## Acknowledgements

Built from [pump-mcp](https://github.com/ex0th3rmic/pump-mcp), using pump.fun's official SDK and public documentation. The Jito orchestration concept was informed by [SolBundler](https://github.com/ZenyyDEV/pumpfun-stealth-bundler); custody, execution, persistence, and dashboard design are implemented separately.

MIT licensed. Not affiliated with pump.fun, Jito, or Helius. Nothing here is financial advice.