BitBooth Seller Routes

@bitbooth/mcp-routes

Claude、Codex、Cursor、その他の MCP クライアントから、BitBooth のプライベートな x402 セラールートを管理します。このサーバーは、BitBooth の認証済み /v1/routes API を通じて、ルートの作成、一覧表示、更新、削除、プレビューを行うツールを公開します。

テナントルートは意図的に非公開です。このパッケージによって、BitBooth の公開カタログに登録されることはありません。preview_route を実行し、正確な resource.url を購入者と共有するか、独自のエージェント統合から呼び出してください。

作成、更新、削除の各呼び出しでは、新しい 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[] を返します

リクエスト例：

• 「テストモードで、Base Sepolia ウォレットを支払い先とする 0.01 USDC の POST ルートを /api/forecast に作成してください。」
• 「/api/forecast を GET に変更し、Base メインネットで有効にしてください。」
• 「/api/forecast をプレビューして、エージェントから呼び出せる URL とワイヤー上の金額を教えてください。」

ルートの仕様

価格には API の従来のフィールド名 priceWei を使用しますが、その値は 6 桁の小数精度を持つ 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 は / で始まり、空でないセグメントを 1 つ以上含む必要があります。また、クエリ、フラグメント、空のセグメント、および .／.. セグメントを含めることはできません。
• mode のデフォルトは test です。テストルートでは Base Sepolia のみが提示され、ライブのルートでは利用可能なメインネットの決済手段が提示されます。
• tenantPayTo には、以下に記載された正確なネットワーク識別子のみを指定できます。ネットワークが指定されていない場合、そのネットワークは accepts[] から省略され、BitBooth のウォレットにフォールバックすることはありません。
• upstreamUrl はパブリック URL である必要があります。ライブのルート、およびアップストリーム認証を使用するすべてのルートでは HTTPS が必須です。認証なしのテストモードのルートに限り、HTTP を使用できます。保存済みのアップストリームを維持するには更新時に省略し、接続を解除するには null を指定してください。
• upstreamAuth は書き込み専用です。更新時に省略すると認証情報が維持され、置き換えを送信するとローテーションされ、null を送信すると消去されます。ルートのレスポンスで公開されるのは upstreamAuthConfigured のみです。

アップストリーム認証の保護

BitBooth は、ベアラートークンまたは安全なカスタムヘッダーを使用して、アップストリームへの有料配信を認証できます。

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

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

作成時に認証を設定する場合は、value と upstreamUrl が必須です。更新時：

• upstreamAuth を省略すると、現在の設定が維持されます。
• value を含めずに { "type": "bearer" } または { "type": "header", "headerName": "x-new-name" } を送信すると、既存の認証情報を再利用しながら、その挿入方法を変更できます。
• 認証情報を設定または置き換えるには、value を含めます。
• 認証情報をクリアするには、null を送信します。
• アップストリームのオリジンを変更するには、認証情報を置き換えるか、認証を明示的にクリアする必要があります。アップストリームを切断すると、その認証情報もクリアされます。

カスタムヘッダー名は小文字に正規化されます。BitBooth は、トランスポート、決済、Cookie、トレーシング、AWS／CloudFront、プロキシ、ブラウザーセキュリティ、Authorization、および X-API-Key のヘッダーを拒否します。認証情報の値は空にできず、前後に空白を含めることも、制御文字を含めることもできません。また、長さは8,192文字以下である必要があります。ベアラートークンには、RFC 6750に準拠したトークン文字セットが使用されます。

認証情報の値は、認証済みの管理用書き込みでのみ送信され、AWS Secrets Manager に保存されます。また、一覧表示／作成／更新／プレビューの各ツールから返されることはなく、表示されるエラーに含まれることもありません。ルートのレスポンスには "upstreamAuthConfigured": true または false のみが含まれます。

対応する支払いネットワーク

モード	ネットワーク	アセットと要件
test	eip155:84532	Base Sepolia USDC。EVM の支払いアドレスが必要です。
live	eip155:8453	Base mainnet USDC。EVM の支払いアドレスが必要です。
live	solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp	Solana mainnet USDC。有効な Solana 公開鍵と、ゲートウェイの手数料支払者設定が必要です。
live	xrpl:0	XRPL mainnet USDC。正確な支払いアドレスと、固定された発行者へのトラストラインを明示的に確認する必要があります。利用可否はデプロイ状況によって異なります。
live	stellar:pubnet	Stellar pubnet 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 です。呼び出し可能な URL は resource.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 キーを秘匿します。

ライセンス

MIT