Source code for every publicly published bolthub.ai package: the npm @bolthub/* scope and the bolthub / bolthub-verify PyPI packages.
bolthub is a payment layer for agent-to-tool commerce: charge agents for your MCP tools and APIs per call, settling straight to your wallet over Lightning (L402), with bolthub never in the funds path. These packages are the open-source side of that: the tool-payment SDK, payment clients, MCP servers, a CLI, and origin-verification middleware.
Package | Registry | Directory | What it is |
npm |
| The payments SDK, both sides: price an MCP tool or HTTP endpoint ( | |
npm |
| The bolthub MCP server: marketplace + specific gateways + your other MCP servers behind one config entry, with one shared Lightning budget | |
npm |
| Terminal client for the marketplace | |
npm |
| Gateway signature verification middleware (Express/Fastify/Node) | |
PyPI |
| The payments SDK in Python: L402 client + wallets, and the seller-side paywall | |
PyPI |
| Python gateway signature verification (Flask/Django/FastAPI) |
packages/shared is internal (never published); it is here because @bolthub/mcp bundles it.
Consolidation (2026-07):
@bolthub/agentmerged into@bolthub/pay(≥0.4.0);@bolthub/mcp-registryand@bolthub/mcp-bridgemerged into@bolthub/mcp. The old names are deprecated on npm and point here.
The bolthub platform (gateway, API, web app) lives in a private monorepo. The SDK packages above are developed there and synced to this repository, which is the publish origin: releases are tagged here and built + published by CI with npm provenance, so what's on npm is verifiably built from this public source.
Issues and PRs are welcome here, but note that this repo is a generated mirror: PRs are never merged directly. Accepted changes are applied to the monorepo first (with attribution), then sync back out with the next release. See CONTRIBUTING.md before opening a PR.
Related MCP server: 402-mcp
Published dist/ bundles are built with Bun from this source and ship source maps with embedded sources, so the tarball itself is readable.
# provenance: confirm the tarball was built from this repo by GitHub Actions
npm audit signatures
# or rebuild and compare yourself
git clone https://github.com/signaltech-org/bolthub-sdk
cd bolthub-sdk && bun install
cd packages/mcp && bun run buildSee SECURITY.md for the trust model (what touches your wallet credentials and what doesn't) and how to report vulnerabilities.
bun install
bun testEach TypeScript package builds with bun run build from its directory (@bolthub/pay must be built before the packages that bundle it).
MIT
Audit a bolthub listing you own against the seller-guide rubric and get a prioritized punch list (HIGH/MED/LOW findings with evidence and a fix pointer). Checks origin protection (is the paywall bypassable? is bolthub's signed traffic being rejected?), honest status codes, docs/examples quality, public schema visibility, uptime and p95 latency, pricing-model fit, samples, and free-try. Read-only — changes nothing. Useful before publish_listing and any time revenue looks off. Requires BOLTHUB_ACCOUNT_TOKEN.
Inputs: tenant_id, endpoint_id.
Buy prepaid CREDIT for a bolthub provider: pay ONCE for a sats budget spendable across ALL of that provider's endpoints, then call_api to any of them draws the credit with no further Lightning payment until it runs out. Use this when you'll call SEVERAL of one provider's endpoints — sum their costs and buy that much credit in one payment. Credit is face-value (the provider charges exactly the sats you ask for, no discount tiers) and per-provider: it never covers a different provider (you'd buy separate credit for each). Unused credit at expiry is non-refundable, so size it to what you expect to spend.
Inputs: path (required), slug (required), credit_sats (required), max_cost_sats.
Call an API endpoint on the bolthub marketplace. Handles L402 Lightning payments automatically. Use get_api_details or preview_cost first to check pricing. Returns the response along with cost and budget information.
Inputs: path (required), slug (required), body, method, +3 more.
One-click connect this MCP server to the user's bolthub account. Starts a browser pairing: returns an approval link and a short confirmation code — show BOTH to the user and tell them to check the codes match before approving. After they approve, call connect_status to finish. The minted account token is stored locally and never appears in chat. Use when a seller tool reports no account token.
Inputs: label.
Finish or check the account pairing started by connect_account. Call it after the user says they approved in the browser. On success the account token is stored locally (never shown in chat) and the seller tools start working.
Inputs: no named parameters.
Check or set up the payout wallet for a workspace. A deployed bolthub node can be bound directly (pass node_id — the credential copy is server-side, nothing secret enters chat). Other wallets connect in the browser: the tool returns the dashboard link plus guidance for self-hosted LND (invoice-only macaroon) and always-on NWC services; the chat only ever sees connected yes/no and reachability. Re-run after the user connects to confirm. Non-custodial: sats settle directly to the user's wallet.
Inputs: node_id, tenant_id.
Create a new bolthub workspace (tenant) for selling APIs. Secret-free and reversible: an empty workspace costs nothing and the 30-day trial only starts when a first endpoint is published. Wallet connection is a separate step (connect_wallet). Requires an account token (connect_account).
Inputs: name (required), slug, tags, description.
Deploy a Lightning node (LND + Neutrino) on the user's own VPS — fully non-custodial. GUIDED FLOW, call it repeatedly as the conversation progresses: (1) no arguments → provider menu with prices; (2) provider chosen but no credential stored → sign-up + access-token steps for that provider (the token itself is entered at bolthub.ai/nodes/deploy in the browser, never in chat); (3) credential present → region menu; (4) region → server sizes with monthly prices; (5) region + size (or size 'recommended') → deploys and returns the node id. The user then creates the wallet + seed phrase on their own node page; bind it as the payout wallet afterwards with connect_wallet.
Inputs: tor, size, region, api_key, +2 more.
Get full details for a specific API including all endpoints, pricing, example requests/responses, and usage instructions. Use the slug from search_apis results.
Inputs: slug (required).
Revenue report for a bolthub workspace you own: all-time and windowed earnings in sats, recent paid days, and top-earning endpoints. Read-only. Requires BOLTHUB_ACCOUNT_TOKEN.
Inputs: days, tenant_id.
One-look onboarding checklist for a workspace: wallet connected, endpoints drafted/published, origin-protection verdict (live probe), listing live, trial state — plus the single next step. Use it to drive the seller onboarding conversation. Read-only.
Inputs: tenant_id.
Turn an API spec into a DRAFT bolthub listing: parses OpenAPI/Swagger or Postman (JSON or YAML), creates the endpoints as unlisted drafts (never visible in the directory), and applies a default per-request price you can refine. Publishing is a separate explicit step — use publish_listing. Requires BOLTHUB_ACCOUNT_TOKEN (your bolthub account, dashboard → MCP setup). Re-importing a spec for an origin that already has endpoints shows a dry-run diff instead of duplicating anything.
Inputs: spec_url, tenant_id, apply_sync, origin_url, +2 more.
Mint a scoped, capped child credential from a multi-use credential you already hold for an endpoint, to hand to a sub-agent. Attenuates OFFLINE (no payment, no round-trip): the child is a normal L402 token the worker spends with call_api or a plain client, and the gateway enforces every cap. Attenuation is tighten-only — a child can never widen scope or exceed the parent's remaining uses/sats. Give at least one restriction. Requires a held multi-use credential for this endpoint (a single-use payment has nothing to delegate). Revoke the whole tree with revoke_token.
Inputs: path (required), slug (required), expiry, n_uses, +2 more.
Check the status of a deployed Lightning node. Returns current state, IP address, sync progress, and setup instructions when applicable. Pass wait_for to BLOCK until a milestone is reached (for driving deploy → wallet → bind without babysitting): the call polls server-side state and returns as soon as the condition holds, errors loudly on timeout or a terminal state, and stops immediately when only user action can progress things (wallet creation is a browser step). Never wrap this tool in your own polling loop — use wait_for.
Inputs: node_id (required), wait_for, timeout_s.
Preview the cost of calling an API endpoint without making the actual request or paying. Use this to check pricing before committing to a call.
Inputs: slug (required), path, method.
Take a workspace's draft endpoints live in the bolthub directory. Without confirm:true it is a DRY RUN that shows exactly what would go live (endpoints, prices, workspace activation) — show that to the user and get their go-ahead before re-calling with confirm:true. Publishing the first endpoint starts the workspace's 30-day free trial. Requires BOLTHUB_ACCOUNT_TOKEN.
Inputs: confirm, tenant_id, endpoint_ids.
Revoke the grant behind a prepaid bundle this session bought, killing the whole delegation tree minted from it (every scoped child made with mint_scoped_token). Takes effect on the next request within ~15s, returning token_revoked. Use it to cut off a sub-agent (or all of them) after handing out children. Optionally pass released_sats to return child-cap budget you reserved back to your budget.
Inputs: path (required), slug (required), released_sats.
Search the bolthub API marketplace. Returns a list of available APIs with names, descriptions, tags, endpoint counts, and pricing. Use this to discover APIs that match your needs. Call without arguments to list all available APIs.
Inputs: tag, query.
Operational usage for a bolthub workspace you own: billing status and projected platform fee for the current cycle, paid traffic by endpoint, and SDK-tool (facilitator) usage. Pass endpoint_id for one endpoint's latency/error detail. Read-only. Requires BOLTHUB_ACCOUNT_TOKEN.
Inputs: days, tenant_id, endpoint_id.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 19 tools
The tools map to clear buyer/seller workflows and mostly do not overlap. The one potential trap is list_api sounding like a directory-listing operation alongside search_apis, but its description makes the draft-listing intent clear.
Most tools follow a verb_noun pattern such as search_apis, call_api, create_workspace, and publish_listing. Deviations like node_status and usage_summary omit a verb, and list_api uses singular where search_apis uses plural, but the overall style remains readable and predictable.
At 19 tools, the set sits in the heavy range and adds selection overhead for agents, though the buyer/seller split keeps tools purposeful. It is above the ideal well-scoped size but not bloated enough to be a major problem.
Core buyer and seller journeys are covered: discovery, pricing, calling, prepayment, delegation, onboarding, publishing, analysis, and reporting. However, there is no unpublish/delete for listings, no way to remove a workspace, and no explicit buyer balance query, leaving lifecycle dead ends.
Pay-per-action access to APIs and MCP tools over Lightning L402 and Base USDC x402.
15 pay-per-call Bitcoin and developer tools, paid in sats over Lightning (L402).
Pay-per-use tool marketplace for AI agents. Search, price-check, and call APIs via MCP.
Bitcoin intelligence API. Pay per call via L402 Lightning (10-200 sats). No accounts needed.
