Skip to main content

coinvello (Python)

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

pip install https://coinvello.com/downloads/sdk/coinvello-0.1.0-py3-none-any.whl
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.0

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.0
File Size Uploaded Provenance Actions
coinvello-0.1.0.tar.gz 13.3 kB Without provenance Details for coinvello-0.1.0.tar.gz

Built distribution (wheel)

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

Total release size: 26.3 kB

Release files / coinvello-0.1.0.tar.gz

Download URL coinvello-0.1.0.tar.gz
Size 13.3 kB
Tags Source
SHA-256 checksum
How to use checksums
55a618cd0805f21fc0c5feeb4aa666f83e779eb74490c74c893400d24ae295f6
BLAKE2b-256 checksum
How to use checksums
ef0281ac465ca2e4273d935f3df4361be549a3c95f5eb1d10582bbfcf52f5430
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.0-py3-none-any.whl

Download URL coinvello-0.1.0-py3-none-any.whl
Size 13.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6fd9d8160dfa3730725fa2f03183066dfdf5ff0321980c7851e55f35d6cb9773
BLAKE2b-256 checksum
How to use checksums
80e51c8eb754a52afd193dadfe82379b573bcf313ebd1ffd23e9712675b1171f
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.0

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