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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.