paybito-mcp 0.1.11

PayBito infrastructure knowledge helper for AI agents — injects PayBito API expertise (Resources + Prompts, no live actions) into any MCP-capable AI platform.

PayBito MCP — AI Integration Knowledge Helper

A knowledge helper that injects PayBito infrastructure expertise into any AI coding agent, so a developer can implement PayBito integrations (websites, exchanges, payment flows, trading apps) in natural language.

It is not an action executor. It never calls PayBito's live API, never moves funds, never reads balances. It serves documentation and code guidance so the AI writes the correct integration code for you — the same way the frontend-design skill makes an AI produce great UIs without "running" anything.

Built from all 6 of PayBito's published OpenAPI specs (1,344 endpoints → 1,058 unique operations across 28 domains and 6 hosts), normalized into one clean model.

What it exposes

Surface	Contents	For
Resources	paybito://overview, paybito://modules, paybito://auth, paybito://domains, paybito://domain/{slug}, paybito://operation/{id}, paybito://playbook/{name}	Clients that read MCP resources (Claude)
Tools (read-only)	paybito_overview, paybito_modules, paybito_search (accepts a module filter), paybito_get_operation, paybito_get_domain, paybito_get_auth, paybito_list_playbooks, paybito_get_playbook	Clients that only invoke tools (ChatGPT, Cursor, Gemini, …). These return documentation only.
Prompts	integrate_paybito, add_payment_button, spot_trading_code	Guided workflows

Product modules (so a prompt hits the right API)

STEP 0 — the AI asks the developer one question first. PayBito serves several audiences with overlapping endpoints, so the most reliable router is the developer's own answer: "What are you building?" —

• (a) an app for the PayBito App Store / dev console → PayBito host;
• (b) crypto payments into your own existing site/product (a merchant) → your own domain;
• (c) your own branded white-label platform — exchange and/or payments (a broker, e.g. trade.coinstrendexchange.com with …/api-documentation/ + …/payments/api-doc/) → your own broker domain;
• (d) a trading / market-data integration only → your platform domain.

The answer sets both the module and the base-URL environment (your own domain vs a PayBito host). The build-your-*-app "App Developer" tiles (Launch / Exchange / Payment platform) are tagged on each operation via app_platforms.

Payments also has a test/live sandbox — so for any payments work the AI also asks "test or live?". Test mode only prepends Test to the service segment (/PaymentsApiKeyService → /TestPaymentsApiKeyService, /Payments-Apikey-V2 → /TestPayments-Apikey-V2); same params, auth, and host. Exchange has no test mode. Each payments operation shows both its Live and Test path.

Every operation is also tagged with a module, and paybito_search takes a module filter to keep results on the right surface:

Module	Use when building…	Base URL	Auth
exchange	spot/futures/options trading, market data, copy-trading, ICO	🏷️ broker's own domain	exchange-base64
payments	merchant invoicing, billing, KYC, transactions, recurring, campaigns, reports	🏷️ broker's own domain	payments-dual
gateway	storefront/checkout — products, catalogs, cart, hosted checkout, payment link/button	🏷️ broker's own domain	payments-dual / payments-pk
platform	launch your own white-label exchange, or build apps across PayBito platforms	institutional-bo.paybito.com:8443	bearer

A merchant/payments app is payments/gateway, never exchange. Call paybito_modules first, then paybito_search(query, module=…).

🏷️ White-label base URL

