CoinVello

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.

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.

List invoices, newest first, filterable by status, order_id or customer_email. Returns { object: 'list', data, has_more, next_cursor }.

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.

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.

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.

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"].

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.

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).

Takes no parameters.

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%).

Takes no parameters.

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).

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 }.

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.

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.

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.

Mid-market rates for supported assets against a fiat base (default USD). Indicative only; invoices lock their own rate at creation.

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.

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.