@provenant/sdk

x402 payment middleware for AI agents. Drop-in fetch replacement that auto-pays APIs on HTTP 402.

Install

npm install @provenant/sdk

Quick Start

import { fundedFetch } from "@provenant/sdk";

const res = await fundedFetch("https://api.example.com/data", {
  provenant: {
    apiKey: "prv_...",
    agentId: "agent_...",
  },
});

When the server responds 402 Payment Required, the SDK:

1. Parses the cost from the WWW-Authenticate header (amount=<microUSDC>)
2. Evaluates the payment against the agent's leash and wallet via the Provenant API
3. If ALLOW — retries with an x402-payment receipt header
4. If DENY or REQUIRES_APPROVAL — throws a typed error

API

fundedFetch(url, options?)

Like fetch, but handles 402 automatically.

const res = await fundedFetch("https://api.example.com/compute", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ prompt: "hello" }),
  provenant: { apiKey: "prv_...", agentId: "agent_..." },
});

createProvenantClient(config)

Factory that returns a pre-configured fetch:

import { createProvenantClient } from "@provenant/sdk";

const client = createProvenantClient({
  apiKey: "prv_...",
  agentId: "agent_...",
});

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

Environment Variables

If provenant is not passed in options, the SDK reads from:

• PROVENANT_API_KEY
• PROVENANT_AGENT_ID

export PROVENANT_API_KEY=prv_...
export PROVENANT_AGENT_ID=agent_...

Errors

| Error | Meaning | |-------|---------| | ProvenantPaymentError | Payment was denied or header was malformed | | ProvenantApprovalError | Payment requires human approval |

import { fundedFetch, ProvenantPaymentError } from "@provenant/sdk";

try {
  const res = await fundedFetch("https://api.example.com/data");
} catch (err) {
  if (err instanceof ProvenantPaymentError) {
    console.error("Payment failed:", err.message);
    console.error("Original response:", err.response.status);
  }
}

License

MIT