# coinvoyage-paykit-claudeplugin

Claude Code plugin for integrating [CoinVoyage](https://coinvoyage.io) — a non-custodial, multi-chain crypto payment gateway — into any app you build with Claude.

Bundles two surfaces:

1. **Skill (`coinvoyage-payments`)** — triggers whenever Claude is helping with crypto payments, checkout, stablecoins, or web3 payment work. Guides the integration end to end: server-side PayOrder creation, React `PaymentWidget`, webhook signature verification, and REST API fallback for non-JS stacks.
2. **MCP server (`@kingpeque/coinvoyage-mcp`)** — gives Claude 15 tools for calling the CoinVoyage API directly: create PayOrders, check status, manage webhooks, get swap quotes, and more.

> **Community-maintained integration.** Not officially affiliated with CoinVoyage.

## Install

```bash
/plugin install KingPeque/coinvoyage-paykit
```

You'll be prompted at install for:

| Field | Required | Notes |
|-------|----------|-------|
| `api_key` | yes | Your public API key from https://dashboard.coinvoyage.io → Developers |
| `api_secret` | optional | Needed for SALE/REFUND orders, webhook management, and fee claims. Leave blank to restrict Claude to read + DEPOSIT flows only. |
| `api_base_url` | optional | Defaults to `https://api.coinvoyage.io` |

The secret is stored in your system keychain via Claude Code's sensitive-config pathway — it never lands in a file you'd commit.

## What you can now say to Claude

Once installed, these kinds of requests will activate the skill and/or MCP tools:

- "Add crypto payments to my Next.js checkout"
- "I want to accept Bitcoin on from my site"
- "Build a donation page that takes any crypto while I settle to USDC on base"
- "Create a $25 test invoice and settle to USDC on Base heres my wallet"
- "Register a webhook at https://mysite.com/api/webhooks/coinvoyage for completed orders"


## What's inside

```
coinvoyage-paykit/
├── .claude-plugin/
│   └── plugin.json              # Plugin manifest (prompts user for API keys)
├── mcp.json                     # Declares the bundled MCP server
├── skills/
│   └── coinvoyage-payments/
│       └── SKILL.md             # Integration guide + trigger description
├── mcp-server/                  # Source for @kingpeque/coinvoyage-mcp (npm)
│   ├── src/index.ts
│   ├── package.json
│   └── tsconfig.json
├── README.md
└── LICENSE
```

## Supported chains

Bitcoin, Solana, Ethereum, Optimism, Arbitrum, Base, BSC, Polygon, Sui — plus any ERC-20 / SPL / native token on these chains. See full chain ID reference in the `supported_chains` MCP tool.

## Pricing (CoinVoyage's, not this plugin's)

- 1.5% per successful payment
- 0% offramp
- Merchants can add a custom percentage fee on top
- This plugin is free and MIT-licensed. Volume discounts on CoinVoyage fees: `help@coinvoyage.io`.

## Security posture

- **No secrets in this repo.** Everything sensitive lives in your Claude Code config, injected into the MCP server at runtime.
- **Per-user keys.** Every builder uses their own CoinVoyage API key. Nothing is centrally hosted; there's no shared server to compromise.
- **Minimal network surface.** The MCP server only talks to `api.coinvoyage.io` (or your configured override).
- **HMAC-SHA256** authentication for privileged operations (SALE/REFUND/webhooks/fee claims).
- **Open source.** Read the MCP server source at [`mcp-server/src/index.ts`](mcp-server/src/index.ts) — it's under 300 lines.

## Local development

```bash
git clone https://github.com/KingPeque/coinvoyage-paykit
cd coinvoyage-paykit/mcp-server
npm install
npm run build
# Point your MCP client at ./mcp-server/dist/index.js with COINVOYAGE_API_KEY set
```

Run the skill locally by symlinking `skills/coinvoyage-payments/` into `~/.claude/skills/` (or installing the plugin in dev mode).

## Contributing

Issues and PRs welcome at https://github.com/KingPeque/coinvoyage-paykit/issues. Please don't commit API keys, secrets, or wallet addresses.

## License

MIT — see [LICENSE](LICENSE).

## Links

- CoinVoyage site: https://coinvoyage.io
- CoinVoyage docs: https://docs.coinvoyage.io
- Dashboard: https://dashboard.coinvoyage.io
- Support: `help@coinvoyage.io`
- This plugin's issues: https://github.com/KingPeque/coinvoyage-paykit/issues