Documentation

CipherPay enables AI agents and automated clients to pay for API access using shielded Zcash. It supports two open standards — x402 (HTTP 402 Payment Required) and the Machine Payments Protocol (MPP) — plus prepaid sessions for high-frequency agent workflows. All payments are verified via trial decryption using your viewing key.

The @cipherpay/x402 middleware auto-detects which protocol the client is using and handles all three flows transparently. Session tokens are checked first, then MPP headers, then x402 headers.

When an unauthenticated request arrives, the middleware responds with HTTP 402 and includes payment terms. For x402, this is a JSON body with the PAYMENT-REQUIRED header. For MPP, the challenge is in the WWW-Authenticate: Payment header. Both contain the same information: price, address, network, and facilitator URL.

Every transaction ID is tracked per-merchant. Once a txid has been used to verify a payment, it cannot be reused to gain access again. The verify endpoint returns "valid": false with reason "already_used" for duplicate txids.

Every AI agent payment on Base, Solana, or Polygon is a public record. Competitors can reconstruct your agent's entire operational strategy — what APIs it calls, what data it buys, how often, and how much it spends. On transparent chains, agent payment metadata is a surveillance goldmine.

With Zcash shielded payments, all of that is invisible. The sender, receiver, amount, and frequency are fully encrypted on-chain. CipherPay verifies payments using your viewing key, but the agent's identity, balance, and activity remain completely private.

The fastest way to accept shielded ZEC payments on your API. One middleware, one line.

npm install @cipherpay/x402

import express from 'express';
import { zcashPaywall } from '@cipherpay/x402/express';

const app = express();

app.use('/api/premium', zcashPaywall({
  amount: 0.001,          // ZEC per request
  address: 'u1abc...',    // Your Zcash Unified Address
  apiKey: 'cpay_sk_...',  // CipherPay API key
}));

app.get('/api/premium/data', (req, res) => {
  res.json({ temperature: 18, conditions: 'partly cloudy' });
});

The middleware handles all three protocols automatically: returns 402 challenges for x402 and MPP clients, validates session bearer tokens, verifies payment txids, and enforces replay protection.

app.use('/api/ai', zcashPaywall({
  address: 'u1abc...',
  apiKey: 'cpay_sk_...',
  amount: 0,
  getAmount: (req) => {
    if (req.url.includes('gpt-4')) return 0.01;
    if (req.url.includes('gpt-3')) return 0.001;
    return 0.0005;
  },
}));

The SDK also exports a standalone verifyPayment function for custom integrations:

import { verifyPayment } from '@cipherpay/x402';

const result = await verifyPayment(txid, 0.001, 'cpay_sk_...');
if (result.valid) {
  // Payment confirmed — grant access
}

For agents that make many requests, paying per-call is expensive and slow. Sessions let an agent deposit ZEC once, receive a bearer token, and use it for subsequent requests — with the balance deducted automatically per-request.

First, call POST /api/sessions/prepare with the merchant's API key to get a unique deposit address and a session_request_id. Send ZEC to that address, then call POST /api/sessions/open with the session_request_id and the txid. Minimum deposit is 10,000 zatoshis (0.0001 ZEC). The bearer token is returned once the deposit is detected, and expires after the configured TTL (default 24h).

{
  "x402Version": 2,
  "resource": { "url": "/api/data" },
  "accepts": [{
    "scheme": "exact",
    "network": "zcash:mainnet",
    "asset": "ZEC",
    "amount": "100000",
    "payTo": "u1yourpaymentaddress...",
    "maxTimeoutSeconds": 120,
    "extra": {}
  }]
}

WWW-Authenticate: Payment scheme="exact", network="zcash:mainnet",
  asset="ZEC", amount="100000", payTo="u1yourpaymentaddress...",
  facilitator="https://api.cipherpay.app/api/x402/verify"

curl -X POST https://api.cipherpay.app/api/x402/verify \
  -H "Authorization: Bearer cpay_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "txid": "a1b2c3d4e5f6...",
    "expected_amount_zec": 0.001
  }'

{
  "valid": true,
  "received_zec": 0.001,
  "received_zatoshis": 100000
}

A minimal Express.js server with the full agentic payment flow — x402, MPP, sessions, and replay protection:

import express from 'express';
import { zcashPaywall } from '@cipherpay/x402/express';

const app = express();

app.use('/api/premium', zcashPaywall({
  amount: 0.001,
  address: 'u1youraddress...',
  apiKey: process.env.CIPHERPAY_API_KEY,
}));

app.get('/api/premium/data', (req, res) => {
  res.json({ message: 'You paid for this!' });
});

All verification calls are logged and accessible via the dashboard (Agentic Payments tab) or the history endpoint. Each entry shows which protocol was used (x402 or MPP), the amount, and the verification result.

curl https://api.cipherpay.app/api/merchants/me/x402/history \
  -H "Authorization: Bearer cpay_sk_YOUR_KEY"

Returns a paginated list with ?limit= and ?offset= query parameters (max 200 per page).

CipherPay exposes a /.well-known/payment endpoint for agent discovery. AI agents can query this URL to learn that a merchant supports Zcash payments via CipherPay, and which protocols (x402, MPP) are available.

curl https://api.cipherpay.app/.well-known/payment

This follows the emerging pattern of machine-readable payment metadata at well-known paths, letting agents auto-discover payment capabilities without human configuration.