Quickstart

bun init -y
bun add @x402/core@2.18.0 @x402/evm@2.18.0 viem

X402_PRIVATE_KEY=0xYOUR_64_HEX_CHARACTER_PRIVATE_KEY

.env
*.naven-upload.json

import { createHash, randomUUID } from "node:crypto";
import { readFile, writeFile } from "node:fs/promises";
import { basename, extname } from "node:path";
import { x402Client, x402HTTPClient } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { isAddress } from "viem";
import { privateKeyToAccount } from "viem/accounts";

const api = "https://api.naven.network/v1/ipfs";
const network = "eip155:4663";
const usdg = "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168";
const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;

type UploadState = {
  key: string;
  sha256: string;
  mimeType: string;
  orderId?: string;
  paymentHeaders?: Record<string, string>;
};

async function readData(response: Response) {
  const body = await response.json();
  if (!response.ok || body.code !== 0) {
    throw new Error(`HTTP ${response.status}: ${body.message ?? "Request failed"}`);
  }
  return body.data;
}

async function main() {
  const imagePath = process.argv[2];
  const privateKey = process.env.X402_PRIVATE_KEY;
  if (!imagePath) throw new Error("Usage: bun run upload.ts ./image.png");
  if (!privateKey || !/^0x[0-9a-f]{64}$/i.test(privateKey)) {
    throw new Error("Set X402_PRIVATE_KEY to a 0x-prefixed private key in .env");
  }

  // Create the signer and enable x402 v2 exact payments on Robinhood Chain.
  const signer = privateKeyToAccount(privateKey as `0x${string}`);
  const client = new x402Client();
  registerExactEvmScheme(client, { signer, networks: [network] });
  const httpClient = new x402HTTPClient(client);

  const config = await readData(await fetch(`${api}/config`));
  if (!config.available) throw new Error("IPFS uploads are temporarily unavailable");

  // Read the actual file; the API also validates its contents and dimensions.
  const mimeTypes: Record<string, string> = {
    ".jpg": "image/jpeg",
    ".jpeg": "image/jpeg",
    ".png": "image/png",
    ".webp": "image/webp",
  };
  const mimeType = mimeTypes[extname(imagePath).toLowerCase()];
  if (!mimeType) throw new Error("Choose a .jpg, .jpeg, .png, or .webp image");
  const bytes = new Uint8Array(await readFile(imagePath));
  if (bytes.length === 0 || bytes.length > config.upload.maxFileBytes) {
    throw new Error(`Image must be 1–${config.upload.maxFileBytes} bytes`);
  }
  const file = new File([bytes], basename(imagePath), { type: mimeType });
  const sha256 = createHash("sha256").update(bytes).digest("hex");

  // Generate the key only for a new upload. Never replace it during a retry.
  const statePath = `${imagePath}.naven-upload.json`;
  let state: UploadState;
  try {
    state = JSON.parse(await readFile(statePath, "utf8"));
  } catch (error) {
    if ((error as { code?: string }).code !== "ENOENT") throw error;
    state = { key: randomUUID(), sha256, mimeType };
    await writeFile(statePath, JSON.stringify(state), { mode: 0o600, flag: "wx" });
  }
  if (state.sha256 !== sha256 || state.mimeType !== mimeType) {
    throw new Error("This saved order belongs to a different image. Restore the original file.");
  }
  const saveState = () =>
    writeFile(statePath, JSON.stringify(state), { mode: 0o600 });

  // Rebuild multipart data for every request so the file can be sent again.
  function sendUpload(paymentHeaders: Record<string, string> = {}) {
    const form = new FormData();
    form.set("file", file);
    return fetch(`${api}/upload`, {
      method: "POST",
      headers: { "Idempotency-Key": state.key, ...paymentHeaders },
      body: form,
      redirect: "error",
      signal: AbortSignal.timeout(120_000),
    });
  }

  // This is the configured paidFetch: check recovery state, then handle one 402.
  async function paidFetch(): Promise<Response> {
    if (state.orderId) {
      const response = await fetch(`${api}/orders/${state.orderId}`, {
        headers: { "Idempotency-Key": state.key },
      });
      const order = await readData(response.clone());
      if (order.status === "fulfilled") return response;
      if (order.status === "paid") return sendUpload();
      if (order.status !== "awaiting_payment") {
        throw new Error(`Order ${order.id} is ${order.status}. Check recovery instructions before continuing.`);
      }
    }

    // If a prior request was interrupted, reuse its exact signed authorization.
    const response = await sendUpload(state.paymentHeaders);
    if (response.status !== 402 || state.paymentHeaders) return response;

    const offer = httpClient.getPaymentRequiredResponse(
      (name) => response.headers.get(name),
      await response.clone().json(),
    );
    const terms = offer.accepts[0];
    const resource = new URL(offer.resource.url);
    const orderId = resource.searchParams.get("orderId");
    if (
      offer.x402Version !== 2 || offer.accepts.length !== 1 ||
      terms?.scheme !== "exact" || terms.network !== network ||
      terms.asset.toLowerCase() !== usdg.toLowerCase() ||
      terms.amount !== "5000" || !isAddress(terms.payTo) ||
      resource.origin !== new URL(api).origin ||
      resource.pathname !== "/v1/ipfs/upload" ||
      resource.username || resource.password || resource.hash ||
      !orderId || !uuid.test(orderId) ||
      (state.orderId && state.orderId !== orderId)
    ) {
      throw new Error("Unexpected upload payment terms; no new payment was signed");
    }

    // Save the order ID before signing, then the payment before sending it.
    state.orderId = orderId;
    await saveState();
    const payload = await httpClient.createPaymentPayload(offer);
    state.paymentHeaders = httpClient.encodePaymentSignatureHeader(payload);
    await saveState();
    return sendUpload(state.paymentHeaders);
  }

  const result = await readData(await paidFetch());
  if (result.status !== "fulfilled") {
    throw new Error(`Upload is ${result.status}; keep the saved state for recovery`);
  }
  console.log(JSON.stringify(result, null, 2));
}

main().catch((error) => {
  console.error(error instanceof Error ? error.message : "Upload failed");
  process.exitCode = 1;
});

bun run upload.ts ./image.png