This MCP is used by each broker's developers, who run on their own domain. For the exchange, payments and gateway modules the base URL is the broker's own platform domain (e.g. https://trade.coinstrendexchange.com or https://exchange.axada.co) — the developer supplies it, the AI only fills in the endpoint path. Generated code reads a BASE_URL config/env var; it never hardcodes a PayBito host. Only the platform module (apps built on PayBito infrastructure) targets a fixed PayBito host.

Install

pip install -e .          # or: pipx install .   /   uvx --from . paybito-mcp
paybito-build             # generate build/model.json + build/corpus from specs/

paybito-mcp then runs the server over stdio.

Inject it into your AI (one-time setup per tool)

There are two delivery modes. Use the MCP server for agentic/coding tools, and the portable bundle for web chat UIs.

Mode A — MCP server (agentic & coding tools)

The command is paybito-mcp (after pip install), or npx -y paybito-mcp once published (see typescript/).

Claude Code

claude mcp add paybito -- paybito-mcp          # then: /mcp to verify it's connected

Claude Desktop — edit claude_desktop_config.json (Windows: %APPDATA%\Claude\, macOS: ~/Library/Application Support/Claude/):

{ "mcpServers": { "paybito": { "command": "paybito-mcp" } } }

Cursor — .cursor/mcp.json in your project (or global ~/.cursor/mcp.json):

{ "mcpServers": { "paybito": { "command": "paybito-mcp" } } }

VS Code (Copilot agent mode) — .vscode/mcp.json:

{ "servers": { "paybito": { "type": "stdio", "command": "paybito-mcp" } } }

OpenAI Codex CLI — ~/.codex/config.toml:

[mcp_servers.paybito]
command = "paybito-mcp"

Gemini CLI — ~/.gemini/settings.json:

{ "mcpServers": { "paybito": { "command": "paybito-mcp" } } }

Windsurf — ~/.codeium/windsurf/mcp_config.json:

{ "mcpServers": { "paybito": { "command": "paybito-mcp" } } }

ChatGPT (Developer mode / connectors) — host the server over HTTP and add it as a custom connector. (Local stdio is for desktop tools; for ChatGPT web, prefer Mode B or a hosted HTTP deployment.)

If paybito-mcp isn't on your PATH, use the absolute path, or { "command": "python", "args": ["-m", "paybito_mcp.server"] }.

Mode B — Portable knowledge bundle (web chat UIs, no install)

Run paybito-build, then upload the generated build/corpus/ folder as knowledge files:

• ChatGPT — Custom GPT → Configure → Knowledge (upload the files), or a Project's files.
• Claude (web/Projects) — create a Project → add the files to Project knowledge.
• Gemini (Gems) — create a Gem → add the files as knowledge.

Start the system/instruction with: "Use the PayBito knowledge files to write integration code; read overview.md and auth.md first."

Use cases — what to ask, and what the AI does

Once injected, the developer works in plain language. Examples:

You ask…	The AI does (via this knowledge)
"Add a PayBito crypto payment button to my WooCommerce checkout."	Reads the woocommerce + payment-button playbooks, pulls GetMerchant_settings / payNowCheckout / get_invoice_status_paid_amount fields, and writes a PHP gateway plugin with correct X-MBX-APIKEY auth and settlement polling.
"Build a Node endpoint to place a spot limit buy and check the order."	Reads spot-trading, gets tradeCreateOffer, getUserBalance, assetpairPrecision, and writes server-side code with precision + error handling and a ⚠️ confirmation step.
"Generate a Python client for PayBito withdrawals."	Finds createWithdrawalOrder / validateAddress / getFees, flags them as state-changing, and writes a client that validates the address and confirms before sending.
"How do I launch my own branded exchange on PayBito?"	Reads build-your-platform, surveys the Broker/Exchange/Access-Control domains, and outlines the onboarding + OAuth + configuration calls with the correct institutional-bo host.
"What does the response of getUserBalance look like?"	Calls paybito_get_operation and returns the documented fields + a ready request example.

The AI writes the code; you run it. The server never executes a PayBito call itself.

Quick prompts (MCP prompts)

In MCP-aware clients you can also invoke the bundled prompts directly: integrate_paybito, add_payment_button, use_playbook, spot_trading_code.

Rebuild when PayBito updates their specs

The specs in specs/ were downloaded from the Redoc spec-url endpoints under https://service.hashcashconsultants.com/Api/…. Re-download them and run paybito-build.

Architecture

specs/*.yaml ──► normalize.py ──► build/model.json ──► corpus.py ──► resources/tools/prompts
  (6 OpenAPI)     (Phase 0:          (1,058 unique     (Phase 1:        (server.py)
                   repair quirks,     operations,       layered
                   merge, dedup)      provenance)       markdown)

Spec quirks the normalizer repairs: empty servers.url; hostnames + query strings baked into path keys; missing securitySchemes (auth is prose-only); 6 mixed hosts incl. WebSocket pseudo-endpoints; heavy overlap across the 6 files.

Auth model (for generated code)

⚠️ PayBito uses three different auth schemes by product — the server resolves the right one per operation (see each operation's Authentication section, or paybito://auth):

• Exchange / Trading (accounts.paybito.com) — one header X-MBX-APIKEY: base64(API_KEY:SECRET).
• Payments Platform — two verbatim headers X-MBX-APIKEY: <key> + X-MBX-SECRETKEY: <secret> (not base64), plus Origin + IP whitelisting on private endpoints.
• Cart / Checkout V2 — X-MBX-PUBLIC-KEY + CLIENT-SECRET-KEY (call createClientSecretKey first to get the per-domain secretHash; see the cart-v2-pk-domain playbook).
• Build-your-exchange / launch — Authorization: Bearer <JWT> from the login endpoint.

Permissions: READ / DEPOSIT / WITHDRAW / TRADE. Rate limit 5 req/s per IP.