Docs · PyNukez
PyNukez SDK
python · v4.0.24
Reference
Classes and methods
Python Reference
The SDK reference below is organized by the objects you hold during a normal storage flow: quote, payment option, receipt, file URLs, attestation, and verification result.
Classes
Objects returned by the SDK
| Class | Description |
|---|---|
Nukez | Synchronous client. Requests storage, confirms payment, provisions lockers, manages files, and verifies receipts. |
AsyncNukez | Async client with method parity for event loops, FastAPI services, notebooks, and agents. |
StorageRequest | Typed x402 quote. Includes pay_req_id, selected leg fields, quote expiry, and payment_options for all gateway legs. |
PaymentOption | Parsed payment leg: chain/network, asset, amount, decimals, treasury address, and token contract/mint when applicable. |
Receipt | Confirmed payment receipt. Save receipt.id; it is the handle for provisioning, file operations, verification, and viewer URLs. |
FileUrls | Upload/download URLs and confirm_url returned by create_file(). In resumable mode it also carries the resumable_upload session-opener block plus the echoed expected_hash and expected_size_bytes pre-commitments. |
VerificationResult | Storage verification result from verify_storage(). |
AttestResult | Merkle/on-chain attestation result from attest(). |
ReceiptHashVerification | Receipt-object hash comparison from verify_receipt_hash(). |
Constructor
Local signing is optional.
keypair_path is a developer convenience for local envelope signing. You can pass an explicit signer instead, and Nukez does not custody or receive client keypair material.
| Parameter | Default | Use |
|---|---|---|
keypair_path | None | Optional path to a local Solana CLI keypair JSON. Used only for local Ed25519 envelope signing convenience. |
base_url | https://api.nukez.xyz | Gateway API URL. |
network | "devnet" | "devnet" or "mainnet-beta". |
timeout | None | HTTP request timeout in seconds. |
evm_private_key_path | None | Optional path to a local EVM private key file for secp256k1 envelope signing. |
evm_rpc_url | None | Reserved at the SDK layer. |
signing_key | None | Explicit Signer instance; use this instead of a local key file when you have a relay, HSM, wallet bridge, or custom signer. |
Methods
High-use client calls
| Method | Use |
|---|---|
request_storage(units=1, provider=None, pay_network=None, pay_asset=None) | Start the x402 payment flow and return available payment options. |
confirm_storage(pay_req_id, tx_sig, payment_chain=None, payment_asset=None) | Confirm an externally executed payment and return a receipt. |
provision_locker(receipt_id) | Create the locker associated with a confirmed receipt. |
create_file(receipt_id, filename, content_type="application/octet-stream", ttl_min=30, expected_hash=None, expected_size_bytes=None, upload_mode=None) | Create signed upload/download URLs for one file. expected_hash and expected_size_bytes pre-commit the object so confirm can verify it; upload_mode="resumable" additionally returns a resumable session opener for large objects. Files stored without an explicit content_type are typed as application/octet-stream. |
upload_bytes(upload_url, data, content_type=None) | Upload bytes; gateway short URLs are preflighted before large direct PUTs. |
upload_file_path(receipt_id, filepath, filename=None, content_type=None, ttl_min=30, confirm=True) | Upload one local file by path so the bytes never pass through agent context. Files at or above 256 MiB route automatically through upload_large_file(). |
upload_large_file(receipt_id, filepath, filename=None, content_type=None, chunk_bytes=8 MiB, confirm=True, auto_attest=False, threshold_bytes=256 MiB, on_progress=None) | Resumable direct-to-provider upload for files of any size: streaming digests, aligned chunks that resume from the provider's committed offset after interruptions, a whole-object CRC32C the provider verifies at finalize, and confirm routed synchronously below the threshold or through the gateway's asynchronous finalize job at or above it. |
bulk_upload_paths(receipt_id, sources, workers=6, ttl_min=30, confirm=True, auto_attest=False, attest_sync=False, on_progress=None) | Upload multiple local paths and optionally confirm hashes in one batch. Uploads run on six parallel workers by default; oversized files route through upload_large_file() automatically. |
finalize_upload_job(receipt_id, filenames, auto_attest=False, attest_sync=False, push_attestation=False) | Create the gateway's asynchronous confirm-and-attest job for already-uploaded files; the gateway streams each stored object and records its verified hash off the request path. |
get_job(job_id, receipt_id) | Poll a gateway job to its terminal state (complete, partial, or failed). |
download_bytes(download_url) | Download bytes from a signed URL. |
download_to_file(download_url, dest_path) | Stream a signed download to disk for larger files. |
confirm_file(receipt_id, filename, confirm_url=None) | Record the content hash for one uploaded file. The SDK signs a locker:write envelope at confirm time, bound to the confirm URL's query string and the canonical "{}" body. |
list_files(receipt_id) | List confirmed files in a locker. |
get_locker_record(receipt_id) | Fetch owner/operator/provider metadata. |
verify_storage(receipt_id) | Verify storage/content attestation state. This is the fast structural check: it trusts the manifest's recorded content hashes and does not re-read stored bytes. |
attest(receipt_id, sync=True) | Build the Merkle root and trigger attestation with a signed locker:attest envelope. sync=True waits by server-side polling of the enqueued job; a truthy merkle_root marks completion. |
recompute_verify(receipt_id, timeout=None) | Byte-level audit: the gateway re-downloads every stored file and re-hashes it, strictly read-only. The SDK signs the required locker:read envelope internally; latency scales with locker size. |
get_merkle_proof(receipt_id, filename) | Return a per-file inclusion proof. |
get_receipt(receipt_id) | Fetch the canonical stored receipt document. |
verify_receipt_hash(receipt_id) | Recompute and compare the receipt object's canonical hash. |
receipt_hash_matches(receipt_id) | Boolean convenience wrapper around verify_receipt_hash(). |
Storage providers
Storage Providers
Pass the arg name as the provider kwarg to request_storage(), get_provider_info(), and other methods that accept a provider.
| Provider | Arg name | Best for |
|---|---|---|
| Google Cloud Storage | "gcs" | General-purpose, large files, proof-of-storage |
| MongoDB | "mongodb" | Fast read/write, small context/state data (16 MB per-doc limit) |
| Filecoin | "filecoin" | Content-addressed decentralized storage |
| Arweave | "arweave" | Permanent, immutable storage |
| Firestore | "firestore" | Firebase document store (1 MB per-doc limit) |
| Storj | "storj" | S3-compatible, decentralized storage |
request = client.request_storage(units=1, provider="mongodb")For complete signatures and type fields, use the PyNukez GitHub reference as the package-level source of truth.