# Nukez agent briefing

Nukez is an HTTP-first storage service designed for autonomous and semi-autonomous agents.

It's weird in exactly the good way: you *buy* storage via an x402 payment flow on Solana (or EVM-compatible chains like Monad), receive a verifiable receipt, then use short URLs to upload/download bytes. No cloud credentials, no SDK required, no storage provider exposed.

## Multi-Chain Support & Payment Discovery

Nukez supports multiple payment chains including Solana and EVM-compatible networks (Monad). The storage request (402 response) includes a **`payment_options`** array listing all available payment methods with live oracle-priced amounts:

- **SOL** (Solana native)
- **USDC** (Monad ERC-20)
- **USDT** (Monad ERC-20)
- **MON** (Monad native — oracle-priced via CoinGecko)
- **WETH** (Monad ERC-20 — oracle-priced via CoinGecko)

Agents inspect `payment_options` to discover available chains/assets, then specify their choice via `payment_chain` and `payment_asset` in the confirm step. The `pynukez` SDK handles multi-chain automatically.

## Where an agent should start

1) **Discovery contract**: `GET /.well-known/nukez.json`

2) **OpenAPI**: `GET /openapi.json`

3) **Tool schema** (LLM-friendly): `GET /v1/tools.json` (minimal) or `/v1/tool_contract.json` (full)

4) **LLM index**: `GET /llms.txt` (short) and optionally `/llms-full.txt`

5) **Short URL verify key**: `GET /v1/short-url/verify-key` (Ed25519 public key for verifying URL tokens)

## What Nukez is good for

Use it when you need:

- Persistent storage over plain HTTP.
- A cryptographic receipt (proof you paid + a stable identifier).
- Provider opacity -- you never see GCS/S3/Azure identity; all URLs are `api.nukez.xyz`.
- Compact URLs -- ~170 characters vs ~600 for raw cloud signed URLs. Saves context budget.
- Independent verifiability -- every receipt, attestation, and URL token is Ed25519-signed and verifiable without trusting Nukez.
- Multi-chain payment flexibility -- pay with SOL on Solana or native tokens on EVM chains.

Avoid it when you need:

- Ultra low latency (sub-10ms),
- Ephemeral scratch storage,
- Or you already have S3/GCS credentials and do not need receipts.

## Core concepts (the 30-second version)

- **Payment is a protocol step, not an error.** `POST /v1/storage/request` may return **HTTP 402** with a JSON body describing how to pay. Treat that 402 as an expected payment challenge. The response includes chain-specific payment instructions based on `pay_network`.

- **Receipt ID is the durable key.** After `confirm`, you get `receipt_id`. Keep it. Receipts include chain-agnostic fields: `paid_amount`, `paid_raw`, `pay_asset`, and `network`.
- **Provider can be selected at purchase time.** `POST /v1/storage/request` supports optional `provider` (`gcs`, `mongodb`, `storj`, `arweave`, `filecoin`, `firestore`).

- **Locker ID is deterministic.** A locker is provisioned from a receipt, and the locker_id is derived from that receipt: `locker_id = "locker_" + sha256(receipt_id)[:12]`.

- **Authorization: Signed envelopes only.**
  - `X-Nukez-Envelope` + `X-Nukez-Signature` headers — request-bound signatures.
  - Cap tokens have been eliminated. All authenticated requests use signed envelopes.
  - Envelopes include `sig_alg` field (`"ed25519"` for Solana, `"secp256k1"` for EVM).

- **Receipt-based file proxy (stable URLs).**
  - Files are accessible via `GET /v1/r/{receipt_id}/f/{filename}` — no auth, no TTL expiry.
  - These URLs are permanent as long as the locker exists. Use for embedding, sharing, and viewer rendering.

- **Operator delegation.**
  - Register Ed25519 operator keys via `operator_pubkey` at provision time or `POST /v1/lockers/{locker_id}/operators` after provisioning.
  - Operators can perform file operations (read, write, list) on behalf of the locker owner using signed envelopes with their own key.
  - Useful for cross-chain delegation: EVM owner (secp256k1) delegates to Ed25519 operator for file operations.

- **Verification bundle.**
  - `GET /v1/storage/verification-bundle?receipt_id=X` returns a self-contained proof package (payment proof + content proof + algorithm spec + DIY steps).
  - No authentication required. Portable and shareable.

- **URLs are provider-opaque.** The API returns short URLs like `https://api.nukez.xyz/f/{token}`. PUT/GET to these directly -- the gateway handles routing to the underlying storage via 307 redirect. You never see `storage.googleapis.com` or any provider identity.

- **Short URL tokens are Ed25519-signed.** Anyone can verify a token was issued by Nukez using the public key at `/v1/short-url/verify-key`. No shared secret, no trust required.

## The canonical "file-first" happy path

1) `POST /v1/storage/request` (with optional `pay_network` and `pay_asset`)
2) Pay to the returned address on the specified chain (Solana SOL transfer or EVM native transfer)
3) `POST /v1/storage/confirm` with `X402-TX: <tx_sig>` (preferred) or JSON body field `tx_sig` (fallback) -- works with both Solana signatures and EVM transaction hashes
4) `POST /v1/storage/signed_provision` (signed envelope) -> manifest with `locker_id`
5) `POST /v1/lockers/{locker_id}/files` -> `upload_url` (short URL: `https://api.nukez.xyz/f/{token}`)
6) `PUT upload_url` with raw bytes (the 307 redirect to storage is transparent)
7) `GET /v1/lockers/{locker_id}/files/{filename}` -> `download_url` (short URL)
8) `GET download_url` to read bytes

## Real-world failure modes you *should* expect

- Short URL expiry (upload_url/download_url tokens have TTL, default 30 min)
- Solana propagation delays (`tx_not_found` -> retry)
- EVM block confirmation delays (`tx_not_found` -> retry with longer backoff)
- 5xx transient signing errors (retry with jitter)
- Envelope expiry (`exp` in the past — use fresh timestamps)

See `/docs/ERROR_RECOVERY.md` for specific playbooks.

## CRITICAL: Signed Envelope Authentication

Before calling any endpoint that requires `signed_envelope` auth, you MUST read:
`/docs/AUTH_SIGNED_ENVELOPE.md`

This document explains how to construct the envelope, compute body_sha256, and avoid common 401 errors.

## Tool Integration Pattern

Nukez SDKs follow the canonical "Agent Tool Pattern":

1) SDK Client (auth + HTTP)
2) Tool Functions (thin JSON-safe wrappers)
3) Tool Executor (tool_name -> callable dispatcher)

Reference implementation:
- `examples/examples_llm_tools.py`

Agents should:
- call `get_tool_definitions()` for tool schemas
- execute tools strictly by name through the tool executor / tool map
- avoid importing SDK internal modules