Skip to main content

coinvello (Python)

Dependency-free client for the CoinVello API. Python 3.9+, stdlib urllib only.

pip install coinvello
from coinvello import CoinVello

cv = CoinVello(os.environ["COINVELLO_API_KEY"])  # cv_live_... or cv_test_...

invoice = cv.invoices.create(
    amount="49.99",
    currency="USD",
    accepted_assets=["btc:bitcoin", "usdt:tron"],
    order_id="WC-10042",
    success_url="https://shop.example.com/thanks",
    idempotency_key="order-10042-invoice",
)
print(invoice["hosted_url"])

Responses are plain dicts mirroring the JSON. Amounts are strings - use decimal.Decimal, never float.

Resources

cv.invoices (create, get, list, update, cancel, expire, list_payments) · cv.payments · cv.wallets (create, create_verification, verify, list_addresses) · cv.webhooks (CRUD, rotate_secret, test, list_deliveries, construct_event) · cv.credits (balance, bundles, purchase, get_purchase, list_purchases, ledger) · cv.rates · cv.conversions · cv.offramp · cv.checkout_sessions · cv.refunds · cv.events · cv.records (list, retrieve, summary) · cv.exports (create, list, retrieve, delete, download) · cv.assets · cv.test.simulate_payment.

Records and exports

Add tax={"amount": "7.98", "rate": "0.19", "label": "VAT 19%", "jurisdiction": "DE"} to cv.invoices.create(...) (a decimal string, already included in amount) and every payment lands in your book of record. Export last quarter to Excel:

exp = cv.exports.create(dataset="records", format="xlsx", period={"start": "2026-07-01", "end": "2026-10-01"},
                        idempotency_key="records-2026-q3")
while exp["status"] in ("queued", "processing"):  # ends as ready, failed or expired
    time.sleep(2)
    exp = cv.exports.retrieve(exp["id"])
if exp["status"] == "ready":
    open(exp["file"]["name"], "wb").write(cv.exports.download(exp["id"]))  # bytes

With a test key, rows from /test/simulate_* only appear when you pass include_simulated=True (to records.list, records.summary and exports.create). cv.records.summary(period_start="2026-01-01", period_end="2027-01-01", group_by="month") returns the totals; period_end is exclusive.

Webhooks

from coinvello import Webhooks, SignatureVerificationError

@app.post("/webhooks/coinvello")
def hook():
    try:
        event = Webhooks.construct_event(request.get_data(), request.headers.get("CoinVello-Signature"), SECRET)
    except SignatureVerificationError as e:
        abort(400, str(e))
    if event["type"] == "invoice.paid":
        mark_paid(event["data"]["object"]["order_id"])   # idempotent on event["id"]
    return "", 200

construct_event(raw_body, header, secret, tolerance=300) enforces the 5-minute window and compares each v1= HMAC-SHA256 with hmac.compare_digest (rotation-safe). Webhooks.sign_payload(body, secret) builds a header for tests.

Options

CoinVello(key, base_url="http://localhost:4242/v1", api_version="2026-10-01", timeout=30, max_retries=3)

Errors

CoinVelloError (type, code, param, request_id, http_status, details, retry_after) and subclasses AuthenticationError, PermissionError, InvalidRequestError, IdempotencyError, RateLimitError, CreditsError, ChainError, PartnerError, ApiError, ConnectionError, SignatureVerificationError.

Pagination

page = cv.invoices.list(status="paid", limit=100)   # dict with data / has_more / next_cursor
for inv in page.auto_paging_iter(): ...

Development

COINVELLO_API_KEY=cv_test_x COINVELLO_BASE_URL=http://localhost:4242/v1 python examples/create_invoice.py

Metadata

Release files for coinvello 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for coinvello 0.1.1
File Size Uploaded Provenance Actions
coinvello-0.1.1.tar.gz 13.3 kB Without provenance Details for coinvello-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for coinvello 0.1.1
File Interpreter ABI Platform Actions
coinvello-0.1.1-py3-none-any.whl Python 3 none any Details for coinvello-0.1.1-py3-none-any.whl

Total release size: 26.2 kB

Release files / coinvello-0.1.1.tar.gz

Download URL coinvello-0.1.1.tar.gz
Size 13.3 kB
Tags Source
SHA-256 checksum
How to use checksums
bd1a46f7afc46453e4736f70e5c2cae17cfab0247591a9333e4926b6fdb1dd3e
BLAKE2b-256 checksum
How to use checksums
d16c3ca097bcd9007916801f2f19ccd9b9594b9321143b5335f9e57b12eb390e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / coinvello-0.1.1-py3-none-any.whl

Download URL coinvello-0.1.1-py3-none-any.whl
Size 12.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8e29dba1b990ce1460739f1bc879d672bc73ce5eba9b8e0c1d90450d4a4e0344
BLAKE2b-256 checksum
How to use checksums
c1f726079ec956314184bc6ebb5caed3f6af76623991d23a7e884637a46fdd6c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for coinvello 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page