zkverify-kurier

name: zkverify-kurier description: Kurier REST API for simplified proof verification. Use when you want the simplest integration path, don't need real-time events, or are building serverless/REST-based architectures. Covers API key setup, proof submission, status polling, and aggregation.

Kurier REST API Integration

Kurier provides HTTP-based proof verification - the simplest integration path for zkVerify.

When to Use Kurier

• Serverless/REST architectures - No WebSocket required
• Simple integrations - HTTP POST/GET instead of blockchain SDKs
• Polling-based workflows - Check status periodically
• Quick prototyping - No blockchain library dependencies

For real-time events or direct chain access, see zkverify-sdk or zkverify-rpc.

Quick Start

1. Prerequisites

1. Sign up at kurier.xyz (mainnet) or testnet.kurier.xyz
2. Generate an API key from the dashboard
3. Install dependencies: npm i axios dotenv

2. Environment Setup

# .env
KURIER_API_KEY=your_generated_api_key
KURIER_API_URL=https://api.kurier.xyz  # or https://api-testnet.kurier.xyz

3. Basic Implementation

import axios from "axios";
import dotenv from "dotenv";
dotenv.config();

const API_URL = "https://api.kurier.xyz";  // or https://api-testnet.kurier.xyz

// Register VK (one-time)
const vkResponse = await axios.post(`${API_URL}/api/v1/register-vk/${process.env.API_KEY}`, {
  proofType: "groth16",
  proofOptions: { library: "snarkjs", curve: "bn128" },
  vk: vkey
});
const vkHash = vkResponse.data.vkHash;

// Submit proof
const submitResponse = await axios.post(`${API_URL}/api/v1/submit-proof/${process.env.API_KEY}`, {
  proofType: "groth16",
  vkRegistered: true,
  proofOptions: { library: "snarkjs", curve: "bn128" },
  proofData: { proof, publicSignals, vk: vkHash }
});

console.log("Job ID:", submitResponse.data.jobId);

// Poll for finalization
while (true) {
  const status = await axios.get(
    `${API_URL}/api/v1/job-status/${process.env.API_KEY}/${submitResponse.data.jobId}`
  );
  if (status.data.status === "Finalized") break;
  await new Promise(r => setTimeout(r, 5000));
}

4. With Aggregation (Cross-Chain)

Add chainId to enable aggregation for L1 verification:

const response = await axios.post(`${API_URL}/api/v1/submit-proof/${API_KEY}`, {
  proofType: "groth16",
  vkRegistered: true,
  chainId: 8453,  // Base mainnet
  proofOptions: { library: "snarkjs", curve: "bn128" },
  proofData: { proof, publicSignals, vk: vkHash }
});

// Poll until status === "Aggregated"
// Response includes aggregationDetails with merkleProof

Job Status Lifecycle

Without Aggregation (no chainId)

Queued → Valid → Submitted → IncludedInBlock → Finalized

Finalized is terminal. The proof is on zkVerify and has a stable txHash.

With Aggregation (chainId set — this is what you want for on-chain use)

[Queued → Valid] → IncludedInBlock → AggregationPending → Aggregated → (AggregationPublished)

• Queued / Valid may not be observed at a 5s polling cadence — the proof typically reaches IncludedInBlock within the first poll.
• IncludedInBlock = proof is in a zkVerify block. txHash and blockHash are populated from this point forward.
• AggregationPending = waiting to be included in an aggregation batch. This is the longest-lived state — typically 1–3 minutes.
• Aggregated = terminal for downstream use. aggregationDetails (with merkleProof, leaf, leafIndex, numberOfLeaves) is now populated. Use this for relay polling and recordValidation.
• AggregationPublished = aggregation has been published to the destination chain. You don't need to wait for this — Aggregated is sufficient.

Observed timing (Base Sepolia, April 2026): ~5s to IncludedInBlock, ~25s to AggregationPending, ~165s to Aggregated. Total: ~3 minutes end-to-end (submit → Aggregated).

Important: With chainId set you typically do NOT see Finalized — the proof goes straight from AggregationPending to Aggregated. Do not wait for Finalized in the aggregation path. Stop polling as soon as you see Aggregated (or AggregationPublished).

Polling Best Practices

When polling with aggregation enabled (chainId set), handle each status distinctly:

const POLL_INTERVAL_MS = 5000;
const MAX_POLL_ATTEMPTS = 120; // 10 minutes

for (let i = 0; i < MAX_POLL_ATTEMPTS; i++) {
  await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));

  const res = await fetch(`${API_URL}/api/v1/job-status/${API_KEY}/${jobId}`);
  const { status, txHash, aggregationId, aggregationDetails } = await res.json();

  if (status === "Failed") {
    throw new Error("Proof verification failed");
  }

  if (status === "IncludedInBlock" || status === "AggregationPending") {
    // Proof is on zkVerify but NOT yet aggregated — keep polling.
    // txHash and blockHash are populated from IncludedInBlock onwards —
    // save them now for explorer links + on-chain recordValidation inputs.
    continue;
  }

  if (status === "Aggregated" || status === "AggregationPublished") {
    // Terminal — aggregationDetails is now populated with the Merkle proof.
    return { aggregationId, aggregationDetails, txHash, blockHash };
  }

  // Early states (Queued, Valid) — rarely observed at this polling cadence,
  // just continue.
}

throw new Error("Polling timed out");

Common mistakes:

• Treating Finalized as terminal when chainId is set — aggregation hasn't happened yet
• Capturing txHash at IncludedInBlock and updating DB status to "finalized" prematurely
• Lumping multiple statuses together in a single if block — handle each distinctly

API Endpoints

See endpoints.md for complete API reference with request/response schemas.

Job Status States

Response Fields by Status

The job-status response includes additional fields as the proof progresses:

Important: txHash is the zkVerify blockchain extrinsic hash, not a Base/Ethereum transaction hash. Use it to build explorer links for proof transparency in your UI.

zkVerify Explorer

View finalized proofs on the zkVerify blockchain explorer:

Format: https://zkverify.subscan.io/extrinsic/{txHash}

After a proof reaches "Finalized" status, use the txHash from the job status response to view details on the zkVerify blockchain explorer. The explorer shows proof verification details, block information, transaction hashes, and gas fees.

See zkverify-explorer.md for complete details.

Additional Resources

Documentation

• Mock testing: mock-testing.md
• TypeScript types: typescript-types.md
• zkVerify Explorer: zkverify-explorer.md
• API endpoints: endpoints.md
• Proof type configs: proof-types.md
• Chain IDs for aggregation: network-config.md

External Resources

• Swagger: api.kurier.xyz/docs
• Support: kurier-support@horizenlabs.io
• Discord: discord.gg/zkverify

Related Skills

• hl-registry-integration — Continue the pipeline: after Aggregated, wait for attestation relay on Base Sepolia and record the validation on the HL Marketplace ValidationGateway.
• zkverify-sdk — TypeScript SDK with real-time events (alternative to polling)
• zkverify-attestation — Cross-chain attestation workflow
• zkverify-contracts — Direct smart-contract verification