Primary task endpoint for storage, recall, verification, listing, and natural-language requests.
Docs · NukezAgent
NukezAgent
Hosted Agent
NukezAgent
The First Hosted Storage Specialist.
NukezAgent is the language- and platform-neutral integration surface: call one hosted endpoint with natural-language instructions to store, recall, list, and verify files. Use this page to locate the endpoint model, runnable examples, and framework adapter patterns.
Write flow response that returns envelopes for the owner client to sign locally.
Unsigned subscription quote endpoint. Payment execution stays outside the agent.
Service model
Managed delegation endpoint
Start from the hosted endpoint and the single delegate path. The service handles orchestration; your client owns identity, payment, and signing.
Service: https://agent.nukez.xyzNetwork: solana-mainnetSigning: Ed25519 owners or secp256k1 owners Primary endpoint:POST /v1/delegate Example task:{ "task": "Store this file named report.pdf. Bytes (base64): ..."}
Code notes
NukezAgent is a hosted managed storage service. Applications send natural-language tasks to one endpoint; the agent builds the required storage operations, returns receipts, and asks the client to sign only when owner authorization is required.
Payment happens at subscription time. Returning owners can go straight to signed /v1/delegate requests.
Request signature
Authenticate every private call
The canonical request signature is the first trust boundary. It proves the owner and binds method, path, nonce, timestamp, and body hash.
X-Nukez-Identity: <base58-pubkey-or-0x-address>X-Nukez-Nonce: <32-byte-random-hex>X-Nukez-Timestamp: <unix-seconds>X-Nukez-Signature: <signature> nukez-request:v1method=POSTpath=/v1/delegateidentity=<owner>nonce=<nonce_hex>timestamp=<unix_seconds>body_sha256=<sha256_hex_of_body>
Code notes
All identity-scoped endpoints require a request-level signature. The signature proves who is calling the service and prevents replay through a nonce and timestamp window. This is separate from write-envelope signing.
The server accepts timestamps within plus or minus 300 seconds. Replayed nonces and mismatched body hashes are rejected.
Client setup
Local signer and request helper
Keep the owner key local and reuse the same signed header builder across status, confirm, delegate, portal, and expansion calls.
pip install httpx pynacl base58 solders import base58, hashlib, httpx, json, os, timefrom nacl.signing import SigningKey FRONT_DOOR = "https://agent.nukez.xyz"_sk = SigningKey(bytes(json.load(open("/path/to/keypair.json"))[:32]))PUBKEY = base58.b58encode(_sk.verify_key.encode()).decode() def body_hash(body: dict | None) -> str: raw = b"" if body is None else json.dumps(body, separators=(",", ":"), sort_keys=True).encode() return hashlib.sha256(raw).hexdigest() def signed_headers(method: str, path: str, body: dict | None = None) -> dict: nonce = os.urandom(32).hex() timestamp = str(int(time.time())) msg = "\n".join([ "nukez-request:v1", f"method={method}", f"path={path}", f"identity={PUBKEY}", f"nonce={nonce}", f"timestamp={timestamp}", f"body_sha256={body_hash(body)}", ]) sig = base58.b58encode(_sk.sign(msg.encode()).signature).decode() return { "X-Nukez-Identity": PUBKEY, "X-Nukez-Nonce": nonce, "X-Nukez-Timestamp": timestamp, "X-Nukez-Signature": sig, }
Code notes
The notebook uses plain Python helpers around httpx and a local owner signer. The service never receives the private key. Helpers sign requests, issue GET/POST calls, and complete signing-needed responses.
secp256k1 owners follow the same canonical request contract with the corresponding wallet signature algorithm.
Subscription
Quote, pay externally, confirm
New owners activate service access once. The agent never moves funds; it only verifies the external transaction through a signed confirmation.
def agent_get(path: str): return httpx.get( FRONT_DOOR + path, headers=signed_headers("GET", path), timeout=60, ).json() def agent_post(path: str, body: dict | None = None, extra_headers: dict | None = None): headers = signed_headers("POST", path, body) if extra_headers: headers.update(extra_headers) return httpx.post(FRONT_DOOR + path, json=body, headers=headers, timeout=120).json() quote = httpx.get(FRONT_DOOR + "/v1/service/request").json()sol = next(o for o in quote["payment_options"] if o["network"] == "solana-mainnet") tx_sig = solana_transfer(sol["pay_to_address"], int(sol["amount"]))confirm = agent_post( "/v1/service/confirm", extra_headers={"X402-TX": tx_sig},)status = agent_get("/v1/status")
Code notes
NukezAgent does not charge per operation. A new owner requests subscription pricing, executes the selected payment outside the agent, then confirms the transaction with a signed request. Active owners skip this payment leg on later sessions.
The payment transaction proves the payer; the request signature proves the owner asking the service to activate access.
Storage write
Complete signing-needed writes
When a write needs owner authorization, sign the returned envelopes locally and submit the signatures back to the same delegate endpoint.
def sign_envelopes(envelopes: list[dict]) -> list[str]: signatures = [] for envelope in envelopes: payload = envelope.get("envelope_json") or json.dumps( envelope["envelope"], separators=(",", ":"), sort_keys=True ) signatures.append(base58.b58encode(_sk.sign(payload.encode()).signature).decode()) return signatures def complete_if_signing(result: dict) -> dict: while result.get("status") == "signing_needed": signatures = sign_envelopes(result["envelopes"]) result = agent_post("/v1/delegate", { "signing_request_id": result["signing_request_id"], "signatures": signatures, }) return result task = { "task": "Store this file named run-042.json. Bytes (base64): eyJvayI6dHJ1ZX0="}stored = complete_if_signing(agent_post("/v1/delegate", task))
Code notes
Write operations may return signing_needed. In that case, the agent has built operation envelopes, but the owner must sign them locally and submit the signatures back to the same delegate endpoint.
Same-content repeats may no-op idempotently. Different content for an existing filename is refused unless the task explicitly says overwrite or replace.
Read path
Recall, download, verify, list
Signed delegate requests cover retrieval and verification. Large file downloads use short-lived bearer tokens returned by the agent.
recall = agent_post("/v1/delegate", { "task": "Recall the file named run-042.json"}) if recall.get("download_token"): download = httpx.get(FRONT_DOOR + f"/v1/download/{recall['download_token']}", timeout=60) file_bytes = download.contentelse: file_bytes = recall["payload"].encode() verified = agent_post("/v1/delegate", { "task": "Verify storage for run-042.json"}) files = agent_post("/v1/delegate", { "task": "List my stored files"})
Code notes
Read-oriented delegation uses the same signed request helpers. Large recalls can return a one-time download token; verification returns a concise summary with structured evidence fields for the UI or agent runtime.
A null tx_signature can be normal while attestation is still in flight; do not treat that alone as verification failure.
Production behavior
Conflict, capacity, portal, returning owner
These rules make the surface predictable once it leaves a notebook: explicit overwrites, explicit expansion, portal reads, and short returning-owner flows.
Overwrite behavior:- "overwrite" or "replace": explicit update- "update": ambiguous; agent asks for clarification- default conflict: file_exists_different_content Capacity expansion:GET /v1/service/expand?units=NPOST /v1/service/expand/confirmbody: {"units": N, "tx_signature": "<tx_sig>"} Portal data:GET /v1/portal/filesGET /v1/portal/ops-logGET /v1/portal/usage Returning owner:signed POST /v1/delegate is sufficient
Code notes
The Agent guide defines a few important production rules: explicit overwrite semantics, signed capacity expansion, dashboard-oriented portal endpoints, and a shorter path for owners who already have active service access.
Default responses stay concise and do not include token_usage or tool_calls_made unless the conversation explicitly opts into metrics.