Docs · PyNukez
PyNukez SDK
python · v4.0.21
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(). |
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=None, ttl_min=30) | Create signed upload/download URLs for one file. |
upload_bytes(upload_url, data, content_type=None) | Upload bytes; gateway short URLs are preflighted before large direct PUTs. |
bulk_upload_paths(receipt_id, sources, workers=3, confirm=True) | Upload multiple local paths and optionally confirm hashes in one batch. |
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. |
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. |
attest(receipt_id, sync=True) | Build the Merkle root and trigger attestation. |
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.