{"_id":"@bitbooth/mcp-routes","_rev":"2-8ff1603f46745663e7e324698d9d2f6d","name":"@bitbooth/mcp-routes","dist-tags":{"latest":"1.1.1"},"versions":{"1.1.0":{"name":"@bitbooth/mcp-routes","version":"1.1.0","keywords":["mcp","mcp-server","model-context-protocol","x402","x402-protocol","agent-payments","bitbooth","api-management","upstream-authentication","monetize-api","paywall","claude","claude-code","anthropic","multi-chain","base","xrpl","solana","stellar","usdc"],"author":{"name":"Derek Heinrichs"},"license":"MIT","_id":"@bitbooth/mcp-routes@1.1.0","maintainers":[{"name":"whatsrdoing","email":"heinrichssoftwaresolutions@gmail.com"}],"homepage":"https://app.heinrichstech.com","bugs":{"url":"https://github.com/Drock91/bitbooth-docs/issues"},"bin":{"mcp-routes":"bin/mcp-routes.js"},"dist":{"shasum":"eb3d1fb87b9f7e41d178bd500c5d99de4e1c61ea","tarball":"https://registry.npmjs.org/@bitbooth/mcp-routes/-/mcp-routes-1.1.0.tgz","fileCount":9,"integrity":"sha512-DZZ8DdgDhrUcl8tJTeGFmpRg9acqN5BtI8Zg/dRfQ+D0jWI1KUamTxmdwPVI007eIrOgiPcsbP63lXuSZG+ULQ==","signatures":[{"sig":"MEQCIH1ymPiauUDmGWcRVhCUvbz5L4g7Ug5IPc7CDaF8hEHrAiACvA6LFstjQFcqlyvSoFzc97Lzv6Y12lepe0HF3s6fOg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":44830},"main":"./src/index.js","type":"module","engines":{"node":">=20.19.0"},"exports":{".":"./src/index.js","./server":"./src/server.js","./api-client":"./src/api-client.js"},"gitHead":"aaec17cc0f78a3931e548dcbdc49941c88656056","mcpName":"io.github.drock91/bitbooth-routes","scripts":{"test":"vitest run","test:watch":"vitest"},"_npmUser":{"name":"whatsrdoing","email":"heinrichssoftwaresolutions@gmail.com"},"repository":{"url":"git+https://github.com/Drock91/bitbooth-docs.git","type":"git","directory":"packages/mcp-routes"},"_npmVersion":"10.9.2","description":"Manage private BitBooth x402 seller routes, non-custodial payouts, and write-only upstream authentication from any MCP client.","directories":{},"_nodeVersion":"22.14.0","dependencies":{"zod":"^3.25.0","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.1.11"},"_npmOperationalInternal":{"tmp":"tmp/mcp-routes_1.1.0_1789070154402_0.9181295424688327","host":"s3://npm-registry-packages-npm-production"}},"1.1.1":{"name":"@bitbooth/mcp-routes","version":"1.1.1","mcpName":"io.github.Drock91/bitbooth-routes","description":"Manage private BitBooth x402 seller routes, non-custodial payouts, and write-only upstream authentication from any MCP client.","type":"module","license":"MIT","author":{"name":"Derek Heinrichs"},"repository":{"type":"git","url":"git+https://github.com/Drock91/bitbooth-docs.git","directory":"packages/mcp-routes"},"homepage":"https://app.heinrichstech.com","bugs":{"url":"https://github.com/Drock91/bitbooth-docs/issues"},"publishConfig":{"access":"public"},"bin":{"mcp-routes":"bin/mcp-routes.js"},"main":"./src/index.js","exports":{".":"./src/index.js","./server":"./src/server.js","./api-client":"./src/api-client.js"},"keywords":["mcp","mcp-server","model-context-protocol","x402","x402-protocol","agent-payments","bitbooth","api-management","upstream-authentication","monetize-api","paywall","claude","claude-code","anthropic","multi-chain","base","xrpl","solana","stellar","usdc"],"engines":{"node":">=20.19.0"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","zod":"^3.25.0"},"devDependencies":{"vitest":"^4.1.11"},"scripts":{"test":"vitest run","test:watch":"vitest"},"_id":"@bitbooth/mcp-routes@1.1.1","gitHead":"aaec17cc0f78a3931e548dcbdc49941c88656056","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-iQB4vPAhM6XJvlNAjI8vNKjOCvJwk4AKSOG87w8TAOr1colrRoyR3puL0SXFpHRbu+TZ2zhGfjkFbtdso7IU+A==","shasum":"2fc4ab3bbd161ee1f6b68f36139ac9ed958dfbe1","tarball":"https://registry.npmjs.org/@bitbooth/mcp-routes/-/mcp-routes-1.1.1.tgz","fileCount":9,"unpackedSize":44830,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHkuREYrc8y07a+AkJ91OAHzuulP3uAcArXqoFBu47fDAiBC+D7ak1a6vnGYYC/BoDBnKfhishU7qmWrsVDlrB+akA=="}]},"_npmUser":{"name":"whatsrdoing","email":"heinrichssoftwaresolutions@gmail.com"},"directories":{},"maintainers":[{"name":"whatsrdoing","email":"heinrichssoftwaresolutions@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-routes_1.1.1_1789076563205_0.9029730514105399"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-10T19:55:54.111Z","modified":"2026-09-10T21:42:43.526Z","1.1.0":"2026-09-10T19:55:54.588Z","1.1.1":"2026-09-10T21:42:43.348Z"},"bugs":{"url":"https://github.com/Drock91/bitbooth-docs/issues"},"author":{"name":"Derek Heinrichs"},"license":"MIT","homepage":"https://app.heinrichstech.com","keywords":["mcp","mcp-server","model-context-protocol","x402","x402-protocol","agent-payments","bitbooth","api-management","upstream-authentication","monetize-api","paywall","claude","claude-code","anthropic","multi-chain","base","xrpl","solana","stellar","usdc"],"repository":{"type":"git","url":"git+https://github.com/Drock91/bitbooth-docs.git","directory":"packages/mcp-routes"},"description":"Manage private BitBooth x402 seller routes, non-custodial payouts, and write-only upstream authentication from any MCP client.","maintainers":[{"name":"whatsrdoing","email":"heinrichssoftwaresolutions@gmail.com"}],"readme":"# @bitbooth/mcp-routes\n\n[![npm version](https://img.shields.io/npm/v/@bitbooth/mcp-routes.svg)](https://www.npmjs.com/package/@bitbooth/mcp-routes)\n[![MIT license](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n\nManage your private BitBooth x402 seller routes from Claude, Codex, Cursor, or any other MCP client. The server exposes tools to create, list, update, delete, and preview routes through BitBooth's authenticated `/v1/routes` API.\n\nTenant routes are intentionally unlisted. This package does not publish them into BitBooth's public catalog. Run `preview_route` and share its exact `resource.url` with buyers or invoke it from your own agent integration.\n\nEvery create, update, and delete call automatically carries a fresh UUIDv4 `Idempotency-Key`. BitBooth scopes that key to the authenticated seller, stores only request hashes, replays an exact completed mutation, and rejects changed reuse before touching DynamoDB or Secrets Manager.\n\n## Install\n\nGet a tenant API key by signing in at [app.heinrichstech.com/portal](https://app.heinrichstech.com/portal). Keep it in your MCP client's environment; do not put it in prompts or source control.\n\n### Claude Desktop, Cursor, Windsurf, or Continue\n\n```json\n{\n  \"mcpServers\": {\n    \"bitbooth-routes\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@bitbooth/mcp-routes@^1.1.0\"],\n      \"env\": {\n        \"BITBOOTH_API_KEY\": \"x402_<your-tenant-api-key>\"\n      }\n    }\n  }\n}\n```\n\n### Claude Code\n\n```bash\nclaude mcp add bitbooth-routes --env BITBOOTH_API_KEY=x402_<your-tenant-api-key> -- npx -y @bitbooth/mcp-routes@^1.1.0\n```\n\n### Global install\n\n```bash\nnpm install -g @bitbooth/mcp-routes@^1.1.0\nexport BITBOOTH_API_KEY=\"x402_<your-tenant-api-key>\"\nmcp-routes\n```\n\n## Tools\n\n| Tool            | Effect                                                                   |\n| --------------- | ------------------------------------------------------------------------ |\n| `list_routes`   | List the authenticated seller's routes and saved payout configuration    |\n| `create_route`  | Create or replace a method-bound x402 route                              |\n| `update_route`  | Idempotently upsert a route by path                                      |\n| `delete_route`  | Delete a route by path                                                   |\n| `preview_route` | Return the exact x402 v2 `resource.url` and `accepts[]` without charging |\n\nExample requests:\n\n- \"Create a POST route at `/api/forecast` for 0.01 USDC in test mode, paid to my Base Sepolia wallet.\"\n- \"Change `/api/forecast` to GET and make it live on Base mainnet.\"\n- \"Preview `/api/forecast` and give me its agent-callable URL and wire amounts.\"\n\n## Route contract\n\nPrices use the API's legacy `priceWei` field name, but the value is a strictly positive string of six-decimal USDC atomic units. For example, `\"10000\"` means `0.01 USDC`.\n\n```json\n{\n  \"path\": \"/api/forecast\",\n  \"method\": \"POST\",\n  \"priceWei\": \"10000\",\n  \"asset\": \"USDC\",\n  \"mode\": \"live\",\n  \"tenantPayTo\": {\n    \"eip155:8453\": \"0x1234567890123456789012345678901234567890\"\n  },\n  \"upstreamUrl\": \"https://api.example.com/forecast\",\n  \"upstreamAuth\": {\n    \"type\": \"bearer\",\n    \"value\": \"your-write-only-upstream-token\"\n  }\n}\n```\n\n- `method` is one of `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, or `HEAD`; it defaults to `POST`. A different request method is rejected before BitBooth issues or settles payment.\n- `path` must start with `/`, contain at least one non-empty segment, and contain no query, fragment, empty segment, or `.`/`..` segment.\n- `mode` defaults to `test`. Test routes advertise only Base Sepolia; live routes advertise eligible mainnet rails.\n- `tenantPayTo` accepts only the exact network identifiers below. A missing network is omitted from `accepts[]`; it never falls back to a BitBooth wallet.\n- `upstreamUrl` must be a public URL. Live routes and every route that uses upstream authentication require HTTPS; plain HTTP is accepted only for unauthenticated test-mode routes. Omit it on update to preserve the saved upstream, or send `null` to disconnect it.\n- `upstreamAuth` is write-only. Omit it on update to preserve the credential, send a replacement to rotate it, or send `null` to clear it. Route responses expose only `upstreamAuthConfigured`.\n\n## Secure upstream authentication\n\nBitBooth can authenticate paid deliveries to an upstream with either a bearer token or a safe custom header:\n\n```json\n{\n  \"upstreamAuth\": {\n    \"type\": \"bearer\",\n    \"value\": \"private-token\"\n  }\n}\n```\n\n```json\n{\n  \"upstreamAuth\": {\n    \"type\": \"header\",\n    \"headerName\": \"x-upstream-token\",\n    \"value\": \"private-value\"\n  }\n}\n```\n\nOn create, `value` and `upstreamUrl` are required when authentication is configured. On update:\n\n- Omit `upstreamAuth` to preserve the current configuration.\n- Send `{ \"type\": \"bearer\" }` or `{ \"type\": \"header\", \"headerName\": \"x-new-name\" }` without `value` to reuse an existing credential while changing how it is injected.\n- Include `value` to set or replace the credential.\n- Send `null` to clear the credential.\n- Changing the upstream origin requires a replacement credential or an explicit auth clear. Disconnecting the upstream also clears its credential.\n\nCustom header names are normalized to lowercase. BitBooth rejects transport, payment, cookie, tracing, AWS/CloudFront, proxy, browser-security, `Authorization`, and `X-API-Key` headers. Credential values cannot be empty, padded with whitespace, contain control characters, or exceed 8,192 characters. Bearer tokens use the RFC 6750-compatible token character set.\n\nCredential values are sent only in the authenticated management write, stored in AWS Secrets Manager, and never returned by list/create/update/preview tools or included in surfaced errors. A route response reports only `\"upstreamAuthConfigured\": true` or `false`.\n\n## Supported payout networks\n\n| Mode   | Network                                   | Asset and requirements                                                                                                                        |\n| ------ | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |\n| `test` | `eip155:84532`                            | Base Sepolia USDC; requires an EVM payout address                                                                                             |\n| `live` | `eip155:8453`                             | Base mainnet USDC; requires an EVM payout address                                                                                             |\n| `live` | `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` | Solana mainnet USDC; requires a valid Solana public key and gateway fee-payer configuration                                                   |\n| `live` | `xrpl:0`                                  | XRPL mainnet USDC; requires the exact payout address and explicit pinned-issuer trustline confirmation; availability remains deployment-gated |\n| `live` | `stellar:pubnet`                          | Stellar pubnet USDC; requires the exact payout address and explicit pinned-issuer trustline confirmation                                      |\n\nXRPL and Stellar opt-ins use this exact shape. Other issuers, assets, and networks are rejected.\n\n```json\n{\n  \"tenantPayTo\": {\n    \"xrpl:0\": \"rfryheo6yzFdLWj8qUQtZc7zG9MKkBkUEy\",\n    \"stellar:pubnet\": \"GDIK4RML4K63ZI3SYGJD5TL4ILEAZT3LBY7MXJJP5YSSZ5O4DTHDOIA3\"\n  },\n  \"tenantStablecoinRails\": {\n    \"xrpl:0\": {\n      \"asset\": \"USDC\",\n      \"issuer\": \"rGm7WCVp9gb4jZHWTEtGUr4dd74z2XuWhE\",\n      \"trustlineConfirmed\": true\n    },\n    \"stellar:pubnet\": {\n      \"asset\": \"USDC\",\n      \"issuer\": \"GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN\",\n      \"trustlineConfirmed\": true\n    }\n  }\n}\n```\n\nThe preview response is x402 v2. Read the callable URL from `resource.url` and the per-rail wire amount from each `accepts[].amount`; wire units can differ by rail.\n\n## Configuration\n\n| Environment variable | Description                                    | Default                         |\n| -------------------- | ---------------------------------------------- | ------------------------------- |\n| `BITBOOTH_API_KEY`   | Tenant management API key (`x402_…`), required | —                               |\n| `BITBOOTH_BASE_URL`  | BitBooth gateway URL                           | `https://app.heinrichstech.com` |\n\n## Programmatic use\n\n```js\nimport { createApiClient } from '@bitbooth/mcp-routes/api-client';\n\nconst api = createApiClient({ apiKey: process.env.BITBOOTH_API_KEY });\nconst { routes } = await api.listRoutes();\nconst challenge = await api.previewRoute(routes[0].path);\nconsole.log(challenge.resource.url, challenge.accepts);\n```\n\nThe client validates BitBooth responses before returning them and redacts the management API key from surfaced transport and API errors.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}