BitBooth Seller Routes

本地服务

app.heinrichstech.com金融数据06 周前更新

代码仓库访问官网

关于 BitBooth Seller Routes

BitBooth Seller Routes 是供卖家通过 MCP 客户端管理私有 x402 路由的服务，可创建、配置、预览和维护收款路由，并将款项发往指定钱包。

主要功能

01创建、列出、更新和删除路由
02预览 x402 资源 URL 与支付信息
03设置价格、请求方法和运行模式
04配置上游地址与认证信息
05支持多个网络的收款设置

适用场景

01从 Claude 或 Cursor 管理卖家路由
02向买家分享可调用的付费资源 URL
03为上游服务配置认证并转发请求

MCP 相关

该 MCP 服务向客户端提供路由创建、查询、更新、删除和预览工具。它通过已认证的 BitBooth `/v1/routes` API 管理私有卖家路由。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "drock91-bitbooth-routes": {
      "command": "npx",
      "args": [
        "-y",
        "@bitbooth/mcp-routes"
      ],
      "env": {
        "BITBOOTH_API_KEY": "<BITBOOTH_API_KEY>",
        "BITBOOTH_BASE_URL": "<BITBOOTH_BASE_URL>"
      }
    }
  }
}

启动命令npx -y @bitbooth/mcp-routes

需要配置的环境变量

BITBOOTH_API_KEY密钥Your BitBooth tenant API key (prefixed x402_). Get one at https://app.heinrichstech.com/portal — Sign in → key shown on dashboard.

BITBOOTH_BASE_URLBitBooth gateway URL. Defaults to https://app.heinrichstech.com.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@bitbooth/mcp-routes1.1.1stdio

工具

收录的工具列表 · 更新于 3 周前

此工具无需参数。

详细介绍

@bitbooth/mcp-routes

通过 Claude、Codex、Cursor 或其他 MCP 客户端管理你的私人 BitBooth x402 卖家路由。此服务通过 BitBooth 经过身份验证的 /v1/routes API 提供创建、列出、更新、删除和预览路由的工具。

租户路由不会公开列出。本软件包不会将它们发布到 BitBooth 的公共目录中。运行 preview_route，并将其准确的 resource.url 分享给买家，或在你自己的 Agent 集成中调用它。

每次创建、更新和删除调用都会自动携带一个新的 UUIDv4 Idempotency-Key。BitBooth 会将该键限定在经过身份验证的卖家范围内，只存储请求哈希，重放完全相同的已完成变更，并在触及 DynamoDB 或 Secrets Manager 之前拒绝重复使用但内容已更改的键。

安装

在 app.heinrichstech.com/portal 登录以获取租户 API 密钥。将其保存在 MCP 客户端的环境中；不要放入提示词或源代码管理中。

Claude Desktop、Cursor、Windsurf 或 Continue

{
  "mcpServers": {
    "bitbooth-routes": {
      "command": "npx",
      "args": ["-y", "@bitbooth/[email protected]"],
      "env": {
        "BITBOOTH_API_KEY": "x402_<your-tenant-api-key>"
      }
    }
  }
}

Claude Code

claude mcp add bitbooth-routes --env BITBOOTH_API_KEY=x402_<your-tenant-api-key> -- npx -y @bitbooth/[email protected]

全局安装

npm install -g @bitbooth/[email protected]
export BITBOOTH_API_KEY="x402_<your-tenant-api-key>"
mcp-routes

工具

工具	作用
`list_routes`	列出经过身份验证的卖家的路由和已保存的收款配置
`create_route`	创建或替换绑定到方法的 x402 路由
`update_route`	按路径幂等地创建或更新路由
`delete_route`	按路径删除路由
`preview_route`	返回准确的 x402 v2 `resource.url` 和 `accepts[]`，且不收费

请求示例：

“在 /api/forecast 创建一个 POST 路由，测试模式下收费 0.01 USDC，款项支付到我的 Base Sepolia 钱包。”
“将 /api/forecast 改为 GET，并在 Base 主网上启用。”
“预览 /api/forecast，并提供其可供 Agent 调用的 URL 和链上金额。”

路由约定

价格使用 API 的旧字段名 priceWei，但其值必须是严格为正的字符串，表示六位小数 USDC 的最小单位。例如，"10000" 表示 0.01 USDC。

{
  "path": "/api/forecast",
  "method": "POST",
  "priceWei": "10000",
  "asset": "USDC",
  "mode": "live",
  "tenantPayTo": {
    "eip155:8453": "0x1234567890123456789012345678901234567890"
  },
  "upstreamUrl": "https://api.example.com/forecast",
  "upstreamAuth": {
    "type": "bearer",
    "value": "your-write-only-upstream-token"
  }
}

