{ "$schema": "https://docs.nukez.xyz/schemas/tools-v1.json", "schema_version": "1.1", "service": { "name": "Nukez", "base_url": "https://api.nukez.xyz", "discovery": "/.well-known/nukez.json", "openapi": "/openapi.json", "description": "Pay-once persistent storage with verifiable receipts + provider-opaque short URL byte transfer." }, "usage_guidance": { "when_to_use": "Use Nukez for persistent storage over HTTP with cryptographic receipts. No cloud credentials needed — just pay with Solana or EVM (x402) and start storing.", "best_for": "Agent-driven file storage, cross-session persistence, verifiable data provenance, multi-chain payment workflows, and any scenario where you want receipts without managing infrastructure.", "agent_note": "This is HTTP-first: no SDK required. You can operate entirely via HTTP requests + Solana or EVM signing.", "critical_guardrails": [ "If a valid receipt_id already exists in context, reuse it. Do not repurchase storage unless user explicitly requests a new purchase.", "In sandbox/proxied runtimes, prefer upload sessions and upload token flow instead of direct local-path uploads.", "When upload errors include details.recovery_hint and details.next_best_method, follow those fields directly." ] }, "auth_reference": { "public": { "description": "No auth headers required.", "tools": [ "nukez_request_storage", "nukez_confirm_storage", "nukez_get_receipt", "nukez_verify_receipt", "nukez_verify_storage", "nukez_get_attest_code" ] }, "signed_envelope": { "description": "Request-bound Ed25519 signature using payer key.", "headers": { "X-Nukez-Envelope": "base64url(canonical_json(envelope))", "X-Nukez-Signature": "base58(ed25519_sign(envelope_bytes))" }, "envelope_fields": [ "v", "locker_id", "receipt_id", "nonce", "iat", "exp", "ops", "method", "path", "body_sha256" ], "see": "/docs/AUTH_SIGNED_ENVELOPE.md" }, "signed_urls": { "description": "upload_url/download_url are provider-opaque short URLs (https://api.nukez.xyz/f/{token}) used for PUT/GET bytes.", "note": "If a short URL fails with 403/404, call GET /v1/lockers/{locker_id}/files/{filename} to refresh URLs. Verify token signatures with GET /v1/short-url/verify-key.", "verify_key": "/v1/short-url/verify-key", "format": "https://api.nukez.xyz/f/{ed25519_signed_token}" }, "verification_spec": { "name": "nukez-merkle-v1", "schema_version": "1.0", "status": "normative", "canonical_doc": "https://docs.nukez.xyz/docs/verify/merkle-v1.md", "machine_readable": "https://docs.nukez.xyz/specs/nukez-merkle-v1.json", "summary": "Canonical Merkle / attestation spec for third-party verification. Covers leaf hashing, sort order, parent formula, odd-level duplication, result_hash, att_code, inclusion proof verification, the historical Solana/Switchboard anchor format plus the Monad anchor format (the Monad bridge is specified but not currently operational in production), and a conformance test vector. Anchors that the gateway publishes itself are described by evidence_spec.", "important": "att_code is a nine-digit integer derived from result_hash, not merkle_root, and is NOT a security primitive. The authoritative values are result_hash, merkle_root, file entries, and on-chain anchors. merkle_root is the Ed25519-signed field and the value written to the on-chain SPL Memo; result_hash is a separate digest from which att_code derives." }, "evidence_spec": { "name": "nukez-evidence-v2", "schema_version": "2.0", "status": "normative", "machine_readable": "https://docs.nukez.xyz/specs/nukez-evidence-v2.json", "summary": "Normative description of the version-two evidence: the signed commitment envelope (RFC 8785 canonical JSON, SHA-256 statement digest, Ed25519 signature over a domain tag plus the digest), the compact statement written in an SPL Memo on Solana, the provider-neutral anchor object, the separate verification facts, the Solana Attestation Service schema nukez.content.v2, the evidence bundle, and the signing key list.", "important": "The anchor proves that the gateway's published key committed this exact snapshot on Solana at this slot, and, with the attestation service account, that the current commitment is readable on-chain at a predictable address. It does not prove that a third party inspected the files. Read the transaction from anchor.tx first. The switchboard_slot, switchboard_tx, and switchboard_feed fields are populated only for historical Switchboard anchors. Never label a solana_sas_v1 or solana_memo_v2 anchor as Switchboard." } }, "tools": [ { "name": "nukez_request_storage", "description": "Start the x402 payment flow. IMPORTANT: this endpoint may return HTTP 402 with a JSON body that contains payment instructions. Treat HTTP 402 here as an expected 'payment challenge', not a failure. Provider can be selected via body.provider when enabled.", "when_to_call": "When you need to purchase/provision new storage units.", "input_schema": { "type": "object", "properties": { "units": { "type": "integer", "minimum": 1, "default": 1, "description": "Number of storage units to purchase." }, "idempotency_key": { "type": "string", "description": "Optional idempotency key for safe retries (Idempotency-Key header)." }, "existing_receipt_id": { "type": "string", "description": "Sandbox guardrail input. If provided with execution_mode='sandbox', the API blocks repurchase unless explicit_purchase=true." }, "execution_mode": { "type": "string", "description": "Optional runtime hint. Use 'sandbox' for constrained app runtimes." }, "explicit_purchase": { "type": "boolean", "description": "Set true only when the user explicitly requests buying new storage." }, "provider": { "type": "string", "enum": [ "gcs", "mongodb", "storj", "arweave", "filecoin", "firestore" ], "description": "Optional storage provider selection. If omitted, server default is used." }, "pay_network": { "type": "string", "enum": [ "solana-mainnet", "monad-mainnet" ], "description": "Optional. Network to pay on. If omitted, server default is used." }, "pay_asset": { "type": "string", "enum": [ "SOL", "USDC", "USDT", "USDT0", "WETH", "BETA", "MON" ], "default": "SOL", "description": "Optional. Payment asset. Default: SOL." } }, "required": [ "units" ] }, "output_schema": { "type": "object", "properties": { "pay_req_id": { "type": "string" }, "pay_to_address": { "type": "string" }, "amount_sol": { "type": "number", "description": "Deprecated alias for amount when pay_asset=SOL. Prefer paid_amount." }, "paid_amount": { "type": "string", "description": "Chain-agnostic human-readable payment amount." }, "paid_raw": { "type": "string", "description": "Atomic units (lamports, wei, etc.)." }, "pay_asset": { "type": "string", "description": "Payment asset used (SOL, USDC, USDT, USDT0, WETH, BETA, MON)." }, "network": { "type": "string", "description": "Payment network (solana-mainnet, monad-mainnet)." }, "amount_lamports": { "type": "integer" }, "unit_price_usd": { "type": "number" }, "total_usd": { "type": "number" }, "sol_usd": { "type": "number" }, "value": {} }, "required": [ "paid_amount", "network", "pay_req_id", "pay_to_address", "pay_asset", "value" ] }, "http": { "method": "POST", "path": "/v1/storage/request", "content_type": "application/json", "headers": { "Idempotency-Key": "{idempotency_key} (optional)" }, "query_parameters": { "pay_network": "Optional. Filter pricing by network.", "pay_asset": "Optional. Filter pricing by asset." }, "expected_status": [ 402, 200 ] }, "auth": "public", "next_step": "Pay to pay_to_address for paid_amount using the specified pay_asset on the specified network, then call nukez_confirm_storage." }, { "name": "nukez_confirm_storage", "description": "Confirm payment and receive a permanent receipt_id. Preferred proof: send transaction signature/hash in the X402-TX header. X402-TX accepts both Solana signatures (base58, ~88 chars) and EVM transaction hashes (0x + 64 hex chars). Fallback for constrained clients: include tx_sig in the JSON body along with pay_req_id. One payment transaction buys one pay request: confirming a second pay request with the same transaction returns 409 PAYMENT_ALREADY_ALLOCATED, while retrying the same pay request is idempotent and returns the same receipt. The transaction must have been made for the quote: a transaction made before the quote existed, or long after it expired, returns 402 PAYMENT_OUTSIDE_QUOTE_WINDOW.", "when_to_call": "After sending payment to pay_to_address returned by nukez_request_storage.", "input_schema": { "type": "object", "properties": { "pay_req_id": { "type": "string" }, "tx_sig": { "type": "string", "description": "Transaction signature (Solana base58, ~88 chars) or EVM transaction hash (0x + 64 hex chars)." }, "operator_pubkey": { "type": "string", "description": "Optional. A key to bind as locker operator at confirm time. It must differ from the payer key." }, "payer_signature": { "type": "string", "description": "Optional today, and expected whenever operator_pubkey is sent. The payer's signature over the exact UTF-8 bytes nukez/confirm/v1|||, with a single hyphen in place of the operator when there is none. Solana payers send an Ed25519 signature in base58. EVM payers send an EIP-191 personal_sign signature in 0x hex. Enforcement is staged: unsigned requests still work while the gateway runs in shadow mode, and they return 401 CONFIRM_INTENT_REQUIRED once enforcement is on." } }, "required": [ "pay_req_id", "tx_sig" ], "additionalProperties": true }, "output_schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "receipt_id": { "type": "string" }, "receipt": { "type": "object", "properties": { "paid_amount": { "type": "string", "description": "Chain-agnostic human-readable amount paid." }, "paid_raw": { "type": "string", "description": "Atomic units (lamports, wei, etc.)." }, "pay_asset": { "type": "string", "description": "Payment asset (SOL, USDC, USDT, USDT0, WETH, BETA, MON)." }, "network": { "type": "string", "description": "Payment network." }, "slot": { "type": "integer", "description": "Solana only, null for EVM." }, "block_number": { "type": "integer", "description": "EVM only, null for Solana." }, "funding_authority": { "type": ["string", "null"], "description": "The account that funded the payment, as observed in the transaction. Evidence only." } } }, "idempotent": { "type": "boolean" }, "value": {} }, "required": [ "ok", "receipt_id", "value" ] }, "http": { "method": "POST", "path": "/v1/storage/confirm", "content_type": "application/json", "headers": { "X402-TX": "{tx_sig} (preferred; Solana base58 signature or EVM 0x-prefixed tx hash; optional if tx_sig is provided in JSON body)" }, "expected_status": [ 200, 401, 402, 409, 422 ] }, "auth": "public", "error_handling": { "tx_not_found": "Transaction not yet propagated; retry with exponential backoff.", "payment_verification_failed": "Confirm tx paid enough; retry only if you suspect RPC lag.", "PAYMENT_ALREADY_ALLOCATED": "409. This transaction already paid for a different pay request. Each payment buys one request. Do not retry with the same transaction. Pay the new quote with a new transaction.", "PAYMENT_OUTSIDE_QUOTE_WINDOW": "402. The transaction was not made for this quote. Request a quote first, pay it, and then confirm.", "PAYMENT_OPTION_NOT_IN_QUOTE": "422. The asset that was paid is not an option in this quote, for example SOL against a quote that did not offer SOL. Request a new quote or pay with a listed option.", "CONFIRM_INTENT_REQUIRED": "401, only when enforcement is on. operator_pubkey was sent without payer_signature. The error detail carries sign_this, which is the exact text to sign.", "CONFIRM_INTENT_INVALID": "401, only when enforcement is on. payer_signature did not verify against the payer key. Sign the sign_this text from the error detail and retry." }, "next_step": "Call nukez_signed_provision with receipt_id to create a locker." }, { "name": "nukez_signed_provision", "description": "Provision a locker from a confirmed receipt. Returns locker_id and a manifest describing the file API surface. Requires signed envelope with ops ['locker:provision'].", "when_to_call": "Once per receipt_id (safe to retry).", "input_schema": { "type": "object", "properties": { "receipt_id": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Optional tags" }, "value": { "$ref": "#/components/schemas/ProvisionRequest" }, "signed_envelope": { "type": "string", "description": "Input used to populate an HTTP header." }, "signed_envelope_signature": { "type": "string", "description": "Input used to populate an HTTP header." } }, "required": [ "receipt_id", "value" ] }, "output_schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "space": { "type": "object", "description": "Locker manifest (runtime affordances)", "additionalProperties": true }, "value": {} }, "required": [ "ok", "space", "value" ] }, "http": { "method": "POST", "path": "/v1/storage/signed_provision", "content_type": "application/json", "headers": { "X-Nukez-Envelope": "{signed_envelope}", "X-Nukez-Signature": "{signed_envelope_signature}" }, "expected_status": [ 200 ] }, "auth": "signed_envelope", "required_ops": [ "locker:provision" ], "next_step": "Use space.file_api paths (or the standard /v1/lockers/{locker_id}/files endpoints) to create/list/get/delete files." }, { "name": "nukez_create_file", "description": "Create (or update) a file entry and mint time-limited short URLs for upload/download. Upload bytes via HTTP PUT to upload_url.", "when_to_call": "When you need to upload new bytes or update an existing file.", "input_schema": { "type": "object", "properties": { "locker_id": { "type": "string" }, "filename": { "type": "string", "description": "Optional. If omitted, server generates a filename." }, "content_type": { "type": "string", "description": "Optional MIME type. If provided, you MUST use the same Content-Type in the PUT to upload_url." }, "ttl_min": { "type": "integer", "minimum": 1, "maximum": 60, "default": 30, "description": "Signed URL TTL in minutes." }, "value": { "$ref": "#/components/schemas/CreateFileRequest" } }, "required": [ "locker_id", "value" ] }, "output_schema": { "type": "object", "properties": { "locker_id": { "type": "string" }, "filename": { "type": "string" }, "upload_url": { "type": "string" }, "download_url": { "type": "string" }, "upload_headers": { "type": "object", "additionalProperties": { "type": "string" } }, "urls_expire_in_sec": { "type": "integer" }, "value": {} }, "required": [ "download_url", "filename", "locker_id", "upload_url", "value" ] }, "http": { "method": "POST", "path": "/v1/lockers/{locker_id}/files", "content_type": "application/json", "expected_status": [ 200 ] }, "auth": "signed_envelope", "required_ops": [ "locker:write" ], "next_step": "PUT raw bytes to upload_url, including any upload_headers, and matching Content-Type if content_type was locked." }, { "name": "nukez_create_files_batch", "description": "Create multiple file entries and mint short upload/download URLs in one call.", "when_to_call": "When uploading multiple files (mixed MIME types) and you want one signed request to return all URLs.", "input_schema": { "type": "object", "properties": { "locker_id": { "type": "string" }, "ttl_min": { "type": "integer", "minimum": 1, "maximum": 1440, "default": 30 }, "files": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "properties": { "filename": { "type": "string" }, "content_type": { "type": "string" }, "expected_hash": { "type": "string" } } } }, "value": { "$ref": "#/components/schemas/BatchCreateFileRequest" } }, "required": [ "files", "locker_id", "value" ] }, "output_schema": { "type": "object", "properties": { "locker_id": { "type": "string" }, "file_count": { "type": "integer" }, "urls_expire_in_sec": { "type": "integer" }, "files": { "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string" }, "upload_url": { "type": "string" }, "download_url": { "type": "string" }, "content_type": { "type": "string" } }, "required": [ "filename", "upload_url", "download_url" ] } }, "value": {} }, "required": [ "files", "locker_id", "value" ] }, "http": { "method": "POST", "path": "/v1/lockers/{locker_id}/files/batch", "content_type": "application/json", "expected_status": [ 200 ] }, "auth": "signed_envelope", "required_ops": [ "locker:write" ], "next_step": "Upload bytes to each returned upload_url (parallelizable), then confirm hashes via /v1/files/confirm-batch." }, { "name": "nukez_get_file_urls", "description": "Mint fresh short URLs for an existing file (download and optionally upload).", "when_to_call": "When a previously minted short URL expired, or before downloading/updating an existing file.", "input_schema": { "type": "object", "properties": { "locker_id": { "type": "string" }, "filename": { "type": "string" }, "ttl_min": { "type": "integer", "minimum": 1, "maximum": 60, "default": 30 } }, "required": [ "filename", "locker_id" ] }, "output_schema": { "type": "object", "properties": { "locker_id": { "type": "string" }, "filename": { "type": "string" }, "upload_url": { "type": "string" }, "download_url": { "type": "string" }, "urls_expire_in_sec": { "type": "integer" }, "value": {} }, "required": [ "download_url", "filename", "locker_id", "value" ] }, "http": { "method": "GET", "path": "/v1/lockers/{locker_id}/files/{filename}?ttl_min={ttl_min}", "expected_status": [ 200 ] }, "auth": "signed_envelope", "required_ops": [ "locker:read" ] }, { "name": "nukez_list_files", "description": "List file metadata in a locker (filenames, content_type, timestamps).", "when_to_call": "When you need to discover what files exist in a locker.", "input_schema": { "type": "object", "properties": { "locker_id": { "type": "string" } }, "required": [ "locker_id" ] }, "output_schema": { "type": "object", "properties": { "locker_id": { "type": "string" }, "file_count": { "type": "integer" }, "files": { "type": "array", "items": { "type": "object" } }, "value": {} }, "required": [ "files", "locker_id", "value" ] }, "http": { "method": "GET", "path": "/v1/lockers/{locker_id}/files", "expected_status": [ 200 ] }, "auth": "signed_envelope", "required_ops": [ "locker:list" ] }, { "name": "nukez_delete_file", "description": "Delete a file from a locker.", "when_to_call": "When you need to remove a stored object.", "input_schema": { "type": "object", "properties": { "locker_id": { "type": "string" }, "filename": { "type": "string" } }, "required": [ "filename", "locker_id" ] }, "output_schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "locker_id": { "type": "string" }, "filename": { "type": "string" }, "value": {} }, "required": [ "value" ] }, "http": { "method": "DELETE", "path": "/v1/lockers/{locker_id}/files/{filename}", "expected_status": [ 200 ] }, "auth": "signed_envelope", "required_ops": [ "locker:write" ] }, { "name": "nukez_get_receipt", "description": "Fetch a receipt by receipt_id.", "when_to_call": "When you need to audit or prove payment.", "input_schema": { "type": "object", "properties": { "receipt_id": { "type": "string" } }, "required": [ "receipt_id" ] }, "output_schema": { "type": "object", "additionalProperties": true, "properties": { "paid_amount": { "type": "string", "description": "Chain-agnostic human-readable amount paid." }, "paid_raw": { "type": "string", "description": "Atomic units (lamports, wei, etc.)." }, "pay_asset": { "type": "string", "description": "Payment asset (SOL, USDC, USDT, USDT0, WETH, BETA, MON)." }, "network": { "type": "string", "description": "Payment network." }, "slot": { "type": "integer", "description": "Solana only, null for EVM." }, "block_number": { "type": "integer", "description": "EVM only, null for Solana." }, "value": {} }, "required": [ "value" ] }, "http": { "method": "GET", "path": "/v1/receipts/{receipt_id}", "expected_status": [ 200 ] }, "auth": "public" }, { "name": "nukez_verify_receipt", "description": "Verify a receipt signature / integrity.", "when_to_call": "When you need strong confidence the receipt is authentic.", "input_schema": { "type": "object", "properties": { "receipt_id": { "type": "string" } }, "required": [ "receipt_id" ] }, "output_schema": { "type": "object", "additionalProperties": true, "properties": { "value": {} }, "required": [ "value" ] }, "http": { "method": "GET", "path": "/v1/receipts/{receipt_id}/verify", "expected_status": [ 200 ] }, "auth": "public" }, { "name": "nukez_verify_storage", "description": "Recompute stored object's sha256 and return a signed integrity certificate for the default payload.bin (legacy storage object).", "when_to_call": "When you need verifiable integrity for legacy payload.bin workflows.", "input_schema": { "type": "object", "properties": { "receipt_id": { "type": "string" }, "value": { "title": "Payload" } }, "required": [ "receipt_id", "value" ] }, "output_schema": { "type": "object", "additionalProperties": true, "properties": { "received_amount": { "type": "string", "description": "Chain-agnostic human-readable amount received." }, "received_raw": { "type": "string", "description": "Atomic units received (lamports, wei, etc.)." }, "pay_asset": { "type": "string", "description": "Payment asset verified (SOL, USDC, USDT, USDT0, WETH, BETA, MON)." }, "verified": { "type": "boolean", "description": "Unchanged historical meaning: an attestation record exists and is not pending. It does not say that the record is anchored on-chain." }, "anchor": { "type": ["object", "null"], "description": "Provider-neutral on-chain anchor: type (solana_sas_v1, solana_memo_v2, or switchboard_v2 for historical records), chain, tx, slot, signer, statement_digest, snapshot_id, payload, and sas when an attestation account exists. Read the transaction from anchor.tx first. Null when the record has no on-chain anchor." }, "verification": { "type": "object", "description": "Separate facts: commitment_computed, signature_valid, anchor_submitted, anchor_confirmed, anchor_finalized, payment_verified, bytes_checked, and witness. Each value is passed, failed, not_checked, or unavailable. To say that a record is anchored on-chain, require anchor_confirmed to be passed." }, "value": {} }, "required": [ "value" ] }, "http": { "method": "POST", "path": "/v1/storage/verify", "content_type": "application/json", "expected_status": [ 200 ] }, "auth": "public" }, { "name": "nukez_get_attest_code", "description": "Get the attestation code for a receipt. att_code is a nine-digit integer derived from result_hash (strip the sha256: prefix, take the first 12 hex characters, parse them as an integer, and take that value modulo 1,000,000,000). It is not a hex string and it does not derive from merkle_root. It is a compact display/oracle fingerprint, not a security primitive; the full result_hash is authoritative. If no attestation exists yet, this returns 400 with a hint to compute one via POST /v1/storage/attest, which requires a payer-signed envelope with the locker:attest operation.", "when_to_call": "After an attestation has been computed for the receipt, or if the receipt already has a result_hash.", "input_schema": { "type": "object", "properties": { "receipt_id": { "type": "string" } }, "required": [ "receipt_id" ] }, "output_schema": { "type": "object", "properties": { "receipt_id": { "type": "string" }, "result_hash": { "type": "string" }, "att_code": { "type": "integer", "description": "Nine-digit integer derived from result_hash (first 12 hex chars of the bare hash, parsed as an integer, modulo 1,000,000,000). Display/oracle value only — not a security primitive." }, "anchor": { "type": ["object", "null"], "description": "Provider-neutral on-chain anchor for the latest attestation. The switchboard_slot and switchboard_tx fields next to it are populated only for historical Switchboard anchors." }, "value": {} }, "required": [ "value" ] }, "http": { "method": "GET", "path": "/v1/attest-code?receipt_id={receipt_id}", "expected_status": [ 200, 400 ] }, "auth": "public" }, { "name": "nukez_start_upload_session", "description": "Start a sandbox upload session and mint a session-scoped upload token. Use this for app-sandbox uploads where direct file paths are restricted.", "when_to_call": "When uploading attachments from sandboxed runtimes and you already have locker_id + receipt_id.", "input_schema": { "type": "object", "properties": { "locker_id": { "type": "string" }, "receipt_id": { "type": "string" }, "files": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "properties": { "filename": { "type": "string" }, "content_type": { "type": "string" }, "expected_size_bytes": { "type": "integer" }, "expected_sha256": { "type": "string" } }, "required": [ "filename" ] } }, "upload_token_ttl_sec": { "type": "integer", "minimum": 60, "maximum": 86400 } }, "required": [ "locker_id", "receipt_id", "files" ] }, "output_schema": { "type": "object", "properties": { "session_id": { "type": "string" }, "upload_token": { "type": "string" }, "endpoints": { "type": "object" }, "viewer_url": { "type": "string" }, "ui": { "type": "object" }, "contract": { "type": "object" } }, "required": [ "session_id", "upload_token", "viewer_url", "ui", "contract" ] }, "http": { "method": "POST", "path": "/v1/lockers/{locker_id}/upload-sessions", "content_type": "application/json", "expected_status": [ 200 ] }, "auth": "signed_envelope", "required_ops": [ "locker:write" ], "next_step": "Upload bytes using nukez_append_upload_session_part, then call nukez_finalize_upload_session." }, { "name": "nukez_append_upload_session_part", "description": "Append one base64 chunk to a file inside an upload session.", "when_to_call": "After nukez_start_upload_session for each file chunk.", "input_schema": { "type": "object", "properties": { "session_id": { "type": "string" }, "file_id": { "type": "string" }, "part_no": { "type": "integer", "minimum": 0 }, "payload_b64": { "type": "string" }, "is_last": { "type": "boolean", "default": false } }, "required": [ "session_id", "file_id", "part_no", "payload_b64" ] }, "output_schema": { "type": "object", "properties": { "session_id": { "type": "string" }, "file_id": { "type": "string" }, "bytes_received": { "type": "integer" }, "part_count": { "type": "integer" } }, "required": [ "session_id", "file_id" ] }, "http": { "method": "POST", "path": "/v1/upload-sessions/{session_id}/files/{file_id}/parts", "content_type": "application/json", "expected_status": [ 200 ] }, "auth": "upload_session_token_or_signed_envelope" }, { "name": "nukez_get_upload_session", "description": "Get upload session status and per-file state. Returns viewer_url + UI contract.", "when_to_call": "To poll upload progress until terminal status.", "input_schema": { "type": "object", "properties": { "session_id": { "type": "string" } }, "required": [ "session_id" ] }, "output_schema": { "type": "object", "properties": { "session_id": { "type": "string" }, "status": { "type": "string" }, "terminal": { "type": "boolean" }, "viewer_url": { "type": "string" }, "ui": { "type": "object" }, "contract": { "type": "object" } }, "required": [ "session_id", "status", "terminal", "viewer_url", "ui", "contract" ] }, "http": { "method": "GET", "path": "/v1/upload-sessions/{session_id}", "expected_status": [ 200 ] }, "auth": "upload_session_token_or_signed_envelope" }, { "name": "nukez_finalize_upload_session", "description": "Finalize an upload session (assemble parts, verify upload integrity, and emit viewer contract).", "when_to_call": "After all chunks have been appended for all files.", "input_schema": { "type": "object", "properties": { "session_id": { "type": "string" }, "file_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "session_id" ] }, "output_schema": { "type": "object", "properties": { "session_id": { "type": "string" }, "status": { "type": "string" }, "terminal": { "type": "boolean" }, "result": { "type": "object" }, "viewer_url": { "type": "string" }, "ui": { "type": "object" }, "contract": { "type": "object" } }, "required": [ "session_id", "status", "terminal", "viewer_url", "ui", "contract" ] }, "http": { "method": "POST", "path": "/v1/upload-sessions/{session_id}/finalize", "content_type": "application/json", "expected_status": [ 200 ] }, "auth": "upload_session_token_or_signed_envelope" }, { "name": "nukez_get_viewer", "description": "Return a viewer-first payload for locker or file display. Always returns viewer_url + button contract.", "when_to_call": "When the user asks to view locker contents or a specific file.", "input_schema": { "type": "object", "properties": { "locker_id": { "type": "string" }, "receipt_id": { "type": "string" }, "filename": { "type": "string" } }, "required": [ "locker_id" ] }, "output_schema": { "type": "object", "properties": { "viewer_url": { "type": "string" }, "ui": { "type": "object" }, "contract": { "type": "object" } }, "required": [ "viewer_url", "ui", "contract" ] }, "http": { "method": "GET", "path": "/v1/lockers/{locker_id}/viewer", "expected_status": [ 200 ] }, "auth": "signed_envelope", "required_ops": [ "locker:read" ] }, { "name": "nukez_get_short_url_verify_key", "description": "Get the Ed25519 public key used to verify short URL tokens.", "when_to_call": "When independently validating that a short URL token was issued by Nukez.", "input_schema": { "type": "object", "properties": {} }, "http": { "method": "GET", "path": "/v1/short-url/verify-key", "expected_status": [ 200 ] }, "auth": "public", "output_hints": [ "verify_key_hex", "algorithm" ] }, { "name": "nukez_get_merkle_proof", "description": "Get a merkle inclusion proof for a specific file. Proves the file is part of the attested merkle tree without needing all other files. Walk the proof to independently verify: start with leaf_hash, for each step if position=='right' hash=SHA256(current+step.hash) else hash=SHA256(step.hash+current). Final hash must equal merkle_root.", "when_to_call": "When you need to verify a single file's membership in the attested merkle tree.", "input_schema": { "type": "object", "properties": { "receipt_id": { "type": "string", "description": "Receipt ID for the locker" }, "filename": { "type": "string", "description": "Name of the file to prove inclusion for" } }, "required": ["receipt_id", "filename"] }, "output_schema": { "type": "object", "properties": { "receipt_id": { "type": "string" }, "filename": { "type": "string" }, "leaf_hash": { "type": "string", "description": "SHA256 hash of the leaf node" }, "leaf_index": { "type": "integer", "description": "Position in sorted file list" }, "merkle_root": { "type": "string", "description": "Attested merkle root (sha256:...)" }, "proof": { "type": "array", "items": { "type": "object", "properties": { "hash": { "type": "string" }, "position": { "type": "string", "enum": ["left", "right"] } } }, "description": "Sibling hash steps from leaf to root" }, "tree_depth": { "type": "integer" }, "file_count": { "type": "integer" }, "file_entry": { "type": "object", "properties": { "filename": { "type": "string" }, "size_bytes": { "type": "integer" }, "content_hash": { "type": "string" } } }, "schema_version": { "type": "string" }, "switchboard": { "type": "object", "description": "Populated only for historical Switchboard anchors. Read anchor first.", "properties": { "slot": { "type": "integer" }, "tx": { "type": "string" } } }, "anchor": { "type": ["object", "null"], "description": "Provider-neutral on-chain anchor. type is solana_sas_v1, solana_memo_v2, or switchboard_v2 for historical records. Read the transaction from anchor.tx and the slot from anchor.slot. Null when the record has no on-chain anchor." } }, "required": ["receipt_id", "filename", "leaf_hash", "merkle_root", "proof"] }, "http": { "method": "GET", "path": "/v1/storage/merkle-proof?receipt_id={receipt_id}&filename={filename}", "expected_status": [200] }, "auth": "public", "next_step": "Walk the proof path to verify: start with leaf_hash, apply each sibling step, confirm final hash equals merkle_root." }, { "name": "nukez_confirm_upload", "description": "Confirm a file upload: the gateway downloads the stored bytes, computes their SHA-256, and records it in the manifest. Call after uploading bytes to upload_url. Uploads that went through the gateway proxy (?proxy=1) already have their hash recorded (reported via the X-Nukez-Content-Hash-Recorded response header); uploads that followed the 307 redirect must still be confirmed (the redirect carries X-Nukez-Confirm-Required: true). receipt_id and filename travel as QUERY parameters, and the POST body is the literal two characters {} — the signed envelope binds the method, path, query string, and the canonical body \"{}\", and the envelope's receipt_id must match the query receipt_id. Sign the envelope at confirm time, after the upload finishes, because the gateway rejects envelopes older than 300 seconds. Enforcement of the envelope is being rolled out in stages, but the signed request is the contract.", "when_to_call": "After uploading bytes to upload_url, especially for redirect-path uploads, sandbox uploads, or when explicit hash verification is needed.", "input_schema": { "type": "object", "properties": { "receipt_id": { "type": "string", "description": "Receipt ID for the locker" }, "filename": { "type": "string", "description": "Filename to confirm (as used in create_file)" } }, "required": ["receipt_id", "filename"] }, "output_schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "filename": { "type": "string" }, "size_bytes": { "type": "integer" }, "content_hash": { "type": "string", "description": "SHA-256 hash of the uploaded content (sha256:... prefixed)" } }, "required": ["ok", "filename"] }, "http": { "method": "POST", "path": "/v1/files/confirm?receipt_id={receipt_id}&filename={filename}", "content_type": "application/json", "body_note": "Send the literal canonical body {} (two characters). The envelope's body_sha256 must be the SHA-256 of exactly those two bytes.", "expected_status": [200] }, "auth": "signed_envelope", "required_ops": ["locker:write"] }, { "name": "nukez_add_operator", "description": "Add an Ed25519 operator key to a locker. Operators can perform file operations (read, write, list) on behalf of the locker owner. Only the locker owner can add operators. Useful for cross-chain delegation (e.g., EVM owner delegates to an Ed25519 operator for file operations).", "when_to_call": "When you need to delegate file access to another Ed25519 key.", "input_schema": { "type": "object", "properties": { "locker_id": { "type": "string" }, "pubkey": { "type": "string", "description": "Ed25519 public key (base58) to add as an operator" } }, "required": ["locker_id", "pubkey"] }, "output_schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "locker_id": { "type": "string" }, "operator_ids": { "type": "array", "items": { "type": "string" }, "description": "Updated list of all operator public keys" } }, "required": ["ok", "operator_ids"] }, "http": { "method": "POST", "path": "/v1/lockers/{locker_id}/operators", "content_type": "application/json", "expected_status": [200] }, "auth": "signed_envelope", "required_ops": ["locker:admin"], "note": "Only the locker owner (payer key) can add operators. Operators themselves cannot add other operators." }, { "name": "nukez_remove_operator", "description": "Remove an operator key from a locker. Only the locker owner can remove operators.", "when_to_call": "When you need to revoke an operator's access to a locker.", "input_schema": { "type": "object", "properties": { "locker_id": { "type": "string" }, "pubkey": { "type": "string", "description": "Ed25519 public key (base58) of the operator to remove" } }, "required": ["locker_id", "pubkey"] }, "output_schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "locker_id": { "type": "string" }, "operator_ids": { "type": "array", "items": { "type": "string" }, "description": "Updated list of remaining operator public keys" } }, "required": ["ok"] }, "http": { "method": "DELETE", "path": "/v1/lockers/{locker_id}/operators/{pubkey}", "expected_status": [200] }, "auth": "signed_envelope", "required_ops": ["locker:admin"] }, { "name": "nukez_get_verification_bundle", "description": "Get a self-contained verification bundle with payment proof, content proof, verification algorithm spec, and DIY verification steps. No authentication required.", "when_to_call": "When you need a portable, self-contained proof package for auditing or sharing.", "input_schema": { "type": "object", "properties": { "receipt_id": { "type": "string", "description": "Receipt ID to generate verification bundle for" } }, "required": ["receipt_id"] }, "output_schema": { "type": "object", "properties": { "receipt_id": { "type": "string" }, "payment_proof": { "type": "object", "description": "On-chain payment evidence" }, "content_proof": { "type": "object", "description": "Merkle root + file hashes" }, "verification_algorithm": { "type": "object", "description": "Algorithm spec for independent verification" }, "diy_steps": { "type": "array", "items": { "type": "string" }, "description": "Human-readable verification steps" } }, "required": ["receipt_id"] }, "http": { "method": "GET", "path": "/v1/storage/verification-bundle?receipt_id={receipt_id}", "expected_status": [200] }, "auth": "public" }, { "name": "nukez_get_evidence_bundle", "description": "Get the portable evidence bundle for a receipt: the file list, the commitment, the signed version-two envelope, the on-chain anchor, the separate verification facts, the signing keys, and plain-language verification steps. It is designed to be saved and checked later without asking the gateway anything else. Records anchored in the Switchboard era are exported with bundle_version 1 and their original signature. No authentication required. The normative description is /specs/nukez-evidence-v2.json.", "when_to_call": "When a verifier must check the gateway's signature and the on-chain anchor on its own, or when you want to save a proof for later.", "input_schema": { "type": "object", "properties": { "receipt_id": { "type": "string", "description": "Receipt ID to export evidence for" } }, "required": ["receipt_id"] }, "output_schema": { "type": "object", "properties": { "schema": { "type": "string", "description": "nukez/evidence-bundle/v2" }, "bundle_version": { "type": "integer", "description": "2 when the record carries a signed envelope, 1 for a Switchboard-era record" }, "receipt_id": { "type": "string" }, "proof_id": { "type": ["string", "null"], "description": "Public proof identifier, 32 hex characters. It is never the receipt id." }, "network": { "type": "string", "description": "CAIP-2 network identifier" }, "algorithms": { "type": "object", "description": "The Merkle algorithm and, for bundle_version 2, the envelope rules" }, "commitment": { "type": "object", "description": "merkle_root, file_count, manifest_file_count, total_bytes, check_mode, attested_at" }, "files": { "type": "array", "items": { "type": "object" }, "description": "filename, size_bytes, content_hash for every file in the snapshot" }, "envelope": { "type": ["object", "null"], "description": "body, statement_digest, signature, sig_alg, issuer_pubkey. Null for bundle_version 1." }, "v1_signature": { "type": ["object", "null"], "description": "manifest_signature, signed_message, result_hash. Null for bundle_version 2." }, "anchor": { "type": ["object", "null"], "description": "Provider-neutral on-chain anchor. type is solana_sas_v1, solana_memo_v2, or switchboard_v2 for historical records. Read the transaction from anchor.tx and the slot from anchor.slot. Null when the record has no on-chain anchor." }, "verification": { "type": "object", "description": "Separate facts. Each value is passed, failed, not_checked, or unavailable." }, "signing_keys": { "type": "array", "items": { "type": "object" }, "description": "The same entries that GET /v1/keys returns. Pin keys out of band." }, "how_to_verify": { "type": "array", "items": { "type": "string" }, "description": "Five verification steps in plain language" } }, "required": ["schema", "bundle_version", "receipt_id"] }, "http": { "method": "GET", "path": "/v1/storage/evidence-bundle?receipt_id={receipt_id}", "expected_status": [200, 404, 409] }, "auth": "public", "next_step": "Save the bundle and check it with the nukez-verify command, or follow how_to_verify. A 409 means no computed attestation exists for the receipt yet." }, { "name": "nukez_get_signing_keys", "description": "List the gateway's statement-signing keys with their ids. The same document is served at /.well-known/nukez-signing-keys.json. Pin these keys out of band: a key list served by the gateway that also produced the evidence proves self-consistency only.", "when_to_call": "Once, when you set up a verifier, so that you can record the Nukez signing key and compare it on every later verification.", "input_schema": { "type": "object", "properties": {} }, "output_schema": { "type": "object", "properties": { "schema": { "type": "string", "description": "nukez/signing-keys/v1" }, "keys": { "type": "array", "items": { "type": "object", "properties": { "key_id": { "type": "string", "description": "ed25519: followed by the first 16 hex characters of the public key" }, "alg": { "type": "string" }, "public_key_hex": { "type": "string", "description": "64 lowercase hex characters" }, "use": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" } } } }, "note": { "type": "string" } }, "required": ["schema", "keys"] }, "http": { "method": "GET", "path": "/v1/keys", "expected_status": [200] }, "auth": "public" }, { "name": "nukez_get_manifest", "description": "Get the full locker manifest including all file metadata (filenames, sizes, content hashes, timestamps).", "when_to_call": "When you need a complete snapshot of all files and their metadata in a locker.", "input_schema": { "type": "object", "properties": { "locker_id": { "type": "string" } }, "required": ["locker_id"] }, "output_schema": { "type": "object", "properties": { "locker_id": { "type": "string" }, "files": { "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string" }, "content_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "content_hash": { "type": "string" } } } } }, "required": ["locker_id"] }, "http": { "method": "GET", "path": "/v1/lockers/{locker_id}/manifest", "expected_status": [200] }, "auth": "signed_envelope", "required_ops": ["locker:read"] }, { "name": "nukez_fetch_and_store", "description": "Fetch a file from an external HTTPS URL and store it directly in the locker. The server downloads the content server-side, avoiding the need to transfer bytes through the agent. SSRF-protected: only HTTPS URLs to public hosts are allowed.", "when_to_call": "When you have a public HTTPS URL and want to store its contents without downloading first.", "input_schema": { "type": "object", "properties": { "locker_id": { "type": "string" }, "receipt_id": { "type": "string" }, "source_url": { "type": "string", "description": "HTTPS URL to fetch content from" }, "filename": { "type": "string", "description": "Optional filename for the stored file" }, "content_type": { "type": "string", "description": "Optional MIME type override" } }, "required": ["locker_id", "receipt_id", "source_url"] }, "output_schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "filename": { "type": "string" }, "size_bytes": { "type": "integer" }, "content_hash": { "type": "string" }, "download_url": { "type": "string" } }, "required": ["ok", "filename"] }, "http": { "method": "POST", "path": "/v1/files/fetch-and-store", "content_type": "application/json", "expected_status": [200] }, "auth": "signed_envelope", "required_ops": ["locker:write"] } ], "contract_notes": [ "HTTP 402 from /v1/storage/request is an expected payment challenge.", "Do not POST bytes to the API; always use upload_url/download_url short URLs.", "For signed_envelope: body_sha256 must match SHA256 of the exact bytes you send on the wire (canonical JSON).", "Proof responses carry a provider-neutral anchor object. Read the on-chain transaction from anchor.tx first, and use switchboard_tx only when anchor is absent. The switchboard_* fields are populated only for historical Switchboard anchors. Never label a solana_sas_v1 or solana_memo_v2 anchor as Switchboard.", "The verification object reports separate facts, each one of passed, failed, not_checked, or unavailable. To say that a record is anchored on-chain, require verification.anchor_confirmed to be passed. The boolean verified keeps its historical meaning: an attestation record exists and is not pending.", "GET /v1/storage/evidence-bundle?receipt_id={receipt_id} returns the portable evidence bundle, and GET /v1/keys lists the gateway's statement-signing keys. Both are public. The normative description is /specs/nukez-evidence-v2.json.", "One payment transaction buys one pay request. Retrying the same pay request is idempotent." ], "error_recovery": { "signed_url_expired": "Call nukez_get_file_urls to mint new URLs.", "tx_not_found": "Retry confirm_storage with exponential backoff.", "PAYMENT_ALREADY_ALLOCATED": "Do not retry with the same transaction. Request a new quote and pay it with a new transaction.", "PAYMENT_OUTSIDE_QUOTE_WINDOW": "Request a quote first, pay it, and then confirm. A payment made before the quote existed cannot pay for it.", "CONFIRM_INTENT_REQUIRED": "Sign the sign_this text from the error detail with the payer key and resend it as payer_signature." } }