icpay-bucket

Minimal client for ICPay Bucket — on-chain encrypted file storage on the Internet Computer.

pip install icpay-bucket

Quick start

from icpay_bucket import BucketClient

# Writes are authorized by a bucket API key (create it in the ICPay UI).
client = BucketClient(api_key="icp_cloud_…")

# Upload (single call, files up to ~1.85 MB)
result = client.upload_file(
    bucket_id="icp",
    path="/logo.webp",
    data=b"webp bytes…",
    content_type="image/webp",
)
if "err" in result:
    raise RuntimeError(result["err"])

# Public CDN URL — no call needed
url = client.public_url("icp", "/logo.webp")

# List files
listing = client.list_files("icp", page=0, page_size=20)
print([f["path"] for f in listing["ok"]["items"]])

# Delete with the API key
client.delete_file("icp", "/logo.webp")

API

• upload_file(bucket_id, path, data, content_type, api_key?) — returns {"ok": file_id} | {"err": …}.
• delete_file(bucket_id, path, api_key?) — returns {"ok": None} | {"err": …}.
• list_files(bucket_id, page, page_size) — paginated file list.
• download_file(bucket_id, path) — file bytes (public + private buckets).
• get_public_file_url(bucket_id, path) — canister-provided CDN URL.
• public_url(bucket_name, path) — CDN URL computed locally (no call).
• public_file_url(canister_id, bucket_name, path) — same, standalone.

Writes are authorized by a bucket API key. Reads on public buckets work for any caller.

License

MIT