# Nukez -- LLM index

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

Start here:
- Discovery (JSON): https://docs.nukez.xyz/.well-known/nukez.json
- Tools (LLM-friendly, START HERE): https://docs.nukez.xyz/v1/tools.json
- OpenAPI (canonical): https://docs.nukez.xyz/openapi.json

Core flow:
- x402 payment: POST /v1/storage/request -> pay on-chain -> POST /v1/storage/confirm (X402-TX header) -> POST /v1/storage/signed_provision -> file operations
- /v1/storage/request returns 402 with `accepts[]`; pick a leg, pay on-chain, then at confirm attach the tx_sig (X402-TX header) AND echo your chosen `pay_asset` (plus `pay_network` for cross-chain) in the JSON body — required whenever you paid a non-default leg, otherwise gateway falls back to the quote's default and rejects the mismatch
- locker_id is deterministic from receipt_id (locker_ + sha256(receipt_id).hex()[:12])

Multi-chain support (optional pay_network + pay_asset at request time):
- solana-mainnet (CAIP-2 solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp): SOL, USDC, USDT, WETH, BETA
- monad-mainnet (CAIP-2 eip155:143): MON, USDC, USDT0, WETH
- Confirm: tx_sig goes in X402-TX header (Solana sig or EVM tx hash); confirm body must include `pay_asset` (and `pay_network` for multi-chain) matching the leg you actually paid
- sig_alg ed25519 for Solana wallets, secp256k1 for EVM wallets

Assets:
- Stablecoins (USDC, USDT, USDT0): USD-priced; amount in atomic units (decimals 6)
- Native (SOL, MON): USD-priced via oracle; amount in lamports/wei
- WETH: USD-priced via oracle; decimals 8 (Solana) or 18 (Monad)
- BETA: flat 1 token per unit (one locker, or one Nukez Agent service activation). Not USD-priced. Mint: GBVdmQpooUmETgS8TiEqP9zuk3ajky2mabHrvSbYjR6s on solana-mainnet (decimals 0). Pay by SPL transfer to the BETA ATA returned in the accepts entry's `payTo`.

Provisioning:
- /v1/storage/signed_provision (signed envelope) returns a locker manifest with file_api endpoints
- Optional operator_pubkey for cross-chain delegation (e.g., EVM payer -> Ed25519 operator for file ops)

Storage providers (selectable at /v1/storage/request via `provider`):
- gcs, mongodb, storj, arweave, filecoin, firestore

File operations (signed envelope, ops vary by endpoint):
- POST /v1/lockers/{locker_id}/files (locker:write) — create file metadata + mint short URLs
- GET /v1/lockers/{locker_id}/files (locker:list)
- GET /v1/lockers/{locker_id}/files/{filename} (locker:read) — fresh signed URLs
- DELETE /v1/lockers/{locker_id}/files/{filename} (locker:write)
- Bytes transfer via provider-opaque short URLs at https://api.nukez.xyz/f/{token} (PUT to upload, GET to download). Append ?proxy=1 to PUT for single-domain egress.

Auth (signed envelope, request-bound, no bearer tokens):
- Two headers: X-Nukez-Envelope (base64url canonical-JSON envelope, no padding) + X-Nukez-Signature (base58 ed25519 / hex secp256k1 over envelope bytes)
- Envelope fields: v, locker_id, receipt_id, nonce (16-byte hex), iat, exp (~iat+60s), ops, method, path, body_sha256
- body_sha256 must match SHA256 of the EXACT bytes sent on the wire — canonicalize JSON once, hash that string, send that string verbatim

Other useful surfaces:
- /v1/storage/verification-bundle?receipt_id=X — self-contained proof package, no auth required
- /v1/storage/merkle-proof?receipt_id=X&filename=Y — inclusion proof for a single file (no auth)
- /v1/lockers/{locker_id}/operators — register/remove operator pubkeys (locker:admin)
- /v1/files/fetch-and-store — server-side fetch + store from external HTTPS URL (locker:write)
- /v1/storage/attest, /v1/attest/push — signed: ops=["locker:attest"]. Compute the file-set Merkle root and anchor it on Switchboard. Most callers use the SDK (client.attest) or /v1/storage/verify instead; only direct HTTP callers construct envelopes. Envelope.receipt_id MUST equal the request's receipt_id (JSON body for push; query param for attest). Mismatch returns 401 RECEIPT_ID_MISMATCH on both.

Independent verification (third parties):
- Canonical spec (normative): https://docs.nukez.xyz/docs/verify/merkle-v1.md
- Machine-readable: https://docs.nukez.xyz/specs/nukez-merkle-v1.json
- Covers leaf hashing, sort order, parent formula, odd-level duplication, result_hash, att_code (display value only — NOT a security primitive), inclusion proof verification, Solana/Switchboard + Monad anchors, and a conformance test vector
- Note: att_code is derived from result_hash, not merkle_root. The authoritative values are result_hash, merkle_root, file entries, and on-chain anchors

Nukez Agent (separate service at agent.nukez.xyz):
- Subscription paywall (flat $500 per 30-day period USD-priced, or 1 BETA flat) for the hosted reasoning agent
- GET /v1/service/request -> pay on-chain -> POST /v1/service/confirm (X402-TX header, X-Nukez-Identity header) -> POST /v1/delegate
- Activates an active developer with one bundled locker for a 30-day period

Common failure modes:
- 402 tx_not_found at confirm — RPC propagation delay, retry with exponential backoff (2s, 4s, 8s, 16s)
- 400 "<ASSET> on <NETWORK> not in quote" at confirm — your `pay_asset`/`pay_network` in the confirm body doesn't match any leg of the original accepts[]; set them to the exact leg you actually transferred funds on
- 401/422 from signed_envelope endpoints — usually missing X-Nukez-* headers or stale envelope (rebuild with fresh iat)
- 403/404 from short URLs — assume expiry; re-mint via GET /v1/lockers/{locker_id}/files/{filename}
- 401 with body_hash error — body_sha256 in envelope doesn't match wire body bytes; canonicalize once and reuse

Docs:
- https://docs.nukez.xyz/docs/AGENT_BRIEFING.md
- https://docs.nukez.xyz/docs/AGENT_FLOW.md
- https://docs.nukez.xyz/docs/AUTH_SIGNED_ENVELOPE.md (CRITICAL before any authenticated endpoint)
- https://docs.nukez.xyz/docs/ERROR_RECOVERY.md
- https://docs.nukez.xyz/docs/CHANGELOG.md