zkFetch.js

fetch, but with a zkproof

Overview

This library lets you fetch any remote resource over an https endpoint. Along with the response, you also get a proof of correct execution of the fetch that can be verified by a third party.

For example, if you do a fetch with a private api key that the third party doesn't have access to, how do you prove to them that you executed the fetch correctly using the api key, and not sharing with them an arbitrary or tampered response? zkfetch.

Key features:

• Generate verifiable proofs of HTTP requests
• Support for private credentials (API keys, auth headers) and secret params
• Response matching and redaction
• Built on Reclaim Protocol

Installation

npm install @reclaimprotocol/zk-fetch

Prerequisites

• Node.js version 18 or higher
• An application ID and secret from the Reclaim Developer Portal

Quick Start

const { ReclaimClient } = require("@reclaimprotocol/zk-fetch");

// Initialize client
const client = new ReclaimClient('APPLICATION_ID', 'APPLICATION_SECRET');

// Make a verified request
const proof = await client.zkFetch('https://api.coingecko.com/api/v3/simple/price?ids=ethereum&vs_currencies=usd', {
  method: 'GET',
  headers: {
    accept: 'application/json'
  }
}, {
  responseMatches: [{
    type: 'regex',
    value: 'ethereum":{"usd":(?<price>.*?)}}',
  }],
  responseRedactions: [{ regex: 'ethereum":{"usd":(?<price>.*?)}}'}],  
});

Authentication Methods

zkFetch supports two authentication modes depending on where you're running the code:

Backend Mode (Direct Secret)

Use this when running on a secure server (Node.js backend). Your application secret stays safe on the server.

const { ReclaimClient } = require('@reclaimprotocol/zk-fetch');

// Backend only - never expose secret in frontend!
const client = new ReclaimClient('APPLICATION_ID', 'APPLICATION_SECRET');

const proof = await client.zkFetch('https://api.example.com/data', {
  method: 'GET'
});

Frontend Mode (Signature-Based)

Use this for browsers or untrusted environments. Your application secret never leaves your backend.

Step 1: Generate signature on your backend

const { generateSessionSignature } = require('@reclaimprotocol/zk-fetch');

// Backend API endpoint
app.post('/api/get-signature', async (req, res) => {
  const signature = await generateSessionSignature({
    applicationId: process.env.APP_ID,
    applicationSecret: process.env.APP_SECRET,
    allowedUrls: [
      'https://api.coingecko.com/*',                  // Wildcard - all paths under domain
      'https://api.example.com/public/data',          // Exact URL match
      '^https://api\\.example\\.com/user/\\d+$'        // Regex pattern
    ],
    expiresAt: Math.floor(Date.now() / 1000) + 3600  // Expires in 1 hour (optional)
  });

  res.json({ signature });
});

Step 2: Use signature in your frontend

const { ReclaimClient } = require('@reclaimprotocol/zk-fetch');

// Fetch signature from your backend
const response = await fetch('/api/get-signature');
const { signature } = await response.json();

// Initialize with signature - safe for frontend!
const client = new ReclaimClient(
  'APPLICATION_ID',
  signature
);

// Make requests (only to URLs in allowlist)
const proof = await client.zkFetch(
  'https://api.coingecko.com/api/v3/simple/price?ids=bitcoin&vs_currencies=usd',
  { method: 'GET' }
);

Signature Features:

• Time-limited (default 1 hour, max 72 hours)
• URL-restricted via allowlist (exact, wildcard, or regex patterns)
• Cryptographically signed (ECDSA)
• No secrets exposed to frontend

URL Pattern Examples:

• 'https://api.example.com/data' - Exact match only
• 'https://api.example.com/*' - All paths under domain
• '^https://api\\.example\\.com/user/\\d+$' - Regex pattern for dynamic URLs

Builder Mode (Organization Token)

Use this if you manage your zkFetch usage through Reclaim Builder. Instead of an application id/secret, the client holds a Builder organization token (rorg_...) and asks Builder to authorize each zkFetch call, drawing down your org's ZKFETCH quota.

const { ReclaimClient } = require('@reclaimprotocol/zk-fetch');

const client = new ReclaimClient({
  orgToken: 'rorg_...',              // your Builder organization token
  builderBaseUrl: undefined,          // optional, defaults to https://build.reclaimprotocol.org
});

const proof = await client.zkFetch('https://api.github.com/user', {
  method: 'GET',
  headers: { Authorization: 'Bearer <github token>' },
});

Every call asks Builder for a short-lived, single-use authorization for the request's target host immediately before connecting to the attestor -- it is never requested ahead of time or reused across calls. This is what actually meters zkFetch against your Builder plan; the fetch and the proof itself still happen entirely in your own process, exactly as in the other modes.

If your org's ZKFETCH quota is exhausted, Builder rejects the authorization and the call rejects with a BuilderQuotaExceededError (a subclass of BuilderAuthorizationError) instead of a generic error, so you can catch it specifically:

