icpay-bucket
Python client for ICPay Bucket — on-chain encrypted file storage on the Internet Computer.
Canister: 6vbhm-nqaaa-aaaan-q6muq-cai · Version: 1.1.1
Docs: Package guide · API reference
Requires ic-py>=1.0.1 and cbor2>=5.4.2,<6 (pinned for query compatibility).
Install
pip install icpay-bucket
Quick start
from icpay_bucket import BucketClient
client = BucketClient(api_key="icp_cloud_…")
result = client.upload_file("icp", "/hello.txt", b"hello world\n", "text/plain")
if "err" in result:
raise RuntimeError(result["err"])
print(client.public_url("icp", "/hello.txt"))
print(client.list_files("icp", page=0, page_size=20))
client.delete_file("icp", "/hello.txt")
Authentication
| Caller | Access |
|---|---|
| Bucket owner (Internet Identity) | All methods |
| Read API key | list_files, download_file, get_file, file_exists, list_folder, search_files, get_file_metadata |
| Write API key | Upload, move, copy, tags, metadata, chunked upload |
| Delete API key | delete_file, bulk_delete_files |
Pass api_key= per call or set BucketClient(api_key=…).
API reference
All methods return {"ok": …} or {"err": "…"}.
Buckets
| Method | Auth |
|---|---|
get_bucket_price(capacity_gb) |
public |
create_bucket(name, capacity_gb, visibility="Public") |
owner |
get_bucket(bucket_id) |
owner |
list_buckets() |
owner |
get_bucket_cycle_status() |
public |
Upload
| Method | Auth |
|---|---|
upload_file(bucket_id, path, data, content_type, api_key?) |
write key / owner |
begin_file_upload(bucket_id, path, content_type, total_size, api_key?) |
write key / owner |
upload_file_chunk_indexed(upload_id, chunk_index, data) |
write key / owner |
complete_file_upload(upload_id, api_key?) |
write key / owner |
get_upload(upload_id) |
owner principal |
cancel_upload(upload_id) |
owner principal |
Read
| Method | Auth |
|---|---|
download_file(bucket_id, path, api_key?) |
read key / owner |
get_public_file_url(bucket_id, path) |
public |
list_files(bucket_id, page=0, page_size=20, api_key?) |
read key / owner |
get_file(bucket_id, path, api_key?) |
read key / owner |
file_exists(bucket_id, path, api_key?) |
read key / owner |
list_folder(bucket_id, prefix, page, page_size, api_key?) |
read key / owner |
search_files(bucket_id, search_query, page, page_size, api_key?) |
read key / owner |
get_file_metadata(bucket_id, path, api_key?) |
read key / owner |
public_url(bucket_name, path) |
local helper |
Write
| Method | Auth |
|---|---|
move_file(bucket_id, source_path, destination_path, api_key?) |
write key / owner |
copy_file(bucket_id, source_path, destination_path, api_key?) |
write key / owner |
delete_file(bucket_id, path, api_key?) |
delete key / owner |
set_file_tags(bucket_id, path, tags, api_key?) |
write key / owner |
set_file_metadata(bucket_id, path, metadata, api_key?) |
write key / owner |
Bulk (max 20)
| Method | Auth |
|---|---|
bulk_delete_files(bucket_id, paths, api_key?) |
delete key / owner |
bulk_move_files(bucket_id, operations, api_key?) |
write key / owner |
bulk_copy_files(bucket_id, operations, api_key?) |
write key / owner |
Bulk operations use {"source": "…", "destination": "…"} dicts.
Public CDN
https://6vbhm-nqaaa-aaaan-q6muq-cai.raw.icp0.io/cloud/{bucketName}{path}
Notes
- Paths must use allowed extensions — use
/file-copy.txt, not/file.txt.copy. get_upload/cancel_uploadneed the bucket owner's Internet Identity principal.
License
MIT
Metadata
Release files for icpay-bucket 1.1.1
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 |
|---|---|---|---|---|
| icpay_bucket-1.1.1.tar.gz | 7.3 kB | Without provenance | Details for icpay_bucket-1.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| icpay_bucket-1.1.1-py3-none-any.whl | Python 3 | none | any | Details for icpay_bucket-1.1.1-py3-none-any.whl |
Total release size: 14.7 kB
Release files / icpay_bucket-1.1.1.tar.gz
| Download URL | icpay_bucket-1.1.1.tar.gz |
|---|---|
| Size | 7.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
33c654c3b4d70d10e994e48de30f3f344066dd585221f38f6a2624328a9d2587
|
|
BLAKE2b-256 checksum How to use checksums |
c6325e790213d3478599e7dba3f8799a7f888c30633a732cbac895e4c26f6e66
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.6
|
Release files / icpay_bucket-1.1.1-py3-none-any.whl
| Download URL | icpay_bucket-1.1.1-py3-none-any.whl |
|---|---|
| Size | 7.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7c83142333c043402ddec92f9bf214423ac7609870d80a5759d28532faffaaf8
|
|
BLAKE2b-256 checksum How to use checksums |
0bc591271b84f25fb0f850ba4d4906dd68b40aec3965b36a515281a2f3db8b6b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.6
|
Security for icpay-bucket 1.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.