@b4bit/b4bit-pay-mcp

MCP server for B4bit Pay. Use from any MCP-compatible client (Claude Desktop, Claude Code, Cursor, VS Code MCP extension) to probe the API, verify webhook signatures, and work with B4bit Pay data without writing HTTP code.

Install

Two ways:

1. Via npx (recommended for end users)

No install step. Just add this to your MCP client config:

{
  "mcpServers": {
    "b4bit-pay": {
      "command": "npx",
      "args": ["-y", "@b4bit/b4bit-pay-mcp"],
      "env": {
        "B4BIT_API_KEY": "<your-device-api-key>"
      }
    }
  }
}

2. Local install

pnpm add -D @b4bit/b4bit-pay-mcp

Then point the client to node_modules/.bin/b4bit-pay-mcp.

Configuration

| Env var | Required | Default | Purpose | |---------|:-:|---------|---------| | B4BIT_API_KEY | ✓ | — | Device API Key (UUID) from pay.b4bit.com/settings/commerce/devices | | B4BIT_BASE_URL | — | https://pos.b4bit.com/api/v1 | Override for staging/local testing |

Tools

Generic

| Tool | Purpose | |------|---------| | probe_endpoint | Arbitrary HTTP against pos.b4bit.com/api/v1/*. Supports dry_run. | | verify_webhook | Validate HMAC-SHA256 of a webhook. Returns diagnostics when invalid. | | list_endpoints | Catalog of the 5 public endpoints. |

Typed (less error-prone for agents)

| Tool | Endpoint | Notes | |------|----------|-------| | list_currencies | GET /currencies | Authoritative source for symbols. | | create_order | POST /orders/ | JSON body. All optional fields. | | get_order | GET /orders/info/{id} | Returns array of 1. | | list_orders | GET /orders/ | Default last 7 days. | | create_device | POST /device/ | Destructive — requires confirm_creation: true. | | map_status | — | Maps NR|PE|AC|IA|CO|CA|EX|OC|FA|DE|CM + safe → merchant state. |

Webhook HMAC test vector

verify_webhook self-validates on the official vector:

• secret_hex: 02d4b921007cad413e79731dd02b3267cd43a14d150a0ae6a1c651942122bb62
• nonce: 1645634942
• body: {"fiat_amount": 100.0, "fiat_currency": "USD", "status": "AC", "crypto_amount": 1.21461894, "unconfirmed_amount": 8.0, "confirmed_amount": 0.0, "currency": "DASH", "identifier": "1040095a-737d-41a2-a2e1-d031d19ec8cd"}
• Expected signature: 395a6c0294f0896fcc0e5827e926e12308f4fdca5c18da69d3af6879e5c80e2d

When invalid, the tool returns actionable diagnostics (wrong secret encoding, trimmed body, reversed concatenation, etc.).

Dev

pnpm install
pnpm dev        # tsx watch
pnpm build      # tsc -> dist/
pnpm start      # node dist/index.js
pnpm test       # vitest

Docs

Full documentation for the API: https://docs.b4bit.com/pay/api/.

License

MIT — see LICENSE.