@qvapay/mcp-server 2.0.0

package/README.md

@@ -0,0 +1,205 @@
+# @qvapay/mcp-server
+
+MCP (Model Context Protocol) server for [QvaPay](https://qvapay.com) — enabling AI assistants to interact with the QvaPay payment platform.
+
+## Features
+
+- **31 tools** covering market data, P2P trading, merchant, and user operations
+- **Market Data** (public, no auth): Crypto prices, coin listings, P2P averages, stats, and rankings
+- **P2P Trading**: Create/edit/cancel offers, apply, chat, rate counterparties
+- **Merchant API**: Create invoices, charge users, list transactions
+- **User API**: Check balance, transfer money, search users, manage contacts
+- **MCP Resources**: Quick access to profile and balance
+- **Guided Prompts**: Step-by-step workflows for invoices, transfers, and account summaries
+
+## Installation
+
+```bash
+npx @qvapay/mcp-server
+```
+
+Or install globally:
+
+```bash
+npm install -g @qvapay/mcp-server
+```
+
+## Configuration
+
+Set environment variables based on which features you need:
+
+### Market Tools (5 tools) — No auth required
+
+Market tools are always available. They provide public crypto prices, P2P averages, platform stats, and rankings.
+
+### Merchant Tools (7 tools)
+
+```bash
+export QVAPAY_APP_ID="your-app-uuid"
+export QVAPAY_APP_SECRET="your-app-secret"
+```
+
+Get these from your [QvaPay Developer Dashboard](https://qvapay.com/apps).
+
+### User + P2P Tools (19 tools)
+
+```bash
+export QVAPAY_API_TOKEN="your-bearer-token"
+```
+
+Get this from your [QvaPay API Settings](https://qvapay.com/settings/api).
+
+### Optional
+
+```bash
+export QVAPAY_API_URL="https://qvapay.com/api"  # Custom API URL
+```
+
+The server starts with whichever credentials are available. Missing credentials simply means those tools won't be registered. Market tools are always available.
+
+## Usage
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "qvapay": {
+      "command": "npx",
+      "args": ["@qvapay/mcp-server"],
+      "env": {
+        "QVAPAY_APP_ID": "your-app-uuid",
+        "QVAPAY_APP_SECRET": "your-app-secret",
+        "QVAPAY_API_TOKEN": "your-bearer-token"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+Add to `.claude/settings.json` or `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "qvapay": {
+      "command": "npx",
+      "args": ["@qvapay/mcp-server"],
+      "env": {
+        "QVAPAY_APP_ID": "your-app-uuid",
+        "QVAPAY_APP_SECRET": "your-app-secret",
+        "QVAPAY_API_TOKEN": "your-bearer-token"
+      }
+    }
+  }
+}
+```
+
+### If installed globally via npm
+
+```json
+{
+  "mcpServers": {
+    "qvapay": {
+      "command": "qvapay-mcp",
+      "env": {
+        "QVAPAY_APP_ID": "your-app-uuid",
+        "QVAPAY_APP_SECRET": "your-app-secret",
+        "QVAPAY_API_TOKEN": "your-bearer-token"
+      }
+    }
+  }
+}
+```
+
+## Tools Reference
+
+### Market Tools (public, no auth)
+
+| Tool | Description |
+|------|-------------|
+| `qvapay_coins` | List all cryptocurrencies with prices, fees, and limits |
+| `qvapay_price_history` | Get price history for a cryptocurrency (1H to ALL) |
+| `qvapay_p2p_averages` | Current P2P exchange rate averages for all coins |
+| `qvapay_p2p_stats` | Platform statistics: volume, trades, growth |
+| `qvapay_p2p_ranking` | Weekly P2P trading leaderboard (top 20) |
+
+### Merchant Tools (requires APP_ID + APP_SECRET)
+
+| Tool | Description |
+|------|-------------|
+| `qvapay_app_info` | Get merchant app details |
+| `qvapay_app_balance` | Get merchant balance |
+| `qvapay_create_invoice` | Create payment invoice |
+| `qvapay_modify_invoice` | Modify pending invoice |
+| `qvapay_charge_user` | Charge authorized user |
+| `qvapay_app_transactions` | List app transactions |
+| `qvapay_app_transaction_detail` | Get transaction detail |
+
+### User Tools (requires API_TOKEN)
+
+| Tool | Description |
+|------|-------------|
+| `qvapay_user_profile` | Get profile + balance |
+| `qvapay_user_extended` | Extended profile with P2P stats |
+| `qvapay_list_transactions` | List transactions with filters |
+| `qvapay_transaction_detail` | Get transaction detail |
+| `qvapay_transfer` | Transfer money (requires PIN) |
+| `qvapay_search_users` | Search users |
+| `qvapay_payment_methods` | List payment methods |
+| `qvapay_contacts` | List contacts |
+
+### P2P Trading Tools (requires API_TOKEN)
+
+| Tool | Description |
+|------|-------------|
+| `qvapay_p2p_list` | Browse P2P offers with filters |
+| `qvapay_p2p_detail` | Get full details of a P2P offer |
+| `qvapay_p2p_create` | Create a new buy/sell offer |
+| `qvapay_p2p_edit` | Edit an open offer you own |
+| `qvapay_p2p_apply` | Apply to an open offer |
+| `qvapay_p2p_cancel` | Cancel a P2P offer |
+| `qvapay_p2p_paid` | Mark offer as paid (buyer action) |
+| `qvapay_p2p_received` | Confirm payment received (seller action) |
+| `qvapay_p2p_chat_read` | Read chat messages from a trade |
+| `qvapay_p2p_chat_send` | Send a chat message in a trade |
+| `qvapay_p2p_rate` | Rate your counterparty (1-5 stars) |
+
+### Resources
+
+| Resource | URI | Description |
+|----------|-----|-------------|
+| Profile | `qvapay://profile` | Full user profile with balance |
+| Balance | `qvapay://balance` | Quick balance check |
+
+### Prompts
+
+| Prompt | Description |
+|--------|-------------|
+| `create-invoice` | Guided invoice creation workflow |
+| `transfer` | Guided money transfer workflow |
+| `account-summary` | Complete account overview |
+
+## Testing
+
+Use the MCP Inspector to verify the server:
+
+```bash
+npx @modelcontextprotocol/inspector node src/index.js
+```
+
+## Security
+
+- The transfer tool requires a PIN and will always prompt the user
+- P2P create/apply operations that move funds require KYC verification
+- Credentials are read from environment variables only
+- The server is a thin HTTP client — no data is cached or stored
+- All communication uses HTTPS
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,34 @@
+{
+	"name": "@qvapay/mcp-server",
+	"version": "2.0.0",
+	"description": "MCP server for QvaPay — AI-native payment platform with P2P trading, market data, and crypto payments",
+	"type": "module",
+	"main": "src/index.js",
+	"bin": {
+		"qvapay-mcp": "src/index.js"
+	},
+	"scripts": {
+		"start": "node src/index.js",
+		"inspect": "npx @modelcontextprotocol/inspector node src/index.js"
+	},
+	"keywords": [
+		"mcp",
+		"qvapay",
+		"payments",
+		"p2p",
+		"crypto",
+		"ai",
+		"claude",
+		"model-context-protocol",
+		"cuba",
+		"fintech"
+	],
+	"license": "MIT",
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "^1.12.0",
+		"zod": "^3.24.0"
+	},
+	"engines": {
+		"node": ">=18.0.0"
+	}
+}

package/server.json

@@ -0,0 +1,72 @@
+{
+	"$schema": "https://registry.modelcontextprotocol.io/schemas/server.json",
+	"name": "com.qvapay/mcp-server",
+	"description": "QvaPay — AI-native payment platform. Market data, P2P trading, invoices, transfers, and crypto payments for Cuba and Latin America.",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/qvapay/mcp-server"
+	},
+	"version_detail": {
+		"version": "2.0.0",
+		"release_date": "2026-03-15"
+	},
+	"packages": [
+		{
+			"registry_name": "npm",
+			"name": "@qvapay/mcp-server",
+			"version": "2.0.0",
+			"runtime": "node",
+			"runtime_arguments": [],
+			"environment_variables": [
+				{
+					"name": "QVAPAY_APP_ID",
+					"description": "Merchant app UUID from QvaPay Developer Dashboard",
+					"required": false
+				},
+				{
+					"name": "QVAPAY_APP_SECRET",
+					"description": "Merchant app secret from QvaPay Developer Dashboard",
+					"required": false
+				},
+				{
+					"name": "QVAPAY_API_TOKEN",
+					"description": "User bearer token from QvaPay API Settings",
+					"required": false
+				}
+			]
+		}
+	],
+	"tools": [
+		{ "name": "qvapay_coins", "description": "List all cryptocurrencies with prices, fees, and limits" },
+		{ "name": "qvapay_price_history", "description": "Get price history for a cryptocurrency" },
+		{ "name": "qvapay_p2p_averages", "description": "Current P2P exchange rate averages" },
+		{ "name": "qvapay_p2p_stats", "description": "Platform statistics: volume, trades, growth" },
+		{ "name": "qvapay_p2p_ranking", "description": "Weekly P2P trading leaderboard" },
+		{ "name": "qvapay_app_info", "description": "Get merchant app details" },
+		{ "name": "qvapay_app_balance", "description": "Get merchant balance" },
+		{ "name": "qvapay_create_invoice", "description": "Create payment invoice" },
+		{ "name": "qvapay_modify_invoice", "description": "Modify pending invoice" },
+		{ "name": "qvapay_charge_user", "description": "Charge authorized user" },
+		{ "name": "qvapay_app_transactions", "description": "List app transactions" },
+		{ "name": "qvapay_app_transaction_detail", "description": "Get transaction detail" },
+		{ "name": "qvapay_user_profile", "description": "Get profile + balance" },
+		{ "name": "qvapay_user_extended", "description": "Extended profile with P2P stats" },
+		{ "name": "qvapay_list_transactions", "description": "List transactions with filters" },
+		{ "name": "qvapay_transaction_detail", "description": "Get transaction detail" },
+		{ "name": "qvapay_transfer", "description": "Transfer money (requires PIN)" },
+		{ "name": "qvapay_search_users", "description": "Search users" },
+		{ "name": "qvapay_payment_methods", "description": "List payment methods" },
+		{ "name": "qvapay_contacts", "description": "List contacts" },
+		{ "name": "qvapay_p2p_list", "description": "Browse P2P offers with filters" },
+		{ "name": "qvapay_p2p_detail", "description": "Get full details of a P2P offer" },
+		{ "name": "qvapay_p2p_create", "description": "Create a new buy/sell P2P offer" },
+		{ "name": "qvapay_p2p_edit", "description": "Edit an open P2P offer" },
+		{ "name": "qvapay_p2p_apply", "description": "Apply to an open P2P offer" },
+		{ "name": "qvapay_p2p_cancel", "description": "Cancel a P2P offer" },
+		{ "name": "qvapay_p2p_paid", "description": "Mark P2P offer as paid" },
+		{ "name": "qvapay_p2p_received", "description": "Confirm payment received" },
+		{ "name": "qvapay_p2p_chat_read", "description": "Read P2P trade chat messages" },
+		{ "name": "qvapay_p2p_chat_send", "description": "Send P2P trade chat message" },
+		{ "name": "qvapay_p2p_rate", "description": "Rate counterparty after trade" }
+	]
+}

package/src/client.js

@@ -0,0 +1,100 @@
+// QvaPay HTTP Client
+// Handles both merchant (app-id/app-secret) and user (bearer token) auth
+
+import { config } from './config.js'
+
+class QvaPayClient {
+
+	// Public API call (no auth required)
+	async public(endpoint, { query } = {}) {
+
+		let url = `${config.apiUrl}${endpoint}`
+		if (query) {
+			const params = new URLSearchParams()
+			for (const [key, value] of Object.entries(query)) {
+				if (value !== undefined && value !== null && value !== '') {
+					params.set(key, String(value))
+				}
+			}
+			const qs = params.toString()
+			if (qs) url += `?${qs}`
+		}
+
+		const res = await fetch(url)
+		return this._handleResponse(res)
+	}
+
+	// Merchant API call (POST with app-id/app-secret headers)
+	async merchant(endpoint, body = {}) {
+
+		if (!config.hasMerchantAuth) { throw new Error('Merchant credentials not configured. Set QVAPAY_APP_ID and QVAPAY_APP_SECRET.') }
+
+		const url = `${config.apiUrl}${endpoint}`
+		const res = await fetch(url, {
+			method: 'POST',
+			headers: {
+				'Content-Type': 'application/json',
+				'app-id': config.appId,
+				'app-secret': config.appSecret,
+			},
+			body: JSON.stringify(body),
+		})
+
+		return this._handleResponse(res)
+	}
+
+	// User API call with bearer token
+	async user(endpoint, { method = 'GET', body, query } = {}) {
+
+		if (!config.hasUserAuth) { throw new Error('User token not configured. Set QVAPAY_API_TOKEN.') }
+
+		let url = `${config.apiUrl}${endpoint}`
+		if (query) {
+			const params = new URLSearchParams()
+			for (const [key, value] of Object.entries(query)) {
+				if (value !== undefined && value !== null && value !== '') {
+					params.set(key, String(value))
+				}
+			}
+			const qs = params.toString()
+			if (qs) url += `?${qs}`
+		}
+
+		const options = {
+			method,
+			headers: {
+				'Content-Type': 'application/json',
+				'Authorization': `Bearer ${config.apiToken}`,
+			},
+		}
+
+		if (body && method !== 'GET') {
+			options.body = JSON.stringify(body)
+		}
+
+		const res = await fetch(url, options)
+		return this._handleResponse(res)
+	}
+
+	async _handleResponse(res) {
+		const text = await res.text()
+
+		let data
+		try {
+			data = JSON.parse(text)
+		} catch {
+			data = text
+		}
+
+		if (!res.ok) {
+			const message = typeof data === 'object' && data !== null
+				? data.message || data.error || JSON.stringify(data)
+				: String(data)
+			throw new Error(`QvaPay API error (${res.status}): ${message}`)
+		}
+
+		return data
+	}
+}
+
+export const client = new QvaPayClient()

package/src/config.js

@@ -0,0 +1,23 @@
+// QvaPay MCP Server Configuration
+// Loads credentials from environment variables
+
+export const config = {
+	// Merchant API credentials (v2 endpoints)
+	appId: process.env.QVAPAY_APP_ID || '',
+	appSecret: process.env.QVAPAY_APP_SECRET || '',
+
+	// User API token (bearer auth)
+	apiToken: process.env.QVAPAY_API_TOKEN || '',
+
+	// Base URL for QvaPay API
+	apiUrl: (process.env.QVAPAY_API_URL || 'https://qvapay.com/api').replace(/\/$/, ''),
+
+	// Auth availability checks
+	get hasMerchantAuth() {
+		return Boolean(this.appId && this.appSecret)
+	},
+
+	get hasUserAuth() {
+		return Boolean(this.apiToken)
+	},
+}

package/src/index.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+
+// QvaPay MCP Server
+// AI-native payment platform integration via Model Context Protocol
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { config } from './config.js'
+import { registerMerchantTools } from './tools/merchant.js'
+import { registerUserTools } from './tools/user.js'
+import { registerMarketTools } from './tools/market.js'
+import { registerP2PTools } from './tools/p2p.js'
+import { registerResources } from './resources/profile.js'
+import { registerPrompts } from './prompts/index.js'
+
+const server = new McpServer({
+	name: 'qvapay',
+	version: '2.0.0',
+	description: 'QvaPay — AI-native payment platform. Market data, P2P trading, invoices, transfers, and crypto payments.',
+})
+
+// Register tools based on available credentials
+if (config.hasMerchantAuth) {
+	registerMerchantTools(server)
+	console.error('[qvapay-mcp] Merchant tools enabled (app-id: ' + config.appId.slice(0, 8) + '...)')
+}
+
+if (config.hasUserAuth) {
+	registerUserTools(server)
+	registerP2PTools(server)
+	registerResources(server)
+	console.error('[qvapay-mcp] User + P2P tools enabled')
+}
+
+// Market tools are always available (public endpoints, no auth)
+registerMarketTools(server)
+console.error('[qvapay-mcp] Market tools enabled (public)')
+
+// Prompts are always available
+registerPrompts(server)
+
+if (!config.hasMerchantAuth && !config.hasUserAuth) {
+	console.error('[qvapay-mcp] WARNING: No credentials configured. Set QVAPAY_APP_ID + QVAPAY_APP_SECRET for merchant tools, or QVAPAY_API_TOKEN for user tools.')
+}
+
+// Start stdio transport
+const transport = new StdioServerTransport()
+await server.connect(transport)
+
+console.error('[qvapay-mcp] Server started on stdio')

package/src/prompts/index.js

@@ -0,0 +1,98 @@
+// MCP Prompts — Guided workflows for common QvaPay operations
+
+import { z } from 'zod'
+
+export function registerPrompts(server) {
+
+	// Create invoice workflow
+	server.prompt(
+		'create-invoice',
+		'Guided workflow to create a payment invoice',
+		{
+			amount: z.string().optional().describe('Amount in USD'),
+			description: z.string().optional().describe('Payment description'),
+		},
+		({ amount, description } = {}) => {
+			const parts = []
+
+			if (amount && description) {
+				parts.push(`Create a QvaPay invoice for $${amount} with description: "${description}".`)
+				parts.push('Generate a unique remote_id and use the qvapay_create_invoice tool.')
+			} else if (amount) {
+				parts.push(`Create a QvaPay invoice for $${amount}.`)
+				parts.push('Ask me for a description, then generate a unique remote_id and use the qvapay_create_invoice tool.')
+			} else {
+				parts.push('Help me create a QvaPay payment invoice.')
+				parts.push('Ask me for: 1) Amount in USD, 2) Description of what this payment is for.')
+				parts.push('Then generate a unique remote_id and use the qvapay_create_invoice tool.')
+			}
+
+			parts.push('After creating the invoice, show me the payment URL.')
+
+			return {
+				messages: [{
+					role: 'user',
+					content: { type: 'text', text: parts.join('\n') },
+				}],
+			}
+		}
+	)
+
+	// Transfer workflow
+	server.prompt(
+		'transfer',
+		'Guided workflow to transfer money to another user',
+		{
+			to: z.string().optional().describe('Recipient username, email, or UUID'),
+			amount: z.string().optional().describe('Amount in USD'),
+		},
+		({ to, amount } = {}) => {
+			const parts = []
+
+			if (to && amount) {
+				parts.push(`Transfer $${amount} to ${to} on QvaPay.`)
+			} else if (to) {
+				parts.push(`Transfer money to ${to} on QvaPay. Ask me for the amount.`)
+			} else {
+				parts.push('Help me transfer money on QvaPay.')
+				parts.push('Ask me for: 1) Recipient (username, email, or phone), 2) Amount in USD.')
+			}
+
+			parts.push('Before executing, verify the recipient using qvapay_search_users.')
+			parts.push('IMPORTANT: Ask me for my PIN before calling qvapay_transfer. Never guess the PIN.')
+			parts.push('After the transfer, confirm the transaction details.')
+
+			return {
+				messages: [{
+					role: 'user',
+					content: { type: 'text', text: parts.join('\n') },
+				}],
+			}
+		}
+	)
+
+	// Account summary
+	server.prompt(
+		'account-summary',
+		'Get a complete summary of the QvaPay account',
+		{},
+		() => ({
+			messages: [{
+				role: 'user',
+				content: {
+					type: 'text',
+					text: [
+						'Give me a complete summary of my QvaPay account.',
+						'Use qvapay_user_profile to get my profile and balance.',
+						'Use qvapay_list_transactions with include_total=true to get recent transactions.',
+						'Present a clear summary with:',
+						'- Account info (username, verification status, golden check)',
+						'- Current balance',
+						'- Recent transaction activity (last 5-10 transactions)',
+						'- Total incoming vs outgoing if visible from recent transactions',
+					].join('\n'),
+				},
+			}],
+		})
+	)
+}

package/src/resources/profile.js

@@ -0,0 +1,66 @@
+// MCP Resources — User profile and balance
+// Resources are read-only data that AI can access without explicit tool calls
+
+import { client } from '../client.js'
+
+export function registerResources(server) {
+
+	// User profile resource
+	server.resource(
+		'profile',
+		'qvapay://profile',
+		{ description: 'Current QvaPay user profile with balance and account details', mimeType: 'application/json' },
+		async () => {
+			try {
+				const data = await client.user('/user')
+				return {
+					contents: [{
+						uri: 'qvapay://profile',
+						mimeType: 'application/json',
+						text: JSON.stringify(data, null, 2),
+					}],
+				}
+			} catch (error) {
+				return {
+					contents: [{
+						uri: 'qvapay://profile',
+						mimeType: 'text/plain',
+						text: `Error fetching profile: ${error.message}`,
+					}],
+				}
+			}
+		}
+	)
+
+	// Balance resource (quick access)
+	server.resource(
+		'balance',
+		'qvapay://balance',
+		{ description: 'Current QvaPay account balance in USD', mimeType: 'application/json' },
+		async () => {
+			try {
+				const data = await client.user('/user')
+				const balance = {
+					balance: data.balance,
+					username: data.username,
+					golden_check: data.golden_check,
+				}
+				return {
+					contents: [{
+						uri: 'qvapay://balance',
+						mimeType: 'application/json',
+						text: JSON.stringify(balance, null, 2),
+					}],
+				}
+			} catch (error) {
+				return {
+					contents: [{
+						uri: 'qvapay://balance',
+						mimeType: 'text/plain',
+						text: `Error fetching balance: ${error.message}`,
+					}],
+				}
+			}
+		}
+	)
+}

package/src/tools/market.js

@@ -0,0 +1,96 @@
+// Market Tools — Public endpoints for crypto prices, coins, and P2P averages (no auth required)
+
+import { z } from 'zod'
+import { client } from '../client.js'
+
+export function registerMarketTools(server) {
+
+	// List available coins
+	server.tool(
+		'qvapay_coins',
+		'List all cryptocurrencies available on QvaPay with prices, fees, and deposit/withdrawal limits. Optionally filter by feature.',
+		{
+			enabled_in: z.boolean().optional().describe('Filter coins enabled for deposits'),
+			enabled_out: z.boolean().optional().describe('Filter coins enabled for withdrawals'),
+			enabled_p2p: z.boolean().optional().describe('Filter coins enabled for P2P trading'),
+			trade: z.boolean().optional().describe('Filter tradeable coins'),
+		},
+		async (params = {}) => {
+			try {
+				const query = {}
+				if (params.enabled_in) query.enabled_in = '1'
+				if (params.enabled_out) query.enabled_out = '1'
+				if (params.enabled_p2p) query.enabled_p2p = '1'
+				if (params.trade) query.trade = '1'
+				const data = await client.public('/coins/v2', { query })
+				return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+			} catch (error) {
+				return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+			}
+		}
+	)
+
+	// Get crypto price history
+	server.tool(
+		'qvapay_price_history',
+		'Get price history for a cryptocurrency. Returns time-series data points with timestamps and USD prices.',
+		{
+			coin: z.string().describe('Coin ticker symbol (e.g., BTC, ETH, TRX, SOL, USDT)'),
+			timeframe: z.enum(['1H', '24H', '1W', '1M', '1Y', 'ALL']).optional().describe('Time range (default: 24H). 1H=last hour, 24H=last day, 1W=last week, 1M=last month, 1Y=last year, ALL=all time'),
+		},
+		async ({ coin, timeframe }) => {
+			try {
+				const query = timeframe ? { timeframe } : undefined
+				const data = await client.public(`/coins/price-history/${coin.toUpperCase()}`, { query })
+				return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+			} catch (error) {
+				return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+			}
+		}
+	)
+
+	// Get P2P market averages
+	server.tool(
+		'qvapay_p2p_averages',
+		'Get current P2P exchange rate averages for all coins. Shows buy/sell averages and offer counts based on completed trades in the last 24 hours. This is the best way to check current exchange rates on QvaPay.',
+		{},
+		async () => {
+			try {
+				const data = await client.public('/p2p/averages')
+				return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+			} catch (error) {
+				return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+			}
+		}
+	)
+
+	// Get P2P platform stats
+	server.tool(
+		'qvapay_p2p_stats',
+		'Get QvaPay P2P platform statistics: volume, trade counts, monthly trends, user growth, and year-over-year metrics.',
+		{},
+		async () => {
+			try {
+				const data = await client.public('/p2p/stats')
+				return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+			} catch (error) {
+				return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+			}
+		}
+	)
+
+	// Get P2P weekly ranking
+	server.tool(
+		'qvapay_p2p_ranking',
+		'Get the weekly P2P trading leaderboard. Shows top 20 traders ranked by volume, trade count, unique partners, and ratings.',
+		{},
+		async () => {
+			try {
+				const data = await client.public('/p2p/ranking')
+				return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+			} catch (error) {
+				return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+			}
+		}
+	)
+}

package/src/tools/merchant.js

@@ -0,0 +1,145 @@
+// Merchant Tools — QvaPay v2 API (requires QVAPAY_APP_ID + QVAPAY_APP_SECRET)
+
+import { z } from 'zod'
+import { client } from '../client.js'
+
+export function registerMerchantTools(server) {
+
+	// Get merchant app info
+	server.tool(
+		'qvapay_app_info',
+		'Get merchant app details (name, URL, description, logo, status)',
+		{},
+		async () => {
+			try {
+				const data = await client.merchant('/v2/info')
+				return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+			} catch (error) {
+				return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+			}
+		}
+	)
+
+	// Get merchant balance
+	server.tool(
+		'qvapay_app_balance',
+		'Get merchant app balance in USD',
+		{},
+		async () => {
+			try {
+				const data = await client.merchant('/v2/balance')
+				return { content: [{ type: 'text', text: JSON.stringify({ balance: data }, null, 2) }] }
+			} catch (error) {
+				return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+			}
+		}
+	)
+
+	// Create payment invoice
+	server.tool(
+		'qvapay_create_invoice',
+		'Create a payment invoice. Returns a payment URL that can be shared with the payer.',
+		{
+			amount: z.number().positive().max(100000).describe('Amount in USD to charge'),
+			description: z.string().min(1).max(255).describe('Description of the payment'),
+			remote_id: z.string().min(1).max(255).describe('Your external reference ID for this payment'),
+			webhook: z.string().url().optional().describe('URL to receive payment webhook notifications'),
+			products: z.array(z.object({
+				name: z.string().min(1).describe('Product name'),
+				price: z.number().positive().describe('Product price'),
+				quantity: z.number().int().positive().optional().describe('Quantity (default: 1)'),
+			})).optional().describe('List of products in this invoice'),
+			expire_at: z.string().optional().describe('Expiration date in ISO 8601 format (must be in the future)'),
+		},
+		async (params) => {
+			try {
+				const data = await client.merchant('/v2/create_invoice', params)
+				return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+			} catch (error) {
+				return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+			}
+		}
+	)
+
+	// Modify pending invoice
+	server.tool(
+		'qvapay_modify_invoice',
+		'Modify a pending invoice. Only works if the invoice has not been paid yet.',
+		{
+			transaction_uuid: z.string().describe('UUID of the transaction/invoice to modify'),
+			amount: z.number().positive().max(100000).optional().describe('New amount in USD'),
+			description: z.string().min(1).max(255).optional().describe('New description'),
+			remote_id: z.string().min(1).max(255).optional().describe('New external reference ID'),
+			webhook: z.string().optional().describe('New webhook URL (empty string to clear)'),
+			products: z.array(z.object({
+				name: z.string().min(1).describe('Product name'),
+				price: z.number().positive().describe('Product price'),
+				quantity: z.number().int().positive().optional().describe('Quantity (default: 1)'),
+			})).optional().describe('Updated product list'),
+			expire_at: z.string().optional().describe('New expiration date in ISO 8601 format'),
+		},
+		async (params) => {
+			try {
+				const data = await client.merchant('/v2/modify_invoice', params)
+				return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+			} catch (error) {
+				return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+			}
+		}
+	)
+
+	// Charge an authorized user
+	server.tool(
+		'qvapay_charge_user',
+		'Charge a user who has authorized payments to your app. Deducts from their balance immediately.',
+		{
+			amount: z.number().positive().max(100000).describe('Amount in USD to charge'),
+			user_uuid: z.string().describe('UUID of the user to charge'),
+			description: z.string().min(1).max(255).describe('Description of the charge'),
+			remote_id: z.string().min(1).max(255).describe('Your external reference ID'),
+		},
+		async (params) => {
+			try {
+				const data = await client.merchant('/v2/charge', params)
+				return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+			} catch (error) {
+				return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+			}
+		}
+	)
+
+	// List app transactions
+	server.tool(
+		'qvapay_app_transactions',
+		'List transactions for the merchant app, paginated.',
+		{
+			page: z.number().int().positive().optional().describe('Page number (default: 1)'),
+			take: z.number().int().positive().max(100).optional().describe('Results per page (default: 30, max: 100)'),
+		},
+		async (params) => {
+			try {
+				const data = await client.merchant('/v2/transactions', params)
+				return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+			} catch (error) {
+				return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+			}
+		}
+	)
+
+	// Get single transaction detail
+	server.tool(
+		'qvapay_app_transaction_detail',
+		'Get detailed information about a specific merchant app transaction.',
+		{
+			uuid: z.string().describe('UUID of the transaction'),
+		},
+		async ({ uuid }) => {
+			try {
+				const data = await client.merchant(`/v2/transactions/${uuid}`)
+				return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+			} catch (error) {
+				return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+			}
+		}
+	)
+}

package/src/tools/p2p.js

@@ -0,0 +1,235 @@
+// P2P Tools — QvaPay P2P Trading (requires QVAPAY_API_TOKEN)
+
+import { z } from 'zod'
+import { client } from '../client.js'
+
+export function registerP2PTools(server) {
+
+	// List P2P offers
+	server.tool(
+		'qvapay_p2p_list',
+		'Browse P2P offers on QvaPay. Filter by type (buy/sell), coin, amount range, or see only your own offers.',
+		{
+			type: z.enum(['buy', 'sell']).optional().describe('Filter by offer type'),
+			coin: z.string().optional().describe('Filter by coin ticker (e.g., TRX, USDT, BTC)'),
+			my: z.boolean().optional().describe('Show only your own offers'),
+			status: z.string().optional().describe('Filter by status: open, processing, paid, completed, cancelled'),
+			min: z.number().optional().describe('Minimum amount filter'),
+			max: z.number().optional().describe('Maximum amount filter'),
+			search: z.string().optional().describe('Search query'),
+			page: z.number().int().positive().optional().describe('Page number (default: 1)'),
+			take: z.number().int().positive().max(30).optional().describe('Results per page (default: 20)'),
+		},
+		async (params = {}) => {
+			try {
+				const query = {}
+				for (const [key, value] of Object.entries(params)) {
+					if (value !== undefined && value !== null) query[key] = String(value)
+				}
+				const data = await client.user('/p2p', { query })
+				return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+			} catch (error) {
+				return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+			}
+		}
+	)
+
+	// Get P2P offer details
+	server.tool(
+		'qvapay_p2p_detail',
+		'Get full details of a specific P2P offer including participants, coin info, and chat availability.',
+		{
+			uuid: z.string().describe('UUID of the P2P offer'),
+		},
+		async ({ uuid }) => {
+			try {
+				const data = await client.user(`/p2p/${uuid}`)
+				return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+			} catch (error) {
+				return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+			}
+		}
+	)
+
+	// Create P2P offer
+	server.tool(
+		'qvapay_p2p_create',
+		'Create a new P2P trading offer. For SELL offers, the amount is deducted from your balance immediately. Requires KYC verification.',
+		{
+			type: z.enum(['buy', 'sell']).describe('Offer type: "buy" to buy crypto, "sell" to sell crypto'),
+			coin: z.string().describe('Coin ticker (e.g., TRX, USDT, BTC) or coin ID number'),
+			amount: z.number().min(0.1).max(100000).describe('Amount in QUSD to trade'),
+			receive: z.number().min(0.1).max(1000000).describe('Amount to receive in the target currency'),
+			details: z.record(z.string()).describe('Payment details object — keys depend on the coin (e.g., { "address": "TRX..." } for crypto, { "card": "..." } for fiat)'),
+			message: z.string().max(79).optional().describe('Public message for the offer (max 79 chars)'),
+			only_kyc: z.boolean().optional().describe('Only allow KYC-verified users to apply'),
+			private: z.boolean().optional().describe('Make this a private offer (not listed publicly)'),
+			only_vip: z.boolean().optional().describe('Only allow VIP users to apply'),
+			tags: z.array(z.string()).max(10).optional().describe('Tags for the offer (max 10)'),
+			webhook: z.string().url().optional().describe('Webhook URL for status updates'),
+		},
+		async (params) => {
+			try {
+				const body = { ...params }
+				if (body.only_kyc !== undefined) body.only_kyc = body.only_kyc ? 1 : 0
+				if (body.private !== undefined) body.private = body.private ? 1 : 0
+				if (body.only_vip !== undefined) body.only_vip = body.only_vip ? 1 : 0
+				const data = await client.user('/p2p/create', { method: 'POST', body })
+				return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+			} catch (error) {
+				return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+			}
+		}
+	)
+
+	// Edit P2P offer
+	server.tool(
+		'qvapay_p2p_edit',
+		'Edit an open P2P offer you own. Can change amount, receive, message, tags, and visibility. For SELL offers, balance is adjusted automatically.',
+		{
+			uuid: z.string().describe('UUID of the P2P offer to edit'),
+			amount: z.number().min(0.1).max(100000).optional().describe('New trade amount'),
+			receive: z.number().min(0.1).max(1000000).optional().describe('New receive amount'),
+			message: z.string().max(79).optional().describe('New public message'),
+			only_vip: z.boolean().optional().describe('Restrict to VIP users'),
+			tags: z.array(z.string()).max(10).optional().describe('New tags'),
+			webhook: z.string().url().optional().describe('New webhook URL'),
+		},
+		async ({ uuid, ...params }) => {
+			try {
+				const data = await client.user(`/p2p/${uuid}/edit`, { method: 'POST', body: params })
+				return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+			} catch (error) {
+				return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+			}
+		}
+	)
+
+	// Apply to P2P offer
+	server.tool(
+		'qvapay_p2p_apply',
+		'Apply to an open P2P offer. For BUY offers (you are selling), the amount is deducted from your balance. Requires KYC.',
+		{
+			uuid: z.string().describe('UUID of the P2P offer to apply to'),
+		},
+		async ({ uuid }) => {
+			try {
+				const data = await client.user(`/p2p/${uuid}/apply`, { method: 'POST', body: {} })
+				return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+			} catch (error) {
+				return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+			}
+		}
+	)
+
+	// Cancel P2P offer
+	server.tool(
+		'qvapay_p2p_cancel',
+		'Cancel a P2P offer. Behavior depends on your role (owner/peer) and offer type. Funds are refunded when applicable.',
+		{
+			uuid: z.string().describe('UUID of the P2P offer to cancel'),
+		},
+		async ({ uuid }) => {
+			try {
+				const data = await client.user(`/p2p/${uuid}/cancel`, { method: 'POST', body: {} })
+				return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+			} catch (error) {
+				return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+			}
+		}
+	)
+
+	// Mark P2P as paid
+	server.tool(
+		'qvapay_p2p_paid',
+		'Mark a P2P offer as paid. Only the buyer can do this (owner for BUY offers, peer for SELL offers). Call this after you have sent payment.',
+		{
+			uuid: z.string().describe('UUID of the P2P offer'),
+			tx_id: z.string().optional().describe('Transaction ID or proof of payment reference'),
+		},
+		async ({ uuid, tx_id }) => {
+			try {
+				const body = tx_id ? { tx_id } : {}
+				const data = await client.user(`/p2p/${uuid}/paid`, { method: 'POST', body })
+				return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+			} catch (error) {
+				return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+			}
+		}
+	)
+
+	// Mark P2P as received (complete)
+	server.tool(
+		'qvapay_p2p_received',
+		'Confirm payment received and complete a P2P trade. Only the seller can do this (peer for BUY offers, owner for SELL offers). A 0.25% fee is applied unless you have golden status.',
+		{
+			uuid: z.string().describe('UUID of the P2P offer'),
+		},
+		async ({ uuid }) => {
+			try {
+				const data = await client.user(`/p2p/${uuid}/received`, { method: 'POST', body: {} })
+				return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+			} catch (error) {
+				return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+			}
+		}
+	)
+
+	// P2P Chat - read messages
+	server.tool(
+		'qvapay_p2p_chat_read',
+		'Read chat messages from a P2P trade. Only participants can read the chat.',
+		{
+			uuid: z.string().describe('UUID of the P2P offer'),
+		},
+		async ({ uuid }) => {
+			try {
+				const data = await client.user(`/p2p/${uuid}/chat`)
+				return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+			} catch (error) {
+				return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+			}
+		}
+	)
+
+	// P2P Chat - send message
+	server.tool(
+		'qvapay_p2p_chat_send',
+		'Send a text message in a P2P trade chat. Only participants can send messages.',
+		{
+			uuid: z.string().describe('UUID of the P2P offer'),
+			message: z.string().min(1).max(599).describe('Message text to send'),
+		},
+		async ({ uuid, message }) => {
+			try {
+				const data = await client.user(`/p2p/${uuid}/chat`, {
+					method: 'POST',
+					body: { message },
+				})
+				return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+			} catch (error) {
+				return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+			}
+		}
+	)
+
+	// Rate P2P counterparty
+	server.tool(
+		'qvapay_p2p_rate',
+		'Rate your counterparty after completing a P2P trade. Rating is 1-5 stars with optional comment.',
+		{
+			uuid: z.string().describe('UUID of the completed P2P offer'),
+			rating: z.number().int().min(1).max(5).describe('Rating from 1 (worst) to 5 (best)'),
+			comment: z.string().max(120).optional().describe('Optional review comment (max 120 chars)'),
+			tags: z.array(z.enum(['rapido', 'confiable', 'comunicacion'])).optional().describe('Optional tags: rapido, confiable, comunicacion'),
+		},
+		async ({ uuid, ...body }) => {
+			try {
+				const data = await client.user(`/p2p/${uuid}/rate`, { method: 'POST', body })
+				return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+			} catch (error) {
+				return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+			}
+		}
+	)
+}

package/src/tools/user.js

@@ -0,0 +1,166 @@
+// User Tools — QvaPay User API (requires QVAPAY_API_TOKEN)
+
+import { z } from 'zod'
+import { client } from '../client.js'
+
+export function registerUserTools(server) {
+
+	// Get user profile
+	server.tool(
+		'qvapay_user_profile',
+		'Get your QvaPay profile including balance, username, verification status, and 3 most recent transactions.',
+		{},
+		async () => {
+			try {
+				const data = await client.user('/user')
+				return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+			} catch (error) {
+				return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+			}
+		}
+	)
+
+	// Get extended profile
+	server.tool(
+		'qvapay_user_extended',
+		'Get extended profile with P2P trading stats, recent withdrawals, and verification details.',
+		{},
+		async () => {
+			try {
+				const data = await client.user('/user/extended')
+				return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+			} catch (error) {
+				return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+			}
+		}
+	)
+
+	// List transactions with filters
+	server.tool(
+		'qvapay_list_transactions',
+		'List your transactions with optional filters. Returns paginated results.',
+		{
+			page: z.number().int().positive().optional().describe('Page number (default: 1)'),
+			take: z.number().int().positive().max(30).optional().describe('Results per page (default: 20, max: 30)'),
+			status: z.string().optional().describe('Filter by status: paid, pending, cancelled (default: paid)'),
+			search: z.string().optional().describe('Search by description, UUID, or remote_id'),
+			uuid: z.string().optional().describe('Find a specific transaction by UUID'),
+			user_uuid: z.string().optional().describe('Filter transactions involving a specific user'),
+			min_amount: z.number().optional().describe('Minimum amount filter'),
+			max_amount: z.number().optional().describe('Maximum amount filter'),
+			date_from: z.string().optional().describe('Start date filter (ISO 8601)'),
+			date_to: z.string().optional().describe('End date filter (ISO 8601)'),
+			order: z.enum(['asc', 'desc']).optional().describe('Sort order (default: desc)'),
+			include_total: z.boolean().optional().describe('Include total count for pagination'),
+		},
+		async (params) => {
+			try {
+				const query = { ...params }
+				if (query.include_total) {
+					query.include_total = 'true'
+					delete query.include_total_bool
+				}
+				const data = await client.user('/transaction', { query })
+				return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+			} catch (error) {
+				return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+			}
+		}
+	)
+
+	// Get transaction detail
+	server.tool(
+		'qvapay_transaction_detail',
+		'Get full details of a specific transaction by UUID.',
+		{
+			uuid: z.string().describe('UUID of the transaction'),
+		},
+		async ({ uuid }) => {
+			try {
+				const data = await client.user(`/transaction/${uuid}`)
+				return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+			} catch (error) {
+				return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+			}
+		}
+	)
+
+	// Transfer money
+	server.tool(
+		'qvapay_transfer',
+		'Transfer money to another QvaPay user. IMPORTANT: Always ask the user for their PIN before calling this tool. Never guess or assume the PIN.',
+		{
+			amount: z.number().positive().describe('Amount in USD to transfer'),
+			to: z.string().describe('Recipient identifier: UUID, email, username, or phone number'),
+			pin: z.string().regex(/^\d{4}$|^\d{6}$/).describe('Your 4 or 6 digit security PIN. Ask the user for this — never assume it.'),
+			description: z.string().optional().describe('Optional transfer description'),
+		},
+		async (params) => {
+			try {
+				const data = await client.user('/transaction/transfer', {
+					method: 'POST',
+					body: params,
+				})
+				return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+			} catch (error) {
+				return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+			}
+		}
+	)
+
+	// Search users
+	server.tool(
+		'qvapay_search_users',
+		'Search for QvaPay users by username, email, UUID, or phone number.',
+		{
+			query: z.string().min(1).describe('Search query (username, email, UUID, or phone)'),
+		},
+		async ({ query }) => {
+			try {
+				const data = await client.user('/user/search', {
+					method: 'POST',
+					body: { query },
+				})
+				return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+			} catch (error) {
+				return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+			}
+		}
+	)
+
+	// List payment methods
+	server.tool(
+		'qvapay_payment_methods',
+		'List your saved payment methods, optionally filtered by cryptocurrency.',
+		{
+			coin: z.string().optional().describe('Filter by coin ticker (e.g., BTC, ETH, TRX)'),
+		},
+		async ({ coin } = {}) => {
+			try {
+				const query = coin ? { coin } : undefined
+				const data = await client.user('/user/payment-methods', { query })
+				return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+			} catch (error) {
+				return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+			}
+		}
+	)
+
+	// List contacts
+	server.tool(
+		'qvapay_contacts',
+		'List your QvaPay contacts. Optionally filter to show only favorites.',
+		{
+			favorite: z.boolean().optional().describe('If true, only show favorite contacts'),
+		},
+		async ({ favorite } = {}) => {
+			try {
+				const query = favorite ? { favorite: 'true' } : undefined
+				const data = await client.user('/user/contact', { query })
+				return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+			} catch (error) {
+				return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+			}
+		}
+	)
+}