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
1 maintainer
Metadata
1 maintainer
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 | |
|---|---|---|---|
| icpay_bucket-1.1.1.tar.gz | 7.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| icpay_bucket-1.1.1-py3-none-any.whl | Python 3 | none | any | Details |
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
|
