@x402janus/sdk 0.1.0

package/README.md

@@ -0,0 +1,94 @@
+# @x402janus/sdk
+
+Wallet security for AI agents. One API call. Forensic wallet analysis. Deterministic risk score.
+
+**x402-native** — no API keys, no accounts. Your agent pays per scan with USDC on Base.
+
+## Install
+
+```bash
+npm install @x402janus/sdk
+```
+
+## Quick Start
+
+```typescript
+import { JanusClient } from "@x402janus/sdk";
+
+const janus = new JanusClient({
+  privateKey: process.env.PRIVATE_KEY, // Agent wallet key
+});
+
+const result = await janus.scan("0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18");
+
+if (result.safe) {
+  // proceed with transaction
+} else {
+  console.log("Blocked:", result.findings);
+  console.log("Revoke txs:", result.revokeTxs);
+}
+```
+
+## How Payment Works
+
+1. Your agent calls `janus.scan(address)`
+2. The SDK hits the x402janus API, which returns HTTP 402 with payment requirements
+3. The SDK signs an EIP-3009 `TransferWithAuthorization` for the required USDC amount
+4. The signed payment is sent in the `X-PAYMENT` header on retry
+5. The Thirdweb facilitator verifies and settles USDC on Base
+6. Scan results are returned
+
+**Your agent needs:**
+- A private key (for signing — never sent to the API)
+- USDC on Base (for scan payments)
+
+## API
+
+### `new JanusClient(config?)`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `privateKey` | `string` | `process.env.PRIVATE_KEY` | Agent wallet private key |
+| `baseUrl` | `string` | `https://x402janus.com` | API endpoint |
+| `defaultTier` | `"quick" \| "standard" \| "deep"` | `"quick"` | Default scan tier |
+
+### `janus.scan(address, options?)`
+
+Scan a wallet for security risks.
+
+```typescript
+const result = await janus.scan("0x...", { tier: "deep" });
+// result: { scanId, safe, risk, findings, revokeTxs }
+```
+
+### `janus.approvals(address)`
+
+List active token approvals with risk assessment.
+
+### `janus.revoke(address)`
+
+Get pre-built revoke transactions for dangerous approvals.
+
+### `janus.health()`
+
+Check API health status.
+
+## Scan Tiers
+
+| Tier | Price | Response Time | Coverage |
+|------|-------|---------------|----------|
+| `quick` | $0.01 | <3s | Deterministic risk score, approval list |
+| `standard` | $0.05 | <10s | + AI threat analysis |
+| `deep` | $0.25 | <30s | + Full graph analysis, drainer fingerprinting |
+
+## Types
+
+All types are exported with Zod schemas for runtime validation:
+
+```typescript
+import { ScanResult, ScanResultSchema, Finding, RevokeTx } from "@x402janus/sdk";
+```
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @module client
+ * JanusClient — the main entry point for @x402janus/sdk.
+ *
+ * Performs wallet security scans via the x402janus API with x402 micropayment.
+ */
+import { type ScanResult, type ApprovalsResult, type RevokeTx, type HealthResult, type JanusClientConfig, type ScanOptions } from "./types.js";
+/**
+ * JanusClient — scan wallets for security risks via x402janus.
+ *
+ * @example
+ * ```ts
+ * import { JanusClient } from "@x402janus/sdk";
+ *
+ * const janus = new JanusClient({ privateKey: process.env.PRIVATE_KEY });
+ * const result = await janus.scan("0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18");
+ *
+ * if (result.safe) {
+ *   // proceed with transaction
+ * } else {
+ *   console.log("Blocked:", result.findings);
+ * }
+ * ```
+ */
+export declare class JanusClient {
+    private readonly baseUrl;
+    private readonly privateKey;
+    private readonly defaultTier;
+    private readonly facilitatorUrl;
+    constructor(config?: JanusClientConfig);
+    /**
+     * Scan a wallet for security risks.
+     *
+     * @param address - Ethereum wallet address (0x...)
+     * @param options - Optional scan configuration
+     * @returns Structured scan result with risk score, findings, and revoke transactions
+     * @throws If the address is invalid, payment fails, or the API returns an error
+     */
+    scan(address: string, options?: ScanOptions): Promise<ScanResult>;
+    /**
+     * List all active token approvals for a wallet.
+     *
+     * @param address - Ethereum wallet address (0x...)
+     * @returns List of approvals with risk assessment
+     */
+    approvals(address: string): Promise<ApprovalsResult>;
+    /**
+     * Build revoke transactions for dangerous approvals.
+     *
+     * @param address - Ethereum wallet address (0x...)
+     * @returns Array of pre-built revoke transactions
+     */
+    revoke(address: string): Promise<RevokeTx[]>;
+    /**
+     * Check API health status.
+     *
+     * @returns Health status of the x402janus API
+     */
+    health(): Promise<HealthResult>;
+    /**
+     * Handle the x402 payment flow: parse 402 requirements, sign, retry.
+     */
+    private handlePaymentFlow;
+    /**
+     * Extract payment requirements from a 402 response body.
+     */
+    private extractPaymentRequirements;
+    /**
+     * Validate a scan result, enforcing the safety invariant.
+     *
+     * @param paid - Whether this response came after a verified payment.
+     *               If false, `safe` is forced to `false` as a security measure.
+     */
+    private validateScanResult;
+    /**
+     * Validate an Ethereum address.
+     * @throws If the address is not a valid 0x-prefixed hex string
+     */
+    private validateAddress;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EASL,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EACjB,MAAM,YAAY,CAAC;AASpB;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAChD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAW;IACvC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;gBAE5B,MAAM,GAAE,iBAAsB;IAgB1C;;;;;;;OAOG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IA2BvE;;;;;OAKG;IACG,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IA6B1D;;;;;OAKG;IACG,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAKlD;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC;IAWrC;;OAEG;YACW,iBAAiB;IA6D/B;;OAEG;IACH,OAAO,CAAC,0BAA0B;IAclC;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAW1B;;;OAGG;IACH,OAAO,CAAC,eAAe;CAKxB"}

package/dist/client.js

@@ -0,0 +1,212 @@
+/**
+ * @module client
+ * JanusClient — the main entry point for @x402janus/sdk.
+ *
+ * Performs wallet security scans via the x402janus API with x402 micropayment.
+ */
+import { ScanTierSchema, ScanResultSchema, ApprovalsResultSchema, HealthResultSchema, PaymentRequirementsSchema, TIER_PRICES, } from "./types.js";
+import { signX402Payment } from "./payment.js";
+/** Ethereum address regex (0x + 40 hex chars) */
+const ETH_ADDRESS = /^0x[a-fA-F0-9]{40}$/;
+/** Maximum retry-after sleep (30 seconds) — prevents unbounded waits */
+const MAX_RETRY_SLEEP_MS = 30_000;
+/**
+ * JanusClient — scan wallets for security risks via x402janus.
+ *
+ * @example
+ * ```ts
+ * import { JanusClient } from "@x402janus/sdk";
+ *
+ * const janus = new JanusClient({ privateKey: process.env.PRIVATE_KEY });
+ * const result = await janus.scan("0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18");
+ *
+ * if (result.safe) {
+ *   // proceed with transaction
+ * } else {
+ *   console.log("Blocked:", result.findings);
+ * }
+ * ```
+ */
+export class JanusClient {
+    baseUrl;
+    privateKey;
+    defaultTier;
+    facilitatorUrl;
+    constructor(config = {}) {
+        this.baseUrl = (config.baseUrl ?? "https://x402janus.com").replace(/\/$/, "");
+        this.defaultTier = config.defaultTier ?? "quick";
+        this.facilitatorUrl =
+            config.facilitatorUrl ??
+                process.env.FACILITATOR_URL ??
+                "https://x402.org";
+        // Resolve private key — never expose in errors
+        const pk = config.privateKey ?? process.env.PRIVATE_KEY;
+        this.privateKey = pk || undefined;
+        // Validate default tier
+        ScanTierSchema.parse(this.defaultTier);
+    }
+    /**
+     * Scan a wallet for security risks.
+     *
+     * @param address - Ethereum wallet address (0x...)
+     * @param options - Optional scan configuration
+     * @returns Structured scan result with risk score, findings, and revoke transactions
+     * @throws If the address is invalid, payment fails, or the API returns an error
+     */
+    async scan(address, options) {
+        this.validateAddress(address);
+        const tier = options?.tier ?? this.defaultTier;
+        ScanTierSchema.parse(tier);
+        const url = `${this.baseUrl}/api/guardian/scan/${address}?tier=${tier}`;
+        // First request — expect 402 with payment requirements
+        const initial = await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+        });
+        if (initial.status === 402) {
+            // Parse payment requirements and sign
+            return this.handlePaymentFlow(url, initial, tier);
+        }
+        if (initial.ok) {
+            // Free tier or already paid — parse and validate
+            const data = await initial.json();
+            return this.validateScanResult(data);
+        }
+        throw new Error(`Scan failed: HTTP ${initial.status} ${initial.statusText}`);
+    }
+    /**
+     * List all active token approvals for a wallet.
+     *
+     * @param address - Ethereum wallet address (0x...)
+     * @returns List of approvals with risk assessment
+     */
+    async approvals(address) {
+        this.validateAddress(address);
+        const url = `${this.baseUrl}/api/guardian/scan/${address}?tier=quick&mode=approvals`;
+        const initial = await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+        });
+        if (initial.status === 402 && this.privateKey) {
+            const paymentResult = await this.handlePaymentFlow(url, initial, "quick");
+            // Map scan result to approvals format
+            return {
+                wallet: address,
+                approvals: [],
+                riskCount: { low: 0, medium: 0, high: 0, critical: 0 },
+                ...paymentResult,
+            };
+        }
+        if (initial.ok) {
+            const data = await initial.json();
+            return ApprovalsResultSchema.parse(data);
+        }
+        throw new Error(`Approvals failed: HTTP ${initial.status}`);
+    }
+    /**
+     * Build revoke transactions for dangerous approvals.
+     *
+     * @param address - Ethereum wallet address (0x...)
+     * @returns Array of pre-built revoke transactions
+     */
+    async revoke(address) {
+        const result = await this.scan(address, { tier: "standard" });
+        return result.revokeTxs;
+    }
+    /**
+     * Check API health status.
+     *
+     * @returns Health status of the x402janus API
+     */
+    async health() {
+        const resp = await fetch(`${this.baseUrl}/api/health`);
+        if (!resp.ok) {
+            throw new Error(`Health check failed: HTTP ${resp.status}`);
+        }
+        const data = await resp.json();
+        return HealthResultSchema.parse(data);
+    }
+    // ─── Private helpers ─────────────────────────────────────────────────────
+    /**
+     * Handle the x402 payment flow: parse 402 requirements, sign, retry.
+     */
+    async handlePaymentFlow(url, response, tier) {
+        if (!this.privateKey) {
+            throw new Error(`Scan tier "${tier}" (${TIER_PRICES[tier].dollars}) requires a private key for x402 payment. ` +
+                `Pass privateKey in config or set PRIVATE_KEY env var.`);
+        }
+        // Parse payment requirements from 402 response
+        const body = await response.json();
+        const requirements = this.extractPaymentRequirements(body);
+        // Sign the payment
+        const paymentHeader = await signX402Payment(this.privateKey, requirements);
+        // Retry with payment header
+        const paid = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "X-PAYMENT": paymentHeader,
+            },
+        });
+        // Handle retry-after (rate limiting)
+        if (paid.status === 429) {
+            const retryAfter = paid.headers.get("retry-after");
+            const sleepMs = Math.min((retryAfter ? parseInt(retryAfter, 10) * 1000 : 5000), MAX_RETRY_SLEEP_MS);
+            await new Promise((r) => setTimeout(r, sleepMs));
+            const retry = await fetch(url, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "X-PAYMENT": paymentHeader,
+                },
+            });
+            if (!retry.ok) {
+                throw new Error(`Scan failed after retry: HTTP ${retry.status}`);
+            }
+            const data = await retry.json();
+            return this.validateScanResult(data, true);
+        }
+        if (!paid.ok) {
+            throw new Error(`Scan failed after payment: HTTP ${paid.status} ${paid.statusText}`);
+        }
+        const data = await paid.json();
+        return this.validateScanResult(data, true);
+    }
+    /**
+     * Extract payment requirements from a 402 response body.
+     */
+    extractPaymentRequirements(body) {
+        if (typeof body !== "object" || body === null) {
+            throw new Error("Invalid 402 response: no payment requirements");
+        }
+        const obj = body;
+        const reqs = obj.paymentRequirements ?? obj.requirements ?? obj;
+        // Handle array format (take first)
+        const single = Array.isArray(reqs) ? reqs[0] : reqs;
+        return PaymentRequirementsSchema.parse(single);
+    }
+    /**
+     * Validate a scan result, enforcing the safety invariant.
+     *
+     * @param paid - Whether this response came after a verified payment.
+     *               If false, `safe` is forced to `false` as a security measure.
+     */
+    validateScanResult(data, paid = false) {
+        const result = ScanResultSchema.parse(data);
+        // Security invariant: never return safe=true without payment verification
+        if (!paid && result.safe) {
+            return { ...result, safe: false };
+        }
+        return result;
+    }
+    /**
+     * Validate an Ethereum address.
+     * @throws If the address is not a valid 0x-prefixed hex string
+     */
+    validateAddress(address) {
+        if (!ETH_ADDRESS.test(address)) {
+            throw new Error(`Invalid Ethereum address: ${address.slice(0, 10)}...`);
+        }
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @x402janus/sdk — AI wallet security for agents.
+ *
+ * One API call. Forensic wallet analysis. Deterministic risk score.
+ * x402-native pay-per-scan on Base.
+ *
+ * @example
+ * ```ts
+ * import { JanusClient } from "@x402janus/sdk";
+ *
+ * const janus = new JanusClient({ privateKey: process.env.PRIVATE_KEY });
+ * const result = await janus.scan("0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18");
+ *
+ * if (result.safe) {
+ *   // proceed with transaction
+ * } else {
+ *   console.log("Blocked:", result.findings);
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { JanusClient } from "./client.js";
+export type { ScanTier, ScanResult, Finding, FindingSeverity, RevokeTx, Approval, ApprovalsResult, HealthResult, JanusClientConfig, ScanOptions, PaymentRequirements, } from "./types.js";
+export { ScanTierSchema, ScanResultSchema, FindingSchema, RevokeTxSchema, ApprovalSchema, ApprovalsResultSchema, HealthResultSchema, PaymentRequirementsSchema, TIER_PRICES, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG1C,YAAY,EACV,QAAQ,EACR,UAAU,EACV,OAAO,EACP,eAAe,EACf,QAAQ,EACR,QAAQ,EACR,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,WAAW,EACX,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,cAAc,EACd,qBAAqB,EACrB,kBAAkB,EAClB,yBAAyB,EACzB,WAAW,GACZ,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,26 @@
+/**
+ * @x402janus/sdk — AI wallet security for agents.
+ *
+ * One API call. Forensic wallet analysis. Deterministic risk score.
+ * x402-native pay-per-scan on Base.
+ *
+ * @example
+ * ```ts
+ * import { JanusClient } from "@x402janus/sdk";
+ *
+ * const janus = new JanusClient({ privateKey: process.env.PRIVATE_KEY });
+ * const result = await janus.scan("0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18");
+ *
+ * if (result.safe) {
+ *   // proceed with transaction
+ * } else {
+ *   console.log("Blocked:", result.findings);
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { JanusClient } from "./client.js";
+// Re-export schemas for runtime validation
+export { ScanTierSchema, ScanResultSchema, FindingSchema, RevokeTxSchema, ApprovalSchema, ApprovalsResultSchema, HealthResultSchema, PaymentRequirementsSchema, TIER_PRICES, } from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAiB1C,2CAA2C;AAC3C,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,cAAc,EACd,qBAAqB,EACrB,kBAAkB,EAClB,yBAAyB,EACzB,WAAW,GACZ,MAAM,YAAY,CAAC"}

package/dist/payment.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @module payment
+ * x402 micropayment signing for @x402janus/sdk.
+ *
+ * Implements EIP-3009 TransferWithAuthorization — the standard used by
+ * Circle's USDC on Base. Signs the authorization using the agent's private
+ * key and encodes it as a base64 payload for the PAYMENT-SIGNATURE header.
+ *
+ * **Security**: The private key is used only within this module for signing.
+ * It is never included in return values, error messages, or console output.
+ */
+import type { PaymentRequirements } from "./types.js";
+/**
+ * Sign an x402 payment using EIP-3009 TransferWithAuthorization.
+ *
+ * This implements the client side of the x402 payment protocol:
+ * 1. Builds the authorization parameters (from, to, value, validity window, nonce)
+ * 2. Signs them with the agent's private key via EIP-712
+ * 3. Encodes the signed payload as base64 for the `PAYMENT-SIGNATURE` header
+ *
+ * The function defaults to `TransferWithAuthorization` (EIP-3009) which is
+ * what Circle's USDC on Base supports. If the server's extra field specifies
+ * `primaryType: "Permit"`, an EIP-2612 Permit signature is used instead.
+ *
+ * @param privateKey - The payer's private key. **Never logged or thrown.**
+ * @param requirements - Payment requirements from the server's 402 response
+ * @returns Base64-encoded signed payment payload string
+ * @throws {Error} If scheme is unsupported or signing fails (key never exposed)
+ */
+export declare function signX402Payment(privateKey: `0x${string}`, requirements: PaymentRequirements): Promise<string>;
+//# sourceMappingURL=payment.d.ts.map

package/dist/payment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment.d.ts","sourceRoot":"","sources":["../src/payment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAkEtD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CACnC,UAAU,EAAE,KAAK,MAAM,EAAE,EACzB,YAAY,EAAE,mBAAmB,GAChC,OAAO,CAAC,MAAM,CAAC,CAgHjB"}

package/dist/payment.js

@@ -0,0 +1,186 @@
+/**
+ * @module payment
+ * x402 micropayment signing for @x402janus/sdk.
+ *
+ * Implements EIP-3009 TransferWithAuthorization — the standard used by
+ * Circle's USDC on Base. Signs the authorization using the agent's private
+ * key and encodes it as a base64 payload for the PAYMENT-SIGNATURE header.
+ *
+ * **Security**: The private key is used only within this module for signing.
+ * It is never included in return values, error messages, or console output.
+ */
+import { privateKeyToAccount } from "viem/accounts";
+import { toHex } from "viem";
+// ─── Constants ───────────────────────────────────────────────────────────────
+/** x402 protocol version supported by this SDK */
+const X402_VERSION = 2;
+/** x402 schemes we can handle */
+const SUPPORTED_SCHEMES = new Set(["exact"]);
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+/**
+ * Parse an EVM chain ID from a CAIP-2 network identifier.
+ * @param network - e.g. "eip155:8453"
+ * @returns The chain ID as a number (e.g. 8453)
+ * @throws {Error} If the format is unrecognised
+ */
+function parseChainId(network) {
+    const match = /^eip155:(\d+)$/.exec(network);
+    if (!match || !match[1]) {
+        throw new Error(`Unsupported network format: "${network}". Expected "eip155:<chainId>".`);
+    }
+    return parseInt(match[1], 10);
+}
+/**
+ * Generate a cryptographically random 32-byte nonce for EIP-3009.
+ * Uses the Web Crypto API (available natively in Node.js 18+).
+ *
+ * EIP-3009 nonces are non-sequential bytes32 values; once used,
+ * the contract marks them as spent to prevent replay attacks.
+ */
+async function generateNonce() {
+    const bytes = new Uint8Array(32);
+    if (typeof globalThis !== "undefined" &&
+        typeof globalThis.crypto !== "undefined" &&
+        typeof globalThis.crypto.getRandomValues === "function") {
+        globalThis.crypto.getRandomValues(bytes);
+    }
+    else {
+        // Node.js without globalThis.crypto (older Node versions)
+        const { webcrypto } = await import("node:crypto");
+        webcrypto.getRandomValues(bytes);
+    }
+    return toHex(bytes);
+}
+/**
+ * Base64-encode a string (works in both Node.js and browser environments).
+ */
+function encodeBase64(data) {
+    if (typeof Buffer !== "undefined") {
+        return Buffer.from(data, "utf-8").toString("base64");
+    }
+    // Browser / edge runtime
+    return btoa(data);
+}
+// ─── Core signing function ────────────────────────────────────────────────────
+/**
+ * Sign an x402 payment using EIP-3009 TransferWithAuthorization.
+ *
+ * This implements the client side of the x402 payment protocol:
+ * 1. Builds the authorization parameters (from, to, value, validity window, nonce)
+ * 2. Signs them with the agent's private key via EIP-712
+ * 3. Encodes the signed payload as base64 for the `PAYMENT-SIGNATURE` header
+ *
+ * The function defaults to `TransferWithAuthorization` (EIP-3009) which is
+ * what Circle's USDC on Base supports. If the server's extra field specifies
+ * `primaryType: "Permit"`, an EIP-2612 Permit signature is used instead.
+ *
+ * @param privateKey - The payer's private key. **Never logged or thrown.**
+ * @param requirements - Payment requirements from the server's 402 response
+ * @returns Base64-encoded signed payment payload string
+ * @throws {Error} If scheme is unsupported or signing fails (key never exposed)
+ */
+export async function signX402Payment(privateKey, requirements) {
+    if (!SUPPORTED_SCHEMES.has(requirements.scheme)) {
+        throw new Error(`Unsupported x402 scheme: "${requirements.scheme}". Supported: ${[...SUPPORTED_SCHEMES].join(", ")}`);
+    }
+    const chainId = parseChainId(requirements.network);
+    // Build account from private key — key stays inside this closure
+    const account = privateKeyToAccount(privateKey);
+    const now = Math.floor(Date.now() / 1000);
+    // Allow 24 hours retroactive validity to smooth over clock skew
+    const validAfterBigInt = BigInt(now - 86_400);
+    // Upper bound: current time + server-specified timeout
+    const validBeforeBigInt = BigInt(now + requirements.maxTimeoutSeconds);
+    const nonce = await generateNonce();
+    const extra = requirements.extra;
+    const tokenName = extra?.["name"] ?? "USD Coin";
+    const tokenVersion = extra?.["version"] ?? "2";
+    const primaryType = extra?.["primaryType"] ?? "TransferWithAuthorization";
+    let signature;
+    try {
+        if (primaryType === "Permit") {
+            // EIP-2612 Permit (for tokens that don't support EIP-3009)
+            signature = await account.signTypedData({
+                domain: {
+                    name: tokenName,
+                    version: tokenVersion,
+                    chainId,
+                    verifyingContract: requirements.asset,
+                },
+                types: {
+                    Permit: [
+                        { name: "owner", type: "address" },
+                        { name: "spender", type: "address" },
+                        { name: "value", type: "uint256" },
+                        { name: "nonce", type: "uint256" },
+                        { name: "deadline", type: "uint256" },
+                    ],
+                },
+                primaryType: "Permit",
+                message: {
+                    owner: account.address,
+                    spender: requirements.payTo,
+                    value: BigInt(requirements.maxAmountRequired),
+                    // For Permit, nonce would normally be fetched on-chain. Here we use 0
+                    // as a placeholder — real deployments should fetch via nonces(owner).
+                    nonce: 0n,
+                    deadline: validBeforeBigInt,
+                },
+            });
+        }
+        else {
+            // EIP-3009 TransferWithAuthorization (default — USDC on Base)
+            signature = await account.signTypedData({
+                domain: {
+                    name: tokenName,
+                    version: tokenVersion,
+                    chainId,
+                    verifyingContract: requirements.asset,
+                },
+                types: {
+                    TransferWithAuthorization: [
+                        { name: "from", type: "address" },
+                        { name: "to", type: "address" },
+                        { name: "value", type: "uint256" },
+                        { name: "validAfter", type: "uint256" },
+                        { name: "validBefore", type: "uint256" },
+                        { name: "nonce", type: "bytes32" },
+                    ],
+                },
+                primaryType: "TransferWithAuthorization",
+                message: {
+                    from: account.address,
+                    to: requirements.payTo,
+                    value: BigInt(requirements.maxAmountRequired),
+                    validAfter: validAfterBigInt,
+                    validBefore: validBeforeBigInt,
+                    nonce,
+                },
+            });
+        }
+    }
+    catch (err) {
+        // Catch and re-throw without any key material
+        const msg = err instanceof Error ? err.message : "Unknown signing error";
+        throw new Error(`x402 payment signing failed: ${msg}`);
+    }
+    // Build the payment payload (x402 v2 format)
+    const payload = {
+        x402Version: X402_VERSION,
+        scheme: requirements.scheme,
+        network: requirements.network,
+        payload: {
+            signature,
+            authorization: {
+                from: account.address,
+                to: requirements.payTo,
+                value: requirements.maxAmountRequired,
+                validAfter: validAfterBigInt.toString(),
+                validBefore: validBeforeBigInt.toString(),
+                nonce,
+            },
+        },
+    };
+    return encodeBase64(JSON.stringify(payload));
+}
+//# sourceMappingURL=payment.js.map

package/dist/payment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment.js","sourceRoot":"","sources":["../src/payment.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,412 @@
+/**
+ * @module types
+ * All public types and Zod schemas for @x402janus/sdk.
+ */
+import { z } from "zod";
+/**
+ * Scan tier controlling analysis depth and x402 micropayment amount.
+ *
+ * | Tier     | Price  | Description                                         |
+ * |----------|--------|-----------------------------------------------------|
+ * | quick    | $0.01  | Fast heuristic scan — known drainers & risk signals |
+ * | standard | $0.05  | Graph analysis + threat-intel correlation           |
+ * | deep     | $0.25  | Full forensic scan + approval chain tracing         |
+ */
+export declare const ScanTierSchema: z.ZodEnum<["quick", "standard", "deep"]>;
+/** @see {@link ScanTierSchema} */
+export type ScanTier = z.infer<typeof ScanTierSchema>;
+/**
+ * USDC pricing for each scan tier (6-decimal precision, Base mainnet).
+ * `units` is the raw USDC atomic value passed in the x402 payment header.
+ */
+export declare const TIER_PRICES: Readonly<Record<ScanTier, {
+    dollars: string;
+    units: string;
+}>>;
+/**
+ * Severity level for a security finding.
+ */
+export type FindingSeverity = "critical" | "high" | "medium" | "low" | "info";
+/**
+ * A single security finding returned in a wallet scan.
+ */
+export declare const FindingSchema: z.ZodObject<{
+    /** Machine-readable finding type (e.g. "unlimited_approval", "known_drainer") */
+    type: z.ZodString;
+    /** Severity of the finding */
+    severity: z.ZodEnum<["critical", "high", "medium", "low", "info"]>;
+    /** Human-readable description */
+    description: z.ZodString;
+    /** Relevant contract or counterparty address, if applicable */
+    address: z.ZodOptional<z.ZodString>;
+    /** Protocol name associated with the finding, if known */
+    protocol: z.ZodOptional<z.ZodString>;
+    /** Token amount at risk (human-readable), if applicable */
+    amount: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: string;
+    severity: "critical" | "high" | "medium" | "low" | "info";
+    description: string;
+    address?: string | undefined;
+    protocol?: string | undefined;
+    amount?: string | undefined;
+}, {
+    type: string;
+    severity: "critical" | "high" | "medium" | "low" | "info";
+    description: string;
+    address?: string | undefined;
+    protocol?: string | undefined;
+    amount?: string | undefined;
+}>;
+/** @see {@link FindingSchema} */
+export type Finding = z.infer<typeof FindingSchema>;
+/**
+ * A revoke transaction that the agent can sign and submit to remove a risky approval.
+ * Transactions are pre-built by the x402janus API — submit them as-is.
+ */
+export declare const RevokeTxSchema: z.ZodObject<{
+    /** Target contract address (the token contract) */
+    to: z.ZodString;
+    /** ABI-encoded calldata (e.g., `approve(spender, 0)`) */
+    data: z.ZodString;
+    /** EVM chain ID (e.g., 8453 for Base) */
+    chainId: z.ZodNumber;
+    /** Human-readable description of what this revoke does */
+    description: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    description: string;
+    to: string;
+    data: string;
+    chainId: number;
+}, {
+    description: string;
+    to: string;
+    data: string;
+    chainId: number;
+}>;
+/** @see {@link RevokeTxSchema} */
+export type RevokeTx = z.infer<typeof RevokeTxSchema>;
+/**
+ * Full result of a wallet security scan.
+ *
+ * **Security invariant**: `safe` is always `false` when payment was not
+ * successfully verified. Never trust `safe: true` from an unpaid response.
+ */
+export declare const ScanResultSchema: z.ZodObject<{
+    /** Unique identifier for this scan (for audit/logging) */
+    scanId: z.ZodString;
+    /**
+     * Whether the wallet is considered safe.
+     * This value is overridden to `false` if payment was not verified.
+     */
+    safe: z.ZodBoolean;
+    /** Risk score from 0 (clean) to 100 (critical risk) */
+    risk: z.ZodNumber;
+    /** List of security findings */
+    findings: z.ZodArray<z.ZodObject<{
+        /** Machine-readable finding type (e.g. "unlimited_approval", "known_drainer") */
+        type: z.ZodString;
+        /** Severity of the finding */
+        severity: z.ZodEnum<["critical", "high", "medium", "low", "info"]>;
+        /** Human-readable description */
+        description: z.ZodString;
+        /** Relevant contract or counterparty address, if applicable */
+        address: z.ZodOptional<z.ZodString>;
+        /** Protocol name associated with the finding, if known */
+        protocol: z.ZodOptional<z.ZodString>;
+        /** Token amount at risk (human-readable), if applicable */
+        amount: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: string;
+        severity: "critical" | "high" | "medium" | "low" | "info";
+        description: string;
+        address?: string | undefined;
+        protocol?: string | undefined;
+        amount?: string | undefined;
+    }, {
+        type: string;
+        severity: "critical" | "high" | "medium" | "low" | "info";
+        description: string;
+        address?: string | undefined;
+        protocol?: string | undefined;
+        amount?: string | undefined;
+    }>, "many">;
+    /** Pre-built revoke transactions for risky approvals */
+    revokeTxs: z.ZodArray<z.ZodObject<{
+        /** Target contract address (the token contract) */
+        to: z.ZodString;
+        /** ABI-encoded calldata (e.g., `approve(spender, 0)`) */
+        data: z.ZodString;
+        /** EVM chain ID (e.g., 8453 for Base) */
+        chainId: z.ZodNumber;
+        /** Human-readable description of what this revoke does */
+        description: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        description: string;
+        to: string;
+        data: string;
+        chainId: number;
+    }, {
+        description: string;
+        to: string;
+        data: string;
+        chainId: number;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    scanId: string;
+    safe: boolean;
+    risk: number;
+    findings: {
+        type: string;
+        severity: "critical" | "high" | "medium" | "low" | "info";
+        description: string;
+        address?: string | undefined;
+        protocol?: string | undefined;
+        amount?: string | undefined;
+    }[];
+    revokeTxs: {
+        description: string;
+        to: string;
+        data: string;
+        chainId: number;
+    }[];
+}, {
+    scanId: string;
+    safe: boolean;
+    risk: number;
+    findings: {
+        type: string;
+        severity: "critical" | "high" | "medium" | "low" | "info";
+        description: string;
+        address?: string | undefined;
+        protocol?: string | undefined;
+        amount?: string | undefined;
+    }[];
+    revokeTxs: {
+        description: string;
+        to: string;
+        data: string;
+        chainId: number;
+    }[];
+}>;
+/** @see {@link ScanResultSchema} */
+export type ScanResult = z.infer<typeof ScanResultSchema>;
+/**
+ * A single ERC-20 token approval with risk assessment.
+ */
+export declare const ApprovalSchema: z.ZodObject<{
+    /** Address that has been approved to spend tokens */
+    spender: z.ZodString;
+    /** Token contract address */
+    token: z.ZodString;
+    /** Token symbol (e.g., "USDC"), if known */
+    tokenSymbol: z.ZodOptional<z.ZodString>;
+    /** Approved allowance amount (as string to handle large values) */
+    allowance: z.ZodString;
+    /** Risk level of this approval */
+    risk: z.ZodEnum<["low", "medium", "high", "critical"]>;
+    /** Human-readable details about why this is risky */
+    details: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    risk: "critical" | "high" | "medium" | "low";
+    spender: string;
+    token: string;
+    allowance: string;
+    tokenSymbol?: string | undefined;
+    details?: string | undefined;
+}, {
+    risk: "critical" | "high" | "medium" | "low";
+    spender: string;
+    token: string;
+    allowance: string;
+    tokenSymbol?: string | undefined;
+    details?: string | undefined;
+}>;
+/** @see {@link ApprovalSchema} */
+export type Approval = z.infer<typeof ApprovalSchema>;
+/**
+ * Aggregated approvals result for a wallet.
+ */
+export declare const ApprovalsResultSchema: z.ZodObject<{
+    /** The wallet address that was queried */
+    wallet: z.ZodString;
+    /** All active token approvals */
+    approvals: z.ZodArray<z.ZodObject<{
+        /** Address that has been approved to spend tokens */
+        spender: z.ZodString;
+        /** Token contract address */
+        token: z.ZodString;
+        /** Token symbol (e.g., "USDC"), if known */
+        tokenSymbol: z.ZodOptional<z.ZodString>;
+        /** Approved allowance amount (as string to handle large values) */
+        allowance: z.ZodString;
+        /** Risk level of this approval */
+        risk: z.ZodEnum<["low", "medium", "high", "critical"]>;
+        /** Human-readable details about why this is risky */
+        details: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        risk: "critical" | "high" | "medium" | "low";
+        spender: string;
+        token: string;
+        allowance: string;
+        tokenSymbol?: string | undefined;
+        details?: string | undefined;
+    }, {
+        risk: "critical" | "high" | "medium" | "low";
+        spender: string;
+        token: string;
+        allowance: string;
+        tokenSymbol?: string | undefined;
+        details?: string | undefined;
+    }>, "many">;
+    /** Count of approvals at each risk level */
+    riskCount: z.ZodObject<{
+        low: z.ZodNumber;
+        medium: z.ZodNumber;
+        high: z.ZodNumber;
+        critical: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        critical: number;
+        high: number;
+        medium: number;
+        low: number;
+    }, {
+        critical: number;
+        high: number;
+        medium: number;
+        low: number;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    wallet: string;
+    approvals: {
+        risk: "critical" | "high" | "medium" | "low";
+        spender: string;
+        token: string;
+        allowance: string;
+        tokenSymbol?: string | undefined;
+        details?: string | undefined;
+    }[];
+    riskCount: {
+        critical: number;
+        high: number;
+        medium: number;
+        low: number;
+    };
+}, {
+    wallet: string;
+    approvals: {
+        risk: "critical" | "high" | "medium" | "low";
+        spender: string;
+        token: string;
+        allowance: string;
+        tokenSymbol?: string | undefined;
+        details?: string | undefined;
+    }[];
+    riskCount: {
+        critical: number;
+        high: number;
+        medium: number;
+        low: number;
+    };
+}>;
+/** @see {@link ApprovalsResultSchema} */
+export type ApprovalsResult = z.infer<typeof ApprovalsResultSchema>;
+/**
+ * API health status.
+ */
+export declare const HealthResultSchema: z.ZodObject<{
+    /** Service health status */
+    status: z.ZodEnum<["ok", "degraded", "down"]>;
+    /** API version string, if available */
+    version: z.ZodOptional<z.ZodString>;
+    /** Process uptime in seconds, if available */
+    uptime: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    status: "ok" | "degraded" | "down";
+    version?: string | undefined;
+    uptime?: number | undefined;
+}, {
+    status: "ok" | "degraded" | "down";
+    version?: string | undefined;
+    uptime?: number | undefined;
+}>;
+/** @see {@link HealthResultSchema} */
+export type HealthResult = z.infer<typeof HealthResultSchema>;
+/**
+ * Payment requirements parsed from a 402 response.
+ * Used internally by JanusClient to build the payment signature.
+ */
+export declare const PaymentRequirementsSchema: z.ZodObject<{
+    /** Payment scheme (currently only "exact" is supported) */
+    scheme: z.ZodString;
+    /** CAIP-2 network identifier (e.g., "eip155:8453") */
+    network: z.ZodString;
+    /** Maximum amount required in token atomic units */
+    maxAmountRequired: z.ZodString;
+    /** Payment token contract address (Base USDC) */
+    asset: z.ZodString;
+    /** Payment recipient address */
+    payTo: z.ZodString;
+    /** Maximum seconds the payment authorization is valid for */
+    maxTimeoutSeconds: z.ZodNumber;
+    /** Extra EIP-712 domain metadata (name, version, etc.) */
+    extra: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    scheme: string;
+    network: string;
+    maxAmountRequired: string;
+    asset: string;
+    payTo: string;
+    maxTimeoutSeconds: number;
+    extra?: Record<string, unknown> | undefined;
+}, {
+    scheme: string;
+    network: string;
+    maxAmountRequired: string;
+    asset: string;
+    payTo: string;
+    maxTimeoutSeconds: number;
+    extra?: Record<string, unknown> | undefined;
+}>;
+/** @see {@link PaymentRequirementsSchema} */
+export type PaymentRequirements = z.infer<typeof PaymentRequirementsSchema>;
+/**
+ * Configuration for {@link JanusClient}.
+ */
+export interface JanusClientConfig {
+    /**
+     * Base URL for the x402janus API.
+     * @default "https://x402janus.com"
+     */
+    baseUrl?: string | undefined;
+    /**
+     * Agent's private key for signing x402 micropayments.
+     * Required for paid tiers (standard, deep).
+     * Falls back to `process.env.PRIVATE_KEY` if not set.
+     *
+     * **Security**: The private key is stored in memory only and never
+     * exposed in error messages, logs, or API responses.
+     */
+    privateKey?: string | undefined;
+    /**
+     * Default scan tier when not specified per-call.
+     * @default "quick"
+     */
+    defaultTier?: ScanTier | undefined;
+    /**
+     * Thirdweb/x402 facilitator URL for payment verification.
+     * Falls back to `process.env.FACILITATOR_URL` then the Thirdweb default.
+     * @default "https://api.thirdweb.com/v1/payments/x402"
+     */
+    facilitatorUrl?: string | undefined;
+}
+/**
+ * Options for a single wallet scan call.
+ */
+export interface ScanOptions {
+    /**
+     * Override the default tier for this scan.
+     */
+    tier?: ScanTier | undefined;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,147 @@
+/**
+ * @module types
+ * All public types and Zod schemas for @x402janus/sdk.
+ */
+import { z } from "zod";
+// ─── Tier ────────────────────────────────────────────────────────────────────
+/**
+ * Scan tier controlling analysis depth and x402 micropayment amount.
+ *
+ * | Tier     | Price  | Description                                         |
+ * |----------|--------|-----------------------------------------------------|
+ * | quick    | $0.01  | Fast heuristic scan — known drainers & risk signals |
+ * | standard | $0.05  | Graph analysis + threat-intel correlation           |
+ * | deep     | $0.25  | Full forensic scan + approval chain tracing         |
+ */
+export const ScanTierSchema = z.enum(["quick", "standard", "deep"]);
+/**
+ * USDC pricing for each scan tier (6-decimal precision, Base mainnet).
+ * `units` is the raw USDC atomic value passed in the x402 payment header.
+ */
+export const TIER_PRICES = {
+    quick: { dollars: "$0.01", units: "10000" },
+    standard: { dollars: "$0.05", units: "50000" },
+    deep: { dollars: "$0.25", units: "250000" },
+};
+/**
+ * A single security finding returned in a wallet scan.
+ */
+export const FindingSchema = z.object({
+    /** Machine-readable finding type (e.g. "unlimited_approval", "known_drainer") */
+    type: z.string(),
+    /** Severity of the finding */
+    severity: z.enum(["critical", "high", "medium", "low", "info"]),
+    /** Human-readable description */
+    description: z.string(),
+    /** Relevant contract or counterparty address, if applicable */
+    address: z.string().optional(),
+    /** Protocol name associated with the finding, if known */
+    protocol: z.string().optional(),
+    /** Token amount at risk (human-readable), if applicable */
+    amount: z.string().optional(),
+});
+// ─── RevokeTx ────────────────────────────────────────────────────────────────
+/**
+ * A revoke transaction that the agent can sign and submit to remove a risky approval.
+ * Transactions are pre-built by the x402janus API — submit them as-is.
+ */
+export const RevokeTxSchema = z.object({
+    /** Target contract address (the token contract) */
+    to: z.string(),
+    /** ABI-encoded calldata (e.g., `approve(spender, 0)`) */
+    data: z.string(),
+    /** EVM chain ID (e.g., 8453 for Base) */
+    chainId: z.number().int().positive(),
+    /** Human-readable description of what this revoke does */
+    description: z.string(),
+});
+// ─── ScanResult ──────────────────────────────────────────────────────────────
+/**
+ * Full result of a wallet security scan.
+ *
+ * **Security invariant**: `safe` is always `false` when payment was not
+ * successfully verified. Never trust `safe: true` from an unpaid response.
+ */
+export const ScanResultSchema = z.object({
+    /** Unique identifier for this scan (for audit/logging) */
+    scanId: z.string(),
+    /**
+     * Whether the wallet is considered safe.
+     * This value is overridden to `false` if payment was not verified.
+     */
+    safe: z.boolean(),
+    /** Risk score from 0 (clean) to 100 (critical risk) */
+    risk: z.number().min(0).max(100),
+    /** List of security findings */
+    findings: z.array(FindingSchema),
+    /** Pre-built revoke transactions for risky approvals */
+    revokeTxs: z.array(RevokeTxSchema),
+});
+// ─── Approvals ───────────────────────────────────────────────────────────────
+/**
+ * A single ERC-20 token approval with risk assessment.
+ */
+export const ApprovalSchema = z.object({
+    /** Address that has been approved to spend tokens */
+    spender: z.string(),
+    /** Token contract address */
+    token: z.string(),
+    /** Token symbol (e.g., "USDC"), if known */
+    tokenSymbol: z.string().optional(),
+    /** Approved allowance amount (as string to handle large values) */
+    allowance: z.string(),
+    /** Risk level of this approval */
+    risk: z.enum(["low", "medium", "high", "critical"]),
+    /** Human-readable details about why this is risky */
+    details: z.string().optional(),
+});
+/**
+ * Aggregated approvals result for a wallet.
+ */
+export const ApprovalsResultSchema = z.object({
+    /** The wallet address that was queried */
+    wallet: z.string(),
+    /** All active token approvals */
+    approvals: z.array(ApprovalSchema),
+    /** Count of approvals at each risk level */
+    riskCount: z.object({
+        low: z.number().int().min(0),
+        medium: z.number().int().min(0),
+        high: z.number().int().min(0),
+        critical: z.number().int().min(0),
+    }),
+});
+// ─── Health ──────────────────────────────────────────────────────────────────
+/**
+ * API health status.
+ */
+export const HealthResultSchema = z.object({
+    /** Service health status */
+    status: z.enum(["ok", "degraded", "down"]),
+    /** API version string, if available */
+    version: z.string().optional(),
+    /** Process uptime in seconds, if available */
+    uptime: z.number().optional(),
+});
+// ─── x402 Payment Requirements ───────────────────────────────────────────────
+/**
+ * Payment requirements parsed from a 402 response.
+ * Used internally by JanusClient to build the payment signature.
+ */
+export const PaymentRequirementsSchema = z.object({
+    /** Payment scheme (currently only "exact" is supported) */
+    scheme: z.string(),
+    /** CAIP-2 network identifier (e.g., "eip155:8453") */
+    network: z.string(),
+    /** Maximum amount required in token atomic units */
+    maxAmountRequired: z.string().regex(/^\d+$/, "must be a decimal integer string"),
+    /** Payment token contract address (Base USDC) */
+    asset: z.string(),
+    /** Payment recipient address */
+    payTo: z.string(),
+    /** Maximum seconds the payment authorization is valid for */
+    maxTimeoutSeconds: z.number().int().positive(),
+    /** Extra EIP-712 domain metadata (name, version, etc.) */
+    extra: z.record(z.unknown()).optional(),
+});
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@x402janus/sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for x402janus wallet security scans with automatic x402 micropayment handling",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "type-check": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "viem": "^2.21.0",
+    "zod": "^3.22.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "x402",
+    "wallet",
+    "security",
+    "scan",
+    "base",
+    "ethereum",
+    "drainer",
+    "approvals",
+    "ai-agent"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/x402janus/sdk"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}