CoinVello
Non-custodial crypto payments: checkout sessions, invoices, webhooks and test payments. No KYC.
使うべきか
品質と安全性
ツール定義とプロトコルへの準拠に関する自動分析に基づいています。
コンテキストコスト
これは、サーバーのツールがモデルのコンテキストに読み込まれるたびに消費されるおおよそのトークン数です。数が多いほど、ほかのタスクに使える注意が減ります。
インストール
ワンクリックインストール
これを `claude_desktop_config.json` ファイルに追加してください:
{
"mcpServers": {
"coinvello": {
"command": "npx",
"args": [
"@coinvello/mcp"
]
}
}
}実行可能なパッケージ
0.1.4stdioリモートエンドポイント
https://mcp.coinvello.com/mcpstreamable-httpできること
ツール一覧
ツール（18）
🟡create_checkout_session(amount, currency, success_url, cancel_url, accepted_assets, ...)
Create a CoinVello hosted checkout session (an invoice plus a payment page at pay.coinvello.com). Redirect the customer to the returned `url`. Amounts are decimal strings. `currency` is an ISO code (USD, EUR...) or an asset id to price in crypto. Fulfil orders from the invoice.paid webhook, never from the redirect.
入力スキーマ
{
"type": "object",
"properties": {
"amount": {
"type": "string",
"pattern": "^-?\\d+(\\.\\d+)?$",
"description": "Total to charge, e.g. \"49.99\"."
},
"currency": {
"type": "string",
"description": "ISO 4217 code such as USD/EUR/GBP, or an asset id such as btc:bitcoin."
},
"success_url": {
"type": "string",
"format": "uri",
"description": "Where the hosted page sends the customer after payment."
},
"cancel_url": {
"type": "string",
"format": "uri"
},
"accepted_assets": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-z0-9]+:[a-z0-9]+$"
},
"description": "Assets the customer may pay with; defaults to all assets with an enabled wallet."
},
"order_id": {
"type": "string",
"maxLength": 128,
"description": "Your order reference; indexed and searchable."
},
"description": {
"type": "string",
"maxLength": 500
},
"customer": {
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email"
},
"name": {
"type": "string",
"maxLength": 200
},
"reference": {
"type": "string",
"maxLength": 128
}
},
"additionalProperties": false
},
"line_items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 200
},
"quantity": {
"type": "integer",
"minimum": 1
},
"unit_amount": {
"type": "string",
"pattern": "^-?\\d+(\\.\\d+)?$"
},
"description": {
"type": "string",
"maxLength": 500
},
"image_url": {
"type": "string",
"format": "uri"
}
},
"required": [
"name",
"quantity",
"unit_amount"
],
"additionalProperties": false
}
},
"redirect_on": {
"type": "string",
"enum": [
"confirming",
"paid"
],
"description": "When the hosted page redirects to success_url (default confirming)."
},
"expires_in": {
"type": "integer",
"minimum": 300,
"maximum": 86400,
"description": "Seconds until expiry (default 1800)."
},
"locale": {
"type": "string"
},
"branding": {
"type": "object",
"properties": {
"theme": {
"type": "string",
"enum": [
"light",
"dark",
"auto"
]
},
"logo_url": {
"type": "string",
"format": "uri"
},
"primary_color": {
"type": "string",
"pattern": "^#[0-9a-fA-F]{6}$"
},
"merchant_name": {
"type": "string",
"maxLength": 100
}
},
"additionalProperties": false
},
"collect_email": {
"type": "boolean"
},
"tax": {
"type": "object",
"properties": {
"amount": {
"$ref": "#/properties/line_items/items/properties/unit_amount"
},
"rate": {
"anyOf": [
{
"$ref": "#/properties/line_items/items/properties/unit_amount"
},
{
"type": "null"
}
]
},
"label": {
"anyOf": [
{
"type": "string",
"maxLength": 60
},
{
"type": "null"
}
]
},
"jurisdiction": {
"anyOf": [
{
"type": "string",
"maxLength": 20
},
{
"type": "null"
}
]
}
},
"required": [
"amount"
],
"additionalProperties": false,
"description": "The tax portion of the sale as you computed it, in the invoice currency and included in `amount` (e.g. {\"amount\":\"7.98\",\"rate\":\"0.19\",\"label\":\"VAT 19%\",\"jurisdiction\":\"DE\"}); copied to the records and exports. jurisdiction is a code you choose, never anything about the payer."
},
"metadata": {
"type": "object",
"additionalProperties": {
"type": "string",
"maxLength": 500
},
"description": "Up to 50 string key/value pairs returned on the object and in webhooks."
},
"idempotency_key": {
"type": "string",
"maxLength": 255,
"description": "Stable key per order so retries do not create duplicate sessions, e.g. order-123-checkout."
}
},
"required": [
"amount",
"currency",
"success_url"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢get_invoice(id)
Retrieve an invoice (inv_...) with its status, payment_options (address, amount, payment_uri, qr_payload) and paid summary. Use for polling or reconciliation. Accepts a checkout session id (cs_...) too and returns the session with the invoice expanded.
入力スキーマ
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "inv_... or cs_... id"
}
},
"required": [
"id"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢list_invoices(limit, cursor, status, order_id, customer_email, ...)
List invoices, newest first, filterable by status, order_id or customer_email. Returns { object: 'list', data, has_more, next_cursor }.
入力スキーマ
{
"type": "object",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Page size (default 20)."
},
"cursor": {
"type": "string",
"description": "next_cursor from the previous page."
},
"status": {
"type": "string",
"enum": [
"new",
"pending",
"confirming",
"paid",
"underpaid",
"overpaid",
"expired",
"cancelled",
"refund_requested"
]
},
"order_id": {
"type": "string"
},
"customer_email": {
"type": "string"
},
"created_gte": {
"type": "string",
"description": "RFC 3339 timestamp"
},
"created_lte": {
"type": "string",
"description": "RFC 3339 timestamp"
}
},
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢list_payments(limit, cursor, invoice_id, status, chain, ...)
List on-chain payments (pay_...) with tx_hash, confirmations, amount and status (detected, confirming, confirmed, failed). Filter by invoice_id, status, chain or tx_hash.
入力スキーマ
{
"type": "object",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Page size (default 20)."
},
"cursor": {
"type": "string",
"description": "next_cursor from the previous page."
},
"invoice_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"detected",
"confirming",
"confirmed",
"failed"
]
},
"chain": {
"type": "string",
"enum": [
"bitcoin",
"ethereum",
"base",
"arbitrum",
"optimism",
"polygon",
"bnb",
"avalanche",
"robinhood",
"solana",
"tron"
]
},
"tx_hash": {
"type": "string"
}
},
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}🟡create_wallet(type, chain, label, xpub, derivation_path, ...)
Register a receiving wallet the merchant controls. type=xpub for bitcoin (CoinVello derives a fresh address per invoice from the extended PUBLIC key); type=address for ethereum, base, arbitrum, optimism, polygon, bnb, avalanche, robinhood, solana, tron. Never pass a private key or seed phrase. The wallet is usable at once in live and test mode; addresses are validated strictly (format, checksum, network, no token contracts). For xpubs, show the returned first_address so the merchant can compare it with their wallet's first receive address. Signed-message verification (POST /wallets/{id}/verification then /verify) is optional and never required.
入力スキーマ
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"xpub",
"address"
]
},
"chain": {
"type": "string",
"enum": [
"bitcoin",
"ethereum",
"base",
"arbitrum",
"optimism",
"polygon",
"bnb",
"avalanche",
"robinhood",
"solana",
"tron"
]
},
"label": {
"type": "string",
"maxLength": 100
},
"xpub": {
"type": "string",
"description": "xpub/ypub/zpub (BTC), tpub/upub/vpub (testnets) or an output descriptor. Required when type=xpub."
},
"derivation_path": {
"type": "string",
"pattern": "^m(\\/\\d+'?)*$",
"description": "Account path such as m/84'/0'/0'. Inferred from the prefix when omitted."
},
"address_type": {
"type": "string",
"enum": [
"p2pkh",
"p2sh-p2wpkh",
"p2wpkh",
"p2tr"
]
},
"start_index": {
"type": "integer",
"minimum": 0
},
"address": {
"type": "string",
"description": "Checksummed EVM address, Solana pubkey or Tron address. Required when type=address."
},
"assets": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-z0-9]+:[a-z0-9]+$"
},
"description": "Assets accepted at this address, e.g. [\"usdc:polygon\",\"usdt:polygon\"]. Defaults to the native asset. Each must be listed by list_assets for the key's mode."
},
"enabled": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": {
"type": "string",
"maxLength": 500
},
"description": "Up to 50 string key/value pairs returned on the object and in webhooks."
}
},
"required": [
"type",
"chain",
"label"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢list_wallets(limit, cursor, chain, status)
List registered wallets with chain, type, status (active/verified/archived) and accepted assets. Use it to see which assets can be offered on an invoice.
入力スキーマ
{
"type": "object",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Page size (default 20)."
},
"cursor": {
"type": "string",
"description": "next_cursor from the previous page."
},
"chain": {
"type": "string",
"enum": [
"bitcoin",
"ethereum",
"base",
"arbitrum",
"optimism",
"polygon",
"bnb",
"avalanche",
"robinhood",
"solana",
"tron"
]
},
"status": {
"type": "string",
"enum": [
"active",
"verified",
"archived",
"unverified"
]
}
},
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}🟡create_webhook(url, events, description, enabled, metadata)
Register a webhook endpoint. The response contains `secret` (whsec_...) ONCE: store it as COINVELLO_WEBHOOK_SECRET. Live endpoints must be HTTPS; test endpoints may be http://localhost. Use events ["*"] for everything or a list such as ["invoice.paid","invoice.expired"].
入力スキーマ
{
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"events": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Event types or [\"*\"]. Common: invoice.paid, invoice.confirming, invoice.underpaid, invoice.overpaid, invoice.expired, payment.detected, checkout_session.completed."
},
"description": {
"type": "string",
"maxLength": 200
},
"enabled": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": {
"type": "string",
"maxLength": 500
},
"description": "Up to 50 string key/value pairs returned on the object and in webhooks."
}
},
"required": [
"url",
"events"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}🟡verify_webhook_signature(raw_body, signature_header, secret, tolerance_seconds, ignore_timestamp)
Verify a webhook delivery locally (no API call). Pass the exact raw request body, the CoinVello-Signature header (t=...,v1=...) and the endpoint secret (whsec_...). Implements the spec: HMAC-SHA256 over "<t>.<raw body>", 300 s tolerance, constant-time compare against any v1. Returns valid=true/false with the reason and the parsed event. Set ignore_timestamp=true when checking an old captured delivery.
入力スキーマ
{
"type": "object",
"properties": {
"raw_body": {
"type": "string",
"description": "Raw body bytes exactly as received (no re-serialisation)."
},
"signature_header": {
"type": "string",
"description": "Value of the CoinVello-Signature header."
},
"secret": {
"type": "string",
"description": "Endpoint secret whsec_..."
},
"tolerance_seconds": {
"type": "integer",
"minimum": 0
},
"ignore_timestamp": {
"type": "boolean",
"description": "Skip the replay-window check (only for inspecting historical deliveries)."
}
},
"required": [
"raw_body",
"signature_header",
"secret"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢get_credits_balance
Return the merchant's prepaid processing-credit balance: balance (= available + reserved, never negative), available (free to spend), reserved (estimated fees of open invoices paid with credits), low_balance_threshold, estimated_payments_remaining, auto_topup. There are no free live credits. 1 credit = $0.01 nominal; a confirmed payment consumes about 30 bps of its fiat value (floor 2, cap 2000).
入力スキーマ
{
"type": "object",
"properties": {},
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢list_credit_bundles
List purchasable credit bundles with USD price, price_per_credit and indicative crypto_prices per asset. Bigger bundles cost less per credit (effective rate ~0.30% down to <0.10%).
入力スキーマ
{
"type": "object",
"properties": {},
"$schema": "http://json-schema.org/draft-07/schema#"
}🟡create_credit_purchase(bundle_id, pay_asset, pay_chain, expires_in, metadata, ...)
Create a crypto credit purchase (cpu_...). Returns payment.payment_options with the address/amount to pay (CoinVello's operator wallet) and a hosted checkout_url. Credits are added when the payment confirms. Card purchases and automatic top-up are set up by the merchant in the dashboard, not through this tool. In test mode credits are free, so this is mainly for exercising the flow (pay it with simulate_test_payment).
入力スキーマ
{
"type": "object",
"properties": {
"bundle_id": {
"type": "string",
"description": "From list_credit_bundles, e.g. bnd_growth_15000."
},
"pay_asset": {
"type": "string",
"description": "Asset symbol to pay with, lowercase, e.g. usdt. Requires pay_chain. Omit for every option."
},
"pay_chain": {
"type": "string",
"enum": [
"bitcoin",
"ethereum",
"base",
"arbitrum",
"optimism",
"polygon",
"bnb",
"avalanche",
"robinhood",
"solana",
"tron"
]
},
"expires_in": {
"type": "integer",
"minimum": 600,
"maximum": 86400
},
"metadata": {
"type": "object",
"additionalProperties": {
"type": "string",
"maxLength": 500
},
"description": "Up to 50 string key/value pairs returned on the object and in webhooks."
},
"idempotency_key": {
"type": "string",
"maxLength": 255
}
},
"required": [
"bundle_id"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢list_records(limit, cursor, type, asset, chain, ...)
List the account's book of record, newest first: one immutable row per movement of value (payment_received, fee_prepaid, credit_purchase, refund_sent, fee_onchain, conversion, offramp_payout...) valued when it happened. Each record has `value` (market value at the block time in the reporting currency, rate and source included), `value_usd`, `contract_value` (what the customer owed at the invoice's locked rate), `tax`, the on-chain proof (tx_hash, block_height, addresses, explorer_url) and an invoice snapshot. `currency` re-values from value_usd at the historical rate. With a test key, rows created by simulate_test_payment appear only with include_simulated=true. Returns { object: 'list', data, has_more, next_cursor }.
入力スキーマ
{
"type": "object",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "Page size (default 20)."
},
"cursor": {
"type": "string",
"description": "next_cursor from the previous page."
},
"type": {
"type": "string",
"enum": [
"payment_received",
"payment_reversed",
"refund_sent",
"fee_prepaid",
"fee_onchain",
"credit_purchase",
"credit_adjustment",
"conversion",
"offramp_payout"
]
},
"asset": {
"type": "string",
"pattern": "^[a-z0-9]+:[a-z0-9]+$",
"description": "Records whose received, sent or fee leg is this asset."
},
"chain": {
"type": "string",
"enum": [
"bitcoin",
"ethereum",
"base",
"arbitrum",
"optimism",
"polygon",
"bnb",
"avalanche",
"robinhood",
"solana",
"tron"
]
},
"invoice_id": {
"type": "string"
},
"order_id": {
"type": "string"
},
"tx_hash": {
"type": "string"
},
"occurred_gte": {
"type": "string",
"description": "RFC 3339 timestamp; block time at or after."
},
"occurred_lte": {
"type": "string",
"description": "RFC 3339 timestamp; block time at or before."
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "Re-value `value` into this currency (default: the account's reporting currency)."
},
"include_simulated": {
"type": "boolean",
"description": "Test mode only: include rows created by simulate_test_payment, which the sandbox hides by default. Ignored with a live key."
}
},
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢get_records_summary(period_start, period_end, currency, timezone, group_by, ...)
Sales (invoiced at the locked rates), received_market_value (what the coins were worth when they landed), valuation_difference, tax_collected, refunds, fees_prepaid and credits_consumed, fees_onchain, network_fees, credit_purchases and net_received, with payment counts, over occurred_at in the given timezone and currency. period_start is inclusive and period_end exclusive (a date such as 2026-01-01, or a date-time). group_by returns the same totals per month, asset, chain, type or address in `groups`. With a test key, simulated rows count only with include_simulated=true.
入力スキーマ
{
"type": "object",
"properties": {
"period_start": {
"type": "string",
"description": "Inclusive, read in `timezone`: a date (2026-01-01) or a date-time."
},
"period_end": {
"type": "string",
"description": "Exclusive."
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"timezone": {
"type": "string",
"description": "IANA zone used to bucket occurred_at, e.g. Europe/Berlin. Default: the account's records timezone."
},
"group_by": {
"type": "string",
"enum": [
"month",
"asset",
"chain",
"type",
"address"
]
},
"include_simulated": {
"type": "boolean",
"description": "Test mode only: include rows created by simulate_test_payment, which the sandbox hides by default. Ignored with a live key."
}
},
"required": [
"period_start",
"period_end"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}🟡create_export(format, dataset, preset, period, timezone, ...)
Create an export of the records (default), another dataset, or `all` (the year-end package) for a period, or for the entire history when period is null or omitted. Returns the export object: small exports are already `ready` with `file` (name, content_type, bytes, sha256) and a signed `download_url` valid until `download_expires_at` (files are kept 7 days); while `queued` or `processing` call get_export. Vendor presets (quickbooks, xero, koinly, cointracker, coinledger) and journal need dataset=records and format=csv (otherwise 422). Verify the downloaded file against file.sha256. With a test key pass include_simulated=true to include simulated payments.
入力スキーマ
{
"type": "object",
"properties": {
"format": {
"type": "string",
"enum": [
"csv",
"xlsx",
"json"
]
},
"dataset": {
"type": "string",
"enum": [
"records",
"invoices",
"payments",
"refunds",
"sweeps",
"credit_ledger",
"credit_purchases",
"conversions",
"offramp_payouts",
"all"
],
"description": "Default records."
},
"preset": {
"type": "string",
"enum": [
"generic",
"journal",
"quickbooks",
"xero",
"koinly",
"cointracker",
"coinledger"
],
"description": "Column layout for the records dataset (default generic)."
},
"period": {
"anyOf": [
{
"type": "object",
"properties": {
"start": {
"type": "string",
"description": "Inclusive, e.g. 2026-07-01."
},
"end": {
"type": "string",
"description": "Exclusive, e.g. 2026-10-01."
}
},
"required": [
"start",
"end"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Read in `timezone`. Null or omitted exports the entire history."
},
"timezone": {
"type": "string",
"description": "IANA zone, e.g. America/New_York. Default: the account's records timezone."
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "Reporting currency of the value columns."
},
"include_simulated": {
"type": "boolean",
"description": "Test mode only: include rows created by simulate_test_payment, which the sandbox hides by default. Ignored with a live key."
},
"metadata": {
"type": "object",
"additionalProperties": {
"type": "string",
"maxLength": 500
},
"description": "Up to 50 string key/value pairs returned on the object and in webhooks."
},
"idempotency_key": {
"type": "string",
"maxLength": 255,
"description": "Stable key so a retry does not start a second export, e.g. records-2026-q3."
}
},
"required": [
"format"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}🟡get_export(id)
Retrieve an export (exp_...): status (queued, processing, ready, failed, expired), rows, file { name, content_type, bytes, sha256 }, download_url and download_expires_at, failure_reason. Poll after create_export until ready.
入力スキーマ
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "exp_... id from create_export"
}
},
"required": [
"id"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢get_rates(base, assets)
Mid-market rates for supported assets against a fiat base (default USD). Indicative only; invoices lock their own rate at creation.
入力スキーマ
{
"type": "object",
"properties": {
"base": {
"type": "string",
"description": "ISO 4217 code or asset id, default USD."
},
"assets": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-z0-9]+:[a-z0-9]+$"
},
"description": "Restrict to these asset ids."
}
},
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢list_assets(chain)
Every asset CoinVello accepts in the API key's mode: id (btc:bitcoin, usdc:polygon, eurc:base...), symbol, chain, kind (native/token), contract_address, decimals, required_confirmations, min_amount, testnet name and the wallet_type (xpub or address) needed to accept it. Tokens without a testnet contract (DAI, usdc:bnb, usdt on base/arbitrum/optimism/avalanche/solana, and the Bitcoin tokens wbtc/cbbtc/btcb) are live-only, so a test key does not list them.
入力スキーマ
{
"type": "object",
"properties": {
"chain": {
"type": "string",
"enum": [
"bitcoin",
"ethereum",
"base",
"arbitrum",
"optimism",
"polygon",
"bnb",
"avalanche",
"robinhood",
"solana",
"tron"
],
"description": "Filter by chain."
}
},
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}🟡simulate_test_payment(invoice_id, asset, amount, confirmations, tx_hash, ...)
Create a synthetic on-chain payment for an invoice (inv_) or credit purchase (cpu_) and run it through the real state machine and webhook pipeline. Test keys only. confirmations=0 -> payment.detected / invoice.pending; confirmations >= required -> invoice.paid. Use a smaller/larger amount to simulate underpaid/overpaid. Reuse tx_hash to advance the same payment.
入力スキーマ
{
"type": "object",
"properties": {
"invoice_id": {
"type": "string",
"description": "inv_... or cpu_..."
},
"asset": {
"type": "string",
"pattern": "^[a-z0-9]+:[a-z0-9]+$",
"description": "Which payment option to pay; defaults to the first accepted asset."
},
"amount": {
"type": "string",
"pattern": "^-?\\d+(\\.\\d+)?$",
"description": "Amount in the asset; defaults to the exact payment_options[].amount."
},
"confirmations": {
"type": "integer",
"minimum": 0,
"description": "Default 0 (detected only)."
},
"tx_hash": {
"type": "string"
},
"from_address": {
"type": "string"
},
"delay_seconds": {
"type": "integer",
"minimum": 0,
"maximum": 300
}
},
"required": [
"invoice_id"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}コミュニティ
エビデンス