const { ReclaimClient, BuilderQuotaExceededError } = require('@reclaimprotocol/zk-fetch');

try {
  const proof = await client.zkFetch('https://api.github.com/user', { method: 'GET' });
} catch (error) {
  if (error instanceof BuilderQuotaExceededError) {
    // error.status is 402 or 429
    console.error('Out of zkFetch quota for this billing period');
  } else {
    throw error;
  }
}

Builder mode does not currently support useTee: true; it only covers the standard (non-TEE) zkFetch path.

Client Configuration

The constructor accepts two optional arguments after the credentials:

new ReclaimClient(applicationId, applicationSecret, logs?, retries?)

Argument	Type	Default	Description
logs	boolean	false	Enable internal logging.
retries	number	1	Default number of attempts for every zkFetch call that doesn't pass its own retries. Must be a positive integer.

// logs enabled, and every zkFetch defaults to 3 attempts
const client = new ReclaimClient('APPLICATION_ID', 'APPLICATION_SECRET', true, 3);

Using TEE Mode

TEE (Trusted Execution Environment) mode can be enabled per-request by setting useTee: true in the options:

const proof = await client.zkFetch('https://api.example.com/data', {
  method: 'GET',
  useTee: true  // Enable TEE mode for this specific request
});

Choosing the ZK Engine (non-TEE)

The non-TEE path uses the stwo proof engine by default. You can opt back into snarkjs per request:

const proof = await client.zkFetch('https://api.example.com/data', {
  method: 'GET',
  zkEngine: 'snarkjs'  // 'snarkjs' | 'stwo' (default 'stwo')
});

zkEngine is ignored when useTee: true — the TEE path picks its own engine.

snarkjs requires extra setup. snarkjs proofs need the chacha20 / aes-128-ctr / aes-256-ctr circuit files (circuit.wasm, circuit_final.zkey, circuit.r1cs) which are not shipped in the npm tarball. After npm install, run the bundled downloader once:

node node_modules/@reclaimprotocol/zk-symmetric-crypto/lib/scripts/download-files

Without these files, zkEngine: 'snarkjs' will fail at proof-generation time. stwo ships its assets inline, so the default path works out of the box.

Usage

For public endpoints

If the endpoint you want to fetch and generate a proof of the response. This endpoint is public, and doesn't need any private data like auth headers/api keys.

This is useful when

• Verifier needs to verify without re-doing the api call
• The API doesn't need any private headers or auth
• The proof or response needs to be generated for a particular endpoint now, and verified later

  const publicOptions = {
    method: 'GET', // or POST or PUT
    headers : {
        accept: 'application/json, text/plain, */*' 
    }
  }
  const proof = await client.zkFetch(
    'https://your.url.org',
    publicOptions
  )

Note : all the data in the publicOptions will be visible to them who you share the proof with (aka, verifier).

For private endpoint

If you want to fetch and generate a proof of the response, but the fetch involves some private data like auth headers or api keys

This is useful when

• Using API keys
• Using Auth headers

  const publicOptions = {
    method: 'GET', // or POST
    headers : {
      accept: 'application/json, text/plain, */*' 
    }
  }

  const privateOptions = {
    headers {
        apiKey: "123...456",
        someOtherHeader: "someOtherValue",
    }
  }

  const proof = await client.zkFetch(
    'https://your.url.org',
    publicOptions,
    privateOptions
  )

All the data in the privateOptions will stay hidden to the verifier.

Using Secret Params

You can add secret params to the request. This won't be revealed in the proof and hidden from the verifier.

For example, here's how you can make a POST request with a body containing a JSON object that includes a secret value

  const publicOptions = {
    method: 'POST',
    body: JSON.stringify({
      'param1': '{{value}}'
    })
  }

  const privateOptions = {
    paramValues: {
      'value': 'secret_value'
    }
  }

  const proof = await client.zkFetch(
    'https://your.url.org',
    publicOptions,
    privateOptions
  )

This will replace the '{{value}}' in the body with 'secret_value' and send the request to the server. but the secret_value will remain hidden from the verifier and will not be revealed in the proof.

Using CookieStr

You can add cookieStr to the request. This won't be revealed in the proof and hidden from the verifier.

  const privateOptions = {
    cookieStr: 'cookie_value'
  }

Using Response Matches and Redactions

You can also use responseMatches and responseRedactions to match and redact the response. This is useful when you want to verify the response against a particular value or redact some part of the response.

 const publicOptions = {
    method: 'GET', // or POST
    headers : {
      accept: 'application/json, text/plain, */*' 
    }
  }

  const privateOptions = {
    responseMatches: [
      {
        type: 'contains' | 'regex', // type of match 
        value: '<HTTP RESPONSE TEXT>' | '<REGEX>', // value to match or regex to match 
      }
    ],
    responseRedactions: [
      {
        jsonPath: '$.data', // JSON path to redact 
        xPath: '/data', // Xpath to redact  
        regex: '<REGEX>', // Regex to redact
        // Optional: replace the matched span with an OPRF commitment instead
        // of a plain redaction byte. When set, `extractedParameterValues.<name>`
        // returns the OPRF hash string (not the plaintext).
        //   'oprf'     — only honored on the TEE path (`useTee: true`)
        //   'oprf-raw' — only honored on the non-TEE path
        hash: 'oprf' // 'oprf' | 'oprf-raw'
      }
    ]
  }

  const proof = await client.zkFetch(
    'https://your.url.org',
    publicOptions,
    privateOptions
  )

