Getting Started

The @zkstash/sdk package provides a type-safe, easy-to-use interface for interacting with the zkstash API. It handles all the complexity of authentication signatures and x402 payment flows automatically.

Installation

pnpm add @zkstash/sdk

npm install @zkstash/sdk

yarn add @zkstash/sdk

Initialization

You can initialize the client in two ways: using a single private key for everything, or using separate signers for identity and payments.

Quick Start (Single Wallet)

Use fromPrivateKey when you want to use the same wallet for both authentication (identity) and paying for credits. This is the most common pattern for simple agents.

import { fromPrivateKey } from "@zkstash/sdk/rest";
 
const authPrivateKey = process.env.AUTH_PRIVATE_KEY;
const client = await fromPrivateKey(
  authPrivateKey,           // Used for Auth + x402 payments
  {
    payment: {
      maxValue: 5000n
    }
  }
);

Advanced (Separate Signers)

Use the ZkStash constructor directly if you need to separate the Identity (who is acting) from the Payer (who is funding the request).

This is useful for:

• Delegated Access: An agent acts on behalf of a user, but the user pays for the credits.
• Security: Keeping the funding wallet separate from the operational agent wallet.

import { ZkStash } from "@zkstash/sdk/rest";
import { createSigner } from "x402-fetch";
 
// 1. Identity Signer (e.g., the Agent's wallet)
const authSigner = await createSigner("solana", process.env.AGENT_KEY);
 
// 2. Payment Signer (e.g., the User's wallet)
const paymentSigner = await createSigner("base-sepolia", process.env.USER_KEY);
 
const client = new ZkStash({
  signer: authSigner,
  payment: {
    signer: paymentSigner,
  }
});