SDK Reference

Complete API reference for the marc-protocol-sdk package.

Installation

npm install marc-protocol-sdk

The SDK ships as ESM and CJS. Built with tsup and includes TypeScript declarations.

fheFetch

Auto-handle HTTP 402 responses with encrypted payments. Sends the request, and if a 402 is returned, automatically encrypts and sends the payment, then retries.

fheFetchtypescript

import { fheFetch, createFheFetch } from "marc-protocol-sdk";

// One-shot usage
const response = await fheFetch("https://api.example.com/data", {
  tokenAddress: "0xE944754aa70d4924dc5d8E57774CDf21Df5e592D",
  verifierAddress: "0x4503A7aee235aBD10e6064BBa8E14235fdF041f4",
  rpcUrl: "https://sepolia.infura.io/v3/YOUR_KEY",
  signer: wallet,
  fhevmInstance: fhevm,
});

// Reusable fetch with pre-configured credentials
const secureFetch = createFheFetch({
  tokenAddress: "0xE944754aa70d4924dc5d8E57774CDf21Df5e592D",
  verifierAddress: "0x4503A7aee235aBD10e6064BBa8E14235fdF041f4",
  rpcUrl: "https://sepolia.infura.io/v3/YOUR_KEY",
  signer: wallet,
  fhevmInstance: fhevm,
});

const res = await secureFetch("https://api.example.com/data");

fhePaywall

Express middleware that gates routes behind encrypted x402 payments.

fhePaywalltypescript

import { fhePaywall } from "marc-protocol-sdk";
import express from "express";

const app = express();

app.get("/api/premium",
  fhePaywall({
    price: "1000000",           // 1 USDC (6 decimals)
    asset: "USDC",
    tokenAddress: "0xE944754aa70d4924dc5d8E57774CDf21Df5e592D",
    verifierAddress: "0x4503A7aee235aBD10e6064BBa8E14235fdF041f4",
    recipientAddress: "0xYOUR_WALLET",
    rpcUrl: "https://sepolia.infura.io/v3/YOUR_KEY",
    chainId: 11155111,
    minConfirmations: 1,
  }),
  (req, res) => {
    res.json({ data: "premium", paidBy: req.paymentInfo?.from });
  }
);

FhePaywallConfig

Field	Type	Default	Description
`price`	string \| number	required	USDC in 6-decimal units
`asset`	string	required	Token symbol ("USDC")
`tokenAddress`	string	required	ConfidentialUSDC address
`verifierAddress`	string	required	X402PaymentVerifier address
`recipientAddress`	string	required	Your server wallet
`rpcUrl`	string	required	Ethereum RPC endpoint
`chainId`	number	11155111	Chain ID
`maxTimeoutSeconds`	number	300	Payment timeout
`minConfirmations`	number	1	Required block confirmations
`nonceStore`	NonceStore	InMemory	External nonce persistence
`onPaymentVerified`	function	-	Success callback
`onPaymentFailed`	function	-	Failure callback
`webhookUrl`	string	-	Webhook URL for events
`webhookSecret`	string	-	HMAC-SHA256 secret

fheBatchPaywall

Same as fhePaywall but supports batch prepayment credits:

batchtypescript

import { fheBatchPaywall } from "marc-protocol-sdk";

app.get("/api/data",
  fheBatchPaywall({
    price: "50000",  // 0.05 USDC per request
    asset: "USDC",
    ...config,
  }),
  handler
);

// Batch flow:
// 1. First request: agent sends batch header (requestCount + pricePerRequest)
// 2. Middleware verifies on-chain, grants credits
// 3. Subsequent requests: deduct credit locally (no on-chain check)
// 4. Credits exhausted: 402 again
//
// Response headers:
// X-Batch-Credits-Remaining: 99
// X-Batch-Credits-Expiry-Warning: (when < 1 hour left)

FhePaymentHandler

Client-side handler for manual x402 payment flows:

handlertypescript

import { FhePaymentHandler } from "marc-protocol-sdk";

const handler = new FhePaymentHandler(signer, fhevmInstance, {
  maxPayment: 10_000_000n,             // 10 USDC safety limit
  allowedNetworks: ["eip155:11155111"],
});

// Make payment
const { txHash, verifierTxHash, nonce } = await handler.pay(
  recipientAddress,
  1_000_000n   // 1 USDC
);

NonceStore Interface

For production, implement external nonce persistence (the default in-memory store does not survive restarts):

redis-nonce-store.tstypescript

import type { NonceStore } from "marc-protocol-sdk";

const redisStore: NonceStore = {
  async check(nonce: string): Promise<boolean> {
    return !(await redis.exists(`nonce:${nonce}`));
  },
  async add(nonce: string): Promise<void> {
    await redis.set(`nonce:${nonce}`, "1", "EX", 86400);
  },
};

// Use with paywall
fhePaywall({ ...config, nonceStore: redisStore })

ERC-8004 / ERC-8183 Helpers

// ERC-8004: Agent registration helpers
import { fhePaymentMethod, fhePaymentProof } from "marc-protocol-sdk";

const method = fhePaymentMethod({ tokenAddress, verifierAddress });
const proof = fhePaymentProof(nonce, verifierAddress);

// ERC-8183: Job escrow helpers
import { createJob, fundJob, submitJob } from "marc-protocol-sdk";

Error Classes

Error	When
`PaymentRequiredError`	Server returned 402
`PaymentVerificationError`	On-chain verification failed
`NonceReplayError`	Nonce already used
`InsufficientBalanceError`	Not enough cUSDC
`ChainMismatchError`	Chain ID does not match
`FheInitError`	FHE instance failed to initialize

Previous← AgentKit Plugin NextContract Addresses→