@bolttx/mcp-server

MCP (Model Context Protocol) server for BoltTx. Submit Solana transactions and use BoltTx as your Solana RPC through any MCP-compatible AI agent.

Tell your AI agent in plain English: "Send 0.1 SOL to <address> via BoltTx with the minimum tip." The agent builds the transaction, your wallet signs it, BoltTx delivers it on-chain with sub-second confirmation.

---

What is this?

MCP is an open protocol that lets AI agents call external tools at runtime — like a "USB for AI". Any MCP-compatible agent can use this server natively.

This package is the MCP server for BoltTx. Once installed, your AI agent gains these capabilities:

• bolttx_get_my_account — inspect your BoltTx plan, TPS budget, cumulative tip
• bolttx_get_tip_amount — look up minimum tip for a given plan
• bolttx_list_tip_addresses — get the 9 canonical tip addresses
• bolttx_send_transaction — submit a signed transaction to BoltTx
• bolttx_send_batch — submit up to 100 transactions in one call
• bolttx_get_status — query BoltTx delivery telemetry for a signature

Plus static resources the agent can read:

• bolttx://plans — full plan table
• bolttx://tip-addresses — tip address list
• bolttx://quickstart — minimum working example
• bolttx://rpc — how to use BoltTx as a drop-in Solana RPC URL

Two ways to send

1. MCP tools (this package) — let the agent drive everything end-to-end: reason about plan, pick a tip, build, submit, poll status.
2. Drop-in RPC URL — if you already have Solana SDK code, just swap the sendTransaction RPC endpoint to https://bolttx.io/?api-key=... and keep the rest of your code untouched. See bolttx://rpc or the RPC section below for details.

Safety

This server never touches your private keys. Transactions must be signed by your local wallet / keypair BEFORE being passed to bolttx_send_transaction. The MCP protocol is used only for:

• Building transaction structure (recipient, amount, tip)
• Submitting already-signed base64 bytes
• Querying status of transactions you submitted

Your private keys stay in whatever signing workflow you already use (Phantom, Solflare, local keypair file, hardware wallet, etc.).

---

Installation

1. Get a BoltTx API key

• Sign up at bolttx.io
• Create an API key in the dashboard
• Save the key (shown only once — format: btx_live_xxx...)

2. Add to your MCP client

Add the bolttx server to your agent's MCP configuration:

{
  "mcpServers": {
    "bolttx": {
      "command": "npx",
      "args": ["-y", "@bolttx/mcp-server"],
      "env": {
        "BOLTTX_API_KEY": "btx_live_your_api_key_here"
      }
    }
  }
}

The configuration file location depends on your agent. Check your agent's documentation for the MCP settings path. Restart the agent after editing.

---

Usage examples

Once installed, just ask your AI agent in plain English.

Example 1 — inspect account

You: What's my current BoltTx plan?

Agent (calls bolttx_get_my_account): You're on the Growth plan with 30 TPS. You've paid 2.34 SOL in cumulative tips — 77.66 SOL to go until auto-upgrade to Pro.

Example 2 — send SOL

You: Send 0.05 SOL to J1k1L1X5AfgJrsWhQ1EGJmKcEFmtJd21Xq8hJQK5dYNc using BoltTx with minimum tip. Use my ~/.config/solana/id.json keypair.

Agent (internally):

