§ how it works · worked examples

Code, end-to-end.

One operation, four surfaces. Every step is numbered, sequential, and paste-ready — no skipped jumps, no implied context.

Direct curl against api.nukez.xyz. Full protocol control; you sign envelopes yourself.

Jump to step

01#

Request a quote

Ask the gateway what storage costs. Returns x402 payment options for SOL and EVM.

Call: POST /v1/storage/request
Auth: None

Request · bash

curl -sS -X POST "https://api.nukez.xyz/v1/storage/request" \
  -H "Content-Type: application/json" \
  -d '{"units":1,"provider":"gcs"}' | jq .

Response (truncated) · json

{
  "x402Version": 2,
  "accepts": [
    {
      "scheme": "exact",
      "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "amount": "240211387",
      "asset": "So11111111111111111111111111111111111111112",
      "payTo": "HqrTLaNk89dHPVR5zyMPtEiRnQfabmqc8B9yR3KVbyVp",
      "extra": {
        "name": "SOL",
        "human_amount": "0.240211387",
        "pay_req_id": "c79d9db9abb7",
        "quote_expires_at": 1776100367
      }
    }
  ]
}

02#

Pay on-chain

Transfer the quoted SOL to the gateway treasury. Save the tx signature.

Call: solana-cli (or any wallet)
Auth: On-chain signing

The gateway never holds your keys. Any payment mechanism that lands the correct amount at the correct treasury is valid.

Solana CLI · bash

solana transfer HqrTLaNk89dHPVR5zyMPtEiRnQfabmqc8B9yR3KVbyVp 0.240211387 \
  --url 'https://mainnet.helius-rpc.com/?api-key=<YOUR_RPC_KEY>' \
  --keypair '/path/to/svm_key.json' \
  --allow-unfunded-recipient

Output · bash

Signature: Eem5xvfMRA3rVCTNNZZ9N4rQzPTVgbH5qfS9WQKK1qT7RvwCMMdVHDb9ruRkrCnW5c7Kp2B9ZVQyYtFwURaZ5WS

03#

Confirm payment → receipt

Hand the gateway the tx signature. It returns a signed receipt and a receipt_id.

Call: POST /v1/storage/confirm
Auth: X402-TX header

Quote window is 300 seconds. Past that, the gateway returns QUOTE_EXPIRED and you re-run Step 1.

Request · bash

curl -sS -X POST "https://api.nukez.xyz/v1/storage/confirm" \
  -H "Content-Type: application/json" \
  -H "X402-TX: <YOUR_TX_SIGNATURE>" \
  -d '{"pay_req_id":"c79d9db9abb7"}' | jq .

Response · json

{
  "ok": true,
  "receipt_id": "ee330fef107cfe66",
  "receipt": {
    "id": "ee330fef107cfe66",
    "owner_id": "BhBeSkwKyqysZstzkqdf4qAcYfS9r27wEMmouvSVfp1U",
    "tx_hash": "Eem5xvfMRA3r...",
    "paid_amount": "0.240211387",
    "receipt_hash": "01f365df877adccabfcfeeef31edcfd7..."
  }
}

04#

Provision the locker

Sign an envelope for locker:provision. The gateway creates the locker bound to your pubkey.

Call: POST /v1/storage/signed_provision
Auth: Signed envelope (ops: locker:provision)

Envelopes are Ed25519-signed canonical JSON carrying receipt_id, ops, and a 5-minute exp. The signing helper script is in Appendix A of the HTTP guide.

Request · bash

RECEIPT_ID="ee330fef107cfe66"

# Build envelope + signature with the helper script
SIGN=$(echo -n "{\"receipt_id\":\"$RECEIPT_ID\",\"tags\":[]}" | \
  python3 nukez_sign.py \
    --keypair '/path/to/svm_key.json' \
    --method POST \
    --path /v1/storage/signed_provision \
    --receipt-id "$RECEIPT_ID" \
    --ops '["locker:provision"]')

curl -sS -X POST "https://api.nukez.xyz/v1/storage/signed_provision" \
  -H "Content-Type: application/json" \
  -H "X-Nukez-Envelope: $(echo "$SIGN" | jq -r '.x_nukez_envelope')" \
  -H "X-Nukez-Signature: $(echo "$SIGN" | jq -r '.x_nukez_signature')" \
  -d "{\"receipt_id\":\"$RECEIPT_ID\",\"tags\":[]}" | jq .

Response · json

{
  "locker_id": "locker_fd737d2f6613",
  "receipt_id": "ee330fef107cfe66",
  "bucket": "nukez",
  "path_prefix": "lockers/locker_fd737d2f6613/"
}

05#

Create a file entry → upload URL

Sign locker:write. Get back a short upload URL that 307-redirects to GCS.

Call: POST /v1/lockers/{locker_id}/files
Auth: Signed envelope (ops: locker:write)

Request · bash

LOCKER_ID="locker_fd737d2f6613"
BODY='{"filename":"Anza.pdf","content_type":"application/pdf","ttl_min":30}'

SIGN=$(echo -n "$BODY" | python3 nukez_sign.py \
  --keypair '/path/to/svm_key.json' \
  --method POST \
  --path "/v1/lockers/$LOCKER_ID/files" \
  --receipt-id "$RECEIPT_ID" \
  --ops '["locker:write"]')