Using Context

You can add context to your proof request, which can be useful for providing additional information:

  const publicOptions = {
    context: {
      contextAddress: '0x0000000000000000000000000000000000000000',
      contextMessage: 'message'
    }
  }

Using the response

The response looks like the follows

{
  claimData: {
    provider: 'http',
    parameters: '{"body":"","method":"GET","responseMatches":[{"type":"regex","value":"ethereum\\":{\\"usd\\":(?<price>.*?)}}"}],"responseRedactions":[],"url":"https://api.coingecko.com/api/v3/simple/price?ids=ethereum&vs_currencies=usd"}',
    owner: '0x96faf173bb7171a530b3e44f35f32d1307bda4fa',
    timestampS: 1725377559,
    context: '{"contextAddress":"0x0000000000000000000000000000000000000000","contextMessage":"message","extractedParameters":{"price":"2446.75"},"providerHash":"0xe5a9592ed030d011f1755f392c07aea1f3cb0492ad8910254b25f80ad556e3bb"}',
    identifier: '0x8518b246857a47658edc8314319305c1fb5eb666ec3ee36ae07e1564c73ff288',
    epoch: 1
  },
  identifier: '0x8518b246857a47658edc8314319305c1fb5eb666ec3ee36ae07e1564c73ff288',
  signatures: [
    '0x02d14b5f3377875ecab84125e53c2387b7b1a50b4762840b33dd24117326b88670818e24668aa65c5e80f8d71c192ba5803a9ca1415d72a81f3efcf1341379d41c'
  ],
  extractedParameterValues: { price: '2446.75' },
  witnesses: [
    {
      id: '0x307832343438393735373233363865616466363562666263356165633938643865353434336139303732',
      url: 'wss://witness.reclaimprotocol.org/ws'
    }
  ]
}

Verify the proofs and transform proof for onchain

Verify the proofs

Install @reclaimprotocol/js-sdk

$ npm install @reclaimprotocol/js-sdk

Import the verifyProof function from the js-sdk

const { verifyProof } = require('@reclaimprotocol/js-sdk');

Use verifyProof(proof)

You must send the proofObject and not the verifiedResponse to the verifier for them to be able to verify.

const isProofVerified = await verifyProof(proof);

it verifies the authenticity and completeness of a given proof. It checks if the proof contains signatures, recalculates the proof identifier, and verifies it against the provided signatures. If the verification fails, it will log the error and return false.

Transform proof for onchain

Transforms proof data into a format suitable for on-chain transactions, you need to use it before sending the proof to the blockchain.

Import the transformForOnchain function from the js-sdk

const { transformForOnchain } = require('@reclaimprotocol/js-sdk');

Use transformForOnchain(proof) to transform the proof for onchain.

const onchainProof = transformForOnchain(proof);

Add Retries and Retry Interval

You can add retries and a retry interval to the fetch request. The per-call default for retries is 1 (or whatever you set as the client-level default in the constructor), and retryInterval defaults to 1000ms. A per-call value overrides the client default.

  const publicOptions = {
    method: 'GET', // or POST
    headers : {
      accept: 'application/json, text/plain, */*' 
    }
  }

  const privateOptions = {
    headers {
        apiKey: "123...456",
        someOtherHeader: "someOtherValue",
    }
  }

  const proof = await client.zkFetch(
    'https://your.url.org',
    publicOptions,
    privateOptions,
    5, // retries
    10000 // retryInterval
  )

TEE note: on the TEE path (useTee: true), a fresh enclave allocation can time out on a cold start. To avoid a single transient timeout hard-failing the request, the TEE path automatically retries such transient failures a few times even when retries is 1. Non-transient errors still fail fast per your retries.

Add GeoLocation

You can add geolocation information to your fetch request. The default value for geoLocation is null.

Note: The geoLocation should be a two-letter ISO country code, for example, 'US' for the United States.

  const publicOptions = {
    method: 'GET', // or POST
    headers : {
      accept: 'application/json, text/plain, */*' 
    }
    // geoLocation should be a two-letter ISO country code, e.g., 'US' for the United States
    geoLocation: 'US'
  }

  const proof = await client.zkFetch(
    'https://your.url.org',
    publicOptions,
  )

More examples

you can find more examples/starter packs here

• React Example
• Express Example
• NestJS Example
• Next.js Example

License

This library is governed by an AGPL license. That means, you can fork, modify and use for commercial use as long as the entire project is fully open sourced under an AGPL License.

If you wish to use commercially use this library in a closed source product, you must take permission.