1. Calls bolttx_get_my_account → learns plan=growth, min tip = 500,000 lamports
2. Calls bolttx_list_tip_addresses → picks BoLt3D1LXn3ne9t569Csq373xoau1fFbFpU6SSc6QaH2
3. Fetches blockhash from your Solana RPC
4. Builds tx: [SystemProgram.transfer(recipient, 50_000_000), SystemProgram.transfer(tip_addr, 500_000)]
5. Signs locally with your keypair (via the host agent's shell / filesystem tools)
6. Serializes to base64
7. Calls bolttx_send_transaction(transaction_base64=...) → returns signature
8. Calls bolttx_get_status(signature) after a short wait → confirms it landed in 412ms

Result: 5xKnR8qXeVm3pN... landed in slot 234567890, 412ms after submission.

Example 3 — batch

You: I have 20 transactions pre-signed in ~/txs.json. Submit them all.

Agent: (reads file, extracts base64 array, calls bolttx_send_batch)

Example 4 — troubleshoot

You: Did my transaction 5xKn... land?

Agent (calls bolttx_get_status): Yes, confirmed in slot 234567890, 412ms after submission. API key: prod-bot-1.

---

Environment variables

Variable	Required	Default	Purpose
BOLTTX_API_KEY	yes	—	Your API key from the BoltTx dashboard
BOLTTX_BASE_URL	no	https://bolttx.io	Alternative BoltTx endpoint

---

Endpoint

BoltTx exposes a single endpoint at https://bolttx.io — auto-routed to the fastest landing path. Both HTTPS and HTTP are supported.

Available routes (all on the same host):

• POST /v1/send — single signed transaction
• POST /v1/send/batch — up to 100 signed transactions
• POST /?api-key=... — Solana JSON-RPC compatible (sendTransaction only)

Rate limits and tip rules are enforced per-account.

---

Use BoltTx as a Solana RPC URL

Instead of (or in addition to) the MCP tools, BoltTx is also a drop-in Solana RPC endpoint for sendTransaction. If you already have Solana SDK code, swap the RPC URL and keep everything else:

https://bolttx.io/?api-key=<YOUR_API_KEY>

Supported method: sendTransaction only (everything else — getAccountInfo, getLatestBlockhash, … — must still go to a regular Solana RPC). Default encoding is base58; pass { "encoding": "base64" } as the second params element to send base64-encoded bytes.

@solana/web3.js

import { Connection, Transaction, SystemProgram, PublicKey } from "@solana/web3.js";

const readRpc = new Connection("https://api.mainnet-beta.solana.com");
const sendRpc = new Connection(
  "https://bolttx.io/?api-key=" + process.env.BOLTTX_API_KEY,
  "confirmed",
);

const tx = new Transaction().add(
  // ... your instructions ...
  // MANDATORY tip transfer — BoltTx rejects txs without one (HTTP 402).
  SystemProgram.transfer({
    fromPubkey: payer.publicKey,
    toPubkey: new PublicKey("BoLt1A77XnXgmLPTWFXztQ9oZRrTPuQHV7cChFCt35g6"),
    lamports: 800_000, // >= your plan's minimum
  }),
);
tx.recentBlockhash = (await readRpc.getLatestBlockhash()).blockhash;
tx.sign(payer);
const sig = await sendRpc.sendRawTransaction(
  tx.serialize(),
  { skipPreflight: true },
);

solana-py

from solana.rpc.api import Client
from solana.rpc.types import TxOpts

client = Client("https://bolttx.io/?api-key=" + BOLTTX_API_KEY)
response = client.send_raw_transaction(
    signed_tx.serialize(),
    opts=TxOpts(skip_preflight=True),
)

Rust

use solana_client::nonblocking::rpc_client::RpcClient;
use solana_sdk::commitment_config::CommitmentConfig;

let rpc = RpcClient::new_with_commitment(
    "https://bolttx.io/?api-key=YOUR_API_KEY".to_string(),
    CommitmentConfig::confirmed(),
);
let sig = rpc.send_transaction(&signed_tx).await?;

The tip rule applies to both paths: the MCP tool and the RPC URL. A transaction without a BoltTx tip transfer is rejected regardless of how you submit it. Full reference with error codes: bolttx.io/docs/api/rpc.

---

Troubleshooting

"BoltTx MCP server requires BOLTTX_API_KEY" Set BOLTTX_API_KEY in the env block of your MCP client config. Restart the agent.

Agent says "bolttx tool is not available" Confirm the server appears in your agent's MCP server list. Check the startup log for parse errors.

"Rate limit exceeded" You've hit your plan's TPS cap. Either wait (the error includes retry_after_ms) or upgrade your plan at bolttx.io/dashboard.

"Transaction must include a tip transfer" Your transaction is missing the mandatory SystemProgram transfer to a BoltTx tip address. Call bolttx_list_tip_addresses and add a transfer instruction before submitting.

---

Links

• BoltTx dashboard: https://bolttx.io/dashboard
• Full API docs: https://bolttx.io/docs
• LLM-friendly reference: https://bolttx.io/llms-full.txt
• MCP protocol spec: https://modelcontextprotocol.io
• Issues / feedback: contact@bolttx.io

License

MIT — see LICENSE.