curl -sS -X POST "https://api.nukez.xyz/v1/lockers/$LOCKER_ID/files" \
  -H "Content-Type: application/json" \
  -H "X-Nukez-Envelope: $(echo "$SIGN" | jq -r '.x_nukez_envelope')" \
  -H "X-Nukez-Signature: $(echo "$SIGN" | jq -r '.x_nukez_signature')" \
  -d "$BODY" | jq .

Response · json

{
  "filename": "Anza.pdf",
  "upload_url": "https://api.nukez.xyz/f/AhNsb2NrZXJfZmQ3M...",
  "download_url": "https://api.nukez.xyz/f/AhNsb2NrZXJfZmQ3M...",
  "confirm_url": "https://api.nukez.xyz/v1/files/confirm?receipt_id=ee330fef...&filename=Anza.pdf",
  "expires_in_sec": 1800
}

06#

PUT bytes to the upload URL

Resolve the 307 once, then PUT the body straight to GCS. Bypasses the 32 MB Cloud Run limit.

Call: PUT <upload_url>
Auth: URL-embedded token

The gateway short URL (/f/{token}) returns a 307 to a signed GCS URL. Preflight a bodyless PUT to capture the redirect, then PUT the file body to the resolved URL. This avoids hitting Cloud Run's request-body cap on large files.

Preflight + upload · bash

UPLOAD_URL="<paste upload_url from Step 5>"

# 1. Preflight: capture the GCS redirect target
GCS_URL=$(curl -sS -X PUT -I "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  | awk -F': ' '/^[Ll]ocation:/ {print $2}' | tr -d '\r')

# 2. Upload the body to GCS directly
curl -sS -X PUT "$GCS_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @'/path/to/Anza.pdf'

07#

Confirm the upload

Tell the gateway the bytes are in place. It hashes them and records size + content_hash.

Call: POST /v1/files/confirm
Auth: Receipt-bearer (URL parameter)

Request · bash

curl -sS -X POST "https://api.nukez.xyz/v1/files/confirm?receipt_id=$RECEIPT_ID&filename=Anza.pdf" \
  | jq .

Response · json

{
  "filename": "Anza.pdf",
  "content_hash": "sha256:9d6500e596f267986b1ab73522a27a5424cd8615b4a65166c486d8933d004237",
  "size_bytes": 5395694,
  "confirmed": true
}

08#

List files in the locker

Sign locker:list. Returns the manifest with hashes, sizes, content types.

Call: GET /v1/lockers/{locker_id}/files
Auth: Signed envelope (ops: locker:list)

Request · bash

SIGN=$(echo -n "" | python3 nukez_sign.py \
  --keypair '/path/to/svm_key.json' \
  --method GET \
  --path "/v1/lockers/$LOCKER_ID/files" \
  --receipt-id "$RECEIPT_ID" \
  --ops '["locker:list"]')

curl -sS "https://api.nukez.xyz/v1/lockers/$LOCKER_ID/files" \
  -H "X-Nukez-Envelope: $(echo "$SIGN" | jq -r '.x_nukez_envelope')" \
  -H "X-Nukez-Signature: $(echo "$SIGN" | jq -r '.x_nukez_signature')" \
  | jq .

09#

Attest the locker on-chain

Build the merkle root over all confirmed files and anchor it on Solana via Switchboard.

Call: POST /v1/storage/attest
Auth: None

Returns the merkle root, the Switchboard tx_signature, and the slot. Until this lands, verify_storage will return verified=false.

Request · bash

curl -sS -X POST "https://api.nukez.xyz/v1/storage/attest" \
  -H "Content-Type: application/json" \
  -d "{\"receipt_id\":\"$RECEIPT_ID\",\"sync\":true}" | jq .

Response · json

{
  "receipt_id": "ee330fef107cfe66",
  "merkle_root": "sha256:0fcdcb3cab2c096f3151deb2c3c74a77629d4edbcb2aaacfd426e8cee9ba4262",
  "file_count": 4,
  "status": "complete",
  "tx_signature": "2duEDtirexzYBmDVPxgFPPzjN94VgiRP7hfqYENLrQHq7GQ8SaQYJ2YVqkNFFG76tgqUn7jt5QtoR3VoEvFb3Rb4",
  "switchboard_slot": 413479250
}

10#

Pull the verification bundle

Download the proof you can hand a third party. Includes payment, files, merkle, on-chain anchor, and DIY verify steps.

Call: GET /v1/storage/verification-bundle
Auth: None

Request · bash

curl -sS "https://api.nukez.xyz/v1/storage/verification-bundle?receipt_id=$RECEIPT_ID" \
  | jq .

Response (truncated) · json

{
  "receipt_id": "ee330fef107cfe66",
  "payment_proof": { "tx_signature": "5oys9HrK...", "explorer_url": "https://explorer.solana.com/tx/..." },
  "content_proof": { "merkle_root": "sha256:0fcdcb3c...", "file_count": 4, "files": [ ... ] },
  "on_chain_anchor": {
    "type": "switchboard_v2",
    "tx_signature": "2duEDtir...",
    "slot": 413479250,
    "feed_pubkey": "7wevRnKMrSCYEAdWEuaZn6K9MuNJBSUXLdkXZfxJ5VmY"
  },
  "verify_yourself": {
    "steps": [
      "1. Download each file from its download_url",
      "2. SHA256 the raw bytes — must match content_hash",
      "3. Build the merkle tree per the algorithm spec",
      "4. Computed root must match content_proof.merkle_root",
      "5. Look up on_chain_anchor.tx_signature on Solana Explorer"
    ]
  }
}

That's the full HTTP API flow. Want to compare to a different surface?