Integration - Numpay Docs

Specification, not yet live. The packages and endpoints below are planned names; they aren’t published yet. Code here is an outline of the intended interface.

Packages

npm install @numpay/zk-sdk @numpay/core snarkjs ethers

pip install numpay-zk-sdk numpay-core snarkjs-py web3

1. Client setup

client/numpayZKClient.ts

import { NumPayZKClient } from '@numpay/zk-sdk';
import { NumPayCore } from '@numpay/core';

export class NumPayPrivateClient {
  core = new NumPayCore({
    privateKey: process.env.PRIVATE_KEY!,
    phoneNumber: '+14155550123',
    encryptIdentity: true,
    network: 'mainnet',
  });
  zk = new NumPayZKClient({
    circuitUrl: 'https://api.numpay.io/zk/circuits',
    provingKeyUrl: 'https://api.numpay.io/zk/proving-key',
    verificationKeyUrl: 'https://api.numpay.io/zk/verification-key',
  });

  initialize() { /* load circuits and keys */ }
  getWalletAddress() { /* … */ }
  resolvePhoneToWallet(phone: string) { /* GET /phone/resolve/:phone */ }
  linkPhoneToWallet() { /* POST /phone/link */ }
}

2. Generate a private payment proof

client/generateProof.ts

const proof = await generatePrivatePayment(senderPhone, recipientPhone, amount, resourceUrl, {
  hideAmount: true,
  hideSender: true,
  usePhoneMapping: true,
  metadata: { paymentReason: 'x402 API access', encryptMetadata: true },
});

3. Protect an API with x402 middleware

When a request has no valid x-payment-proof header, the middleware answers 402:

HTTP/1.1 402 Payment Required
WWW-Authenticate: x402-zk
Content-Type: application/json

{
  "protocol": "x402",
  "method": "numpay-zk",
  "currency": "USDC",
  "amountEncryption": "elgamal",
  "proofSystem": "groth16",
  "verifyEndpoint": "https://api.numpay.io/zk/verify",
  "settleEndpoint": "https://api.numpay.io/zk/settle"
}

With a proof present, the middleware checks:

the proof is valid;
the amount is within range (10% tolerance);
the recipient matches the merchant;
the proof is less than 5 minutes old.

4. Example server

server/app.ts

const app = express();
const pricePerRequest = 0.10; // USDC

app.get('/health', (_req, res) => res.json({ service: 'numpay-zk-x402' }));   // free
app.use('/api/premium', x402ZKMiddleware({ pricePerRequest }));
app.get('/api/premium/data', handler);
app.post('/api/premium/ai-query', handler);

Environment: MERCHANT_PHONE, MERCHANT_WALLET, PORT.

5. Client that pays automatically

X402ZKPaymentClient.makePrivateRequest(endpoint, options):

Calls the endpoint.
On 402, generates a proof.
POST /verify, then POST /settle.
Retries the original request with X-Payment-Proof.

sendPrivatePayment(recipientPhone, amount, memo?) sends a private payment without an API call.

​Packages

​1. Client setup

​2. Generate a private payment proof

​3. Protect an API with x402 middleware

​4. Example server

​5. Client that pays automatically

Packages

1. Client setup

2. Generate a private payment proof

3. Protect an API with x402 middleware

4. Example server

5. Client that pays automatically