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

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:

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:

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.