# Nukez -- LLM index (full)

Nukez is an HTTP-first storage service designed for autonomous agents. It uses an x402 payment protocol supporting multiple chains (Solana and EVM/Monad), returns verifiable receipts, and provides per-object short URLs for byte transfer.

Base URL: https://api.nukez.xyz
Docs: https://docs.nukez.xyz

## Discovery

- Primary discovery document: https://docs.nukez.xyz/.well-known/nukez.json
- OpenAPI (canonical bundle): https://docs.nukez.xyz/openapi.json
- Tool schema (minimal): https://docs.nukez.xyz/v1/tools.json
- Tool contract (full): https://docs.nukez.xyz/v1/tool_contract.json

## Core flow (file-first)

1) Request storage
   - POST /v1/storage/request
   - Optional body field: `provider` in {`gcs`,`mongodb`,`storj`,`arweave`,`filecoin`,`firestore`}
   - Optional body field: `pay_network` (e.g., "solana-devnet", "monad-testnet")
   - Optional body field: `pay_asset` (e.g., "SOL", "MON", "USDC", "USDT", "WETH")
   - IMPORTANT: may return HTTP 402 with JSON body containing payment instructions.
   - Price endpoint returns amounts for multiple chains when no pay_network is specified.

2) Pay on Solana or EVM
   - Send the instructed amount to pay_to_address.
   - Capture tx signature (Solana) or tx hash (EVM).

3) Confirm
   - POST /v1/storage/confirm
   - Header: X402-TX: <tx_sig_or_tx_hash>
   - Body: {"pay_req_id": "..."}
   - Response: receipt_id + receipt
   - Receipt fields are chain-agnostic: paid_amount (human-readable), paid_raw (atomic units), pay_asset, network
   - Receipts include slot (Solana) or block_number (EVM) as applicable
   - sig_alg field: "ed25519" for Solana, "secp256k1" for EVM

4) Provision a locker
   - POST /v1/storage/signed_provision
   - Auth: signed envelope (X-Nukez-Envelope + X-Nukez-Signature)
   - Body: {"receipt_id":"...","tags":[]}
   - Optional: include `operator_pubkey` (Ed25519 base58) to register an operator at provision time
   - Response: locker manifest containing locker_id and file_api endpoints.

5) Create a file (mint short URLs)
   - POST /v1/lockers/{locker_id}/files
   - Auth: signed envelope
   - Body: {"filename":"..." (optional), "content_type":"...", "ttl_min":30}
   - Response: upload_url, download_url, urls_expire_in_sec (+ optional upload_headers)

6) Upload bytes
   - PUT upload_url with raw bytes (short URL is provider-opaque and resolves through gateway)

7) Download bytes
   - GET download_url
   - If expired, refresh URLs with GET /v1/lockers/{locker_id}/files/{filename}?ttl_min=30
   - Verify short URL token signatures via GET /v1/short-url/verify-key if needed

## Auth

Signed envelope (request-bound):
- Headers:
  - X-Nukez-Envelope: base64url(canonical_json(envelope))
  - X-Nukez-Signature: base58(ed25519_signature) for Solana or hex(secp256k1_signature) for EVM
- Envelope binds method+path+body hash and includes ops.
- sig_alg field: "ed25519" for Solana wallets, "secp256k1" for EVM wallets
- See: https://docs.nukez.xyz/docs/AUTH_SIGNED_ENVELOPE.md

## Operator delegation

- Register Ed25519 operator keys to perform file operations on behalf of the locker owner.
- Useful for cross-chain delegation: EVM owner (secp256k1) delegates to Ed25519 operator.
- Add at provision time: include `operator_pubkey` in signed_provision body.
- Add post-provision: POST /v1/lockers/{locker_id}/operators (ops: locker:admin)
- Remove: DELETE /v1/lockers/{locker_id}/operators/{pubkey} (ops: locker:admin)
- Operators sign envelopes with their own Ed25519 key for file ops (read, write, list).

## Verification bundle

- GET /v1/storage/verification-bundle?receipt_id=X
- No auth required. Returns self-contained proof package.
- Includes: payment proof, content proof, algorithm spec, DIY verification steps.
- Portable and shareable — anyone can verify without trusting Nukez.

## Additional endpoints

- Confirm upload: POST /v1/files/confirm — explicit SHA-256 verification after upload (ops: locker:write)
- Get manifest: GET /v1/lockers/{locker_id}/manifest — full locker manifest with file metadata (ops: locker:read)
- Fetch and store: POST /v1/files/fetch-and-store — server-side URL fetch + store (ops: locker:write)

## Failure modes (expected)

- tx_not_found during confirm: retry with exponential backoff
- short URL expiry: re-mint via file get endpoint
- envelope expiry: rebuild with fresh timestamps
- operator not authorized: verify key is registered on locker
- transient 5xx: retry with jitter; keep idempotency keys for request_storage

See: https://docs.nukez.xyz/docs/ERROR_RECOVERY.md