method 为 GET、POST、PUT、PATCH、DELETE 或 HEAD 之一；默认为 POST。BitBooth 发起或结算付款前，会拒绝不同的请求方法。
path 必须以 / 开头，至少包含一个非空路径段，且不得包含查询参数、片段、空路径段或 ./.. 路径段。
mode 默认为 test。测试路由只公布 Base Sepolia；线上路由会公布符合条件的主网支付通道。
tenantPayTo 仅接受以下确切的网络标识符。缺少某个网络时，该网络会从 accepts[] 中省略；不会回退到 BitBooth 钱包。
upstreamUrl 必须是公共 URL。线上路由以及任何使用上游身份验证的路由都要求使用 HTTPS；只有未经过身份验证的测试模式路由才接受普通 HTTP。更新时省略此项可保留已保存的上游配置；发送 null 则会断开连接。
upstreamAuth 仅用于写入。更新时省略此项可保留凭据，发送替代值可轮换凭据，发送 null 则会清除凭据。路由响应仅公开 upstreamAuthConfigured。

上游安全认证

BitBooth 可以使用 Bearer 令牌或安全的自定义标头，对发往上游的付费请求进行认证：

{
  "upstreamAuth": {
    "type": "bearer",
    "value": "private-token"
  }
}

{
  "upstreamAuth": {
    "type": "header",
    "headerName": "x-upstream-token",
    "value": "private-value"
  }
}

创建时，如果配置了认证，则必须提供 value 和 upstreamUrl。更新时：

省略 upstreamAuth，以保留当前配置。
发送 { "type": "bearer" } 或 { "type": "header", "headerName": "x-new-name" }，且不包含 value，即可在更改凭证注入方式的同时复用现有凭证。
包含 value，即可设置或替换凭证。
发送 null，即可清除凭证。
更改上游源站时，必须提供替换凭证或明确清除认证。断开上游连接也会清除其凭证。

自定义标头名称会被规范化为小写。BitBooth 会拒绝传输、支付、Cookie、追踪、AWS/CloudFront、代理、浏览器安全相关标头，以及 Authorization 和 X-API-Key 标头。凭证值不能为空、不能带有首尾空格、不能包含控制字符，且长度不得超过 8,192 个字符。Bearer 令牌必须使用与 RFC 6750 兼容的令牌字符集。

凭证值只会通过经过认证的管理写入请求发送，存储在 AWS Secrets Manager 中，且绝不会通过列表/创建/更新/预览工具返回，也不会包含在对外显示的错误中。路由响应只会报告 "upstreamAuthConfigured": true 或 false。

支持的付款网络

模式	网络	资产和要求
`test`	`eip155:84532`	Base Sepolia USDC；需要 EVM 付款地址
`live`	`eip155:8453`	Base 主网 USDC；需要 EVM 付款地址
`live`	`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`	Solana 主网 USDC；需要有效的 Solana 公钥和网关费用支付方配置
`live`	`xrpl:0`	XRPL 主网 USDC；需要准确的付款地址，并明确确认信任固定发行方的信任线；是否可用仍取决于部署配置
`live`	`stellar:pubnet`	Stellar 公共网络 USDC；需要准确的付款地址，并明确确认信任固定发行方的信任线

XRPL 和 Stellar 的启用选项必须严格采用以下格式。其他发行方、资产和网络均会被拒绝。

{
  "tenantPayTo": {
    "xrpl:0": "rfryheo6yzFdLWj8qUQtZc7zG9MKkBkUEy",
    "stellar:pubnet": "GDIK4RML4K63ZI3SYGJD5TL4ILEAZT3LBY7MXJJP5YSSZ5O4DTHDOIA3"
  },
  "tenantStablecoinRails": {
    "xrpl:0": {
      "asset": "USDC",
      "issuer": "rGm7WCVp9gb4jZHWTEtGUr4dd74z2XuWhE",
      "trustlineConfirmed": true
    },
    "stellar:pubnet": {
      "asset": "USDC",
      "issuer": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
      "trustlineConfirmed": true
    }
  }
}

预览响应采用 x402 v2。可从 resource.url 获取可调用 URL，并从每个 accepts[].amount 获取各支付轨道对应的线上金额；不同支付轨道的线上单位可能不同。

配置

环境变量	描述	默认值
`BITBOOTH_API_KEY`	租户管理 API 密钥（`x402_…`），必填	—
`BITBOOTH_BASE_URL`	BitBooth 网关 URL	`https://app.heinrichstech.com`

程序化使用

import { createApiClient } from '@bitbooth/mcp-routes/api-client';

const api = createApiClient({ apiKey: process.env.BITBOOTH_API_KEY });
const { routes } = await api.listRoutes();
const challenge = await api.previewRoute(routes[0].path);
console.log(challenge.resource.url, challenge.accepts);

客户端会在返回 BitBooth 响应前进行校验，并从对外显示的传输错误和 API 错误中脱敏管理 API 密钥。