@vanditk2/agentvault-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vandit Kunapareddi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# @vanditk2/agentvault-sdk
+
+TypeScript client for [AgentVault](https://github.com/vandit-kunapareddi/agentvault) — the open-source trust and control layer for AI-agent payments.
+
+> **Heads up:** the SDK on its own doesn't move money. It talks to an AgentVault **checkpoint** (the control plane that verifies the credential, enforces budgets, escalates anything unusual, and routes to the right payment protocol). Today AgentVault is self-host — to use this SDK in production you also need to be running your own checkpoint. See the [main repo](https://github.com/vandit-kunapareddi/agentvault) for the self-host quickstart.
+
+## Install
+
+```bash
+npm install @vanditk2/agentvault-sdk
+```
+
+Requires Node 20+.
+
+## Usage
+
+```ts
+import { AgentVault } from "@vanditk2/agentvault-sdk";
+
+const vault = new AgentVault({
+  credential: process.env.AGENT_CREDENTIAL!,   // a signed JWT issued by your AgentVault dashboard
+  checkpointUrl: "https://your-checkpoint.example.com",
+});
+
+const result = await vault.pay({
+  endpoint: "https://api.someservice.com/data",
+  maxAmount: 0.05,
+});
+
+if (result.status === "approved") {
+  // result.protocol → "x402" | "mpp" | "acp"
+  // result.receipt  → vendor, amount, settled, timestamp, receiptId
+  // result.trustTier
+}
+```
+
+`pay()` probes the endpoint to detect which agentic payment protocol it speaks (x402 / MPP / ACP), then POSTs to your checkpoint's `/checkpoint` endpoint with the credential + vendor + amount + protocol + endpoint. Your checkpoint runs the full decision pipeline and either approves, escalates (and holds while a human decides), or blocks.
+
+## What the credential carries
+
+The signed JWT encodes the spending rules the checkpoint will enforce:
+
+```json
+{
+  "agentId": "clx123abc",
+  "agentName": "Research Agent",
+  "walletAddress": "0x52ce…",
+  "authorizedBy": "dev@example.com",
+  "dailyCap": 10.0,
+  "perTxLimit": 0.5,
+  "approvedVendors": ["exa.ai", "hyperbolic.xyz"],
+  "vendorLimits": { "exa.ai": 2.0 },
+  "supportedProtocols": ["x402", "mpp", "acp"],
+  "issuedAt": 1748390400,
+  "expiresAt": 1748476800
+}
+```
+
+Generate these from the AgentVault dashboard's "Register agent" form. The checkpoint verifies the signature against the dashboard's `JWT_SECRET` — both must match.
+
+## What status values mean
+
+| `status` | Meaning |
+|---|---|
+| `approved` | The payment passed every check and was settled by the matching protocol handler. `receipt` is populated with the on-chain (or mock) settlement details. |
+| `recognized` | The protocol was identified but the handler doesn't execute the payment yet (ACP today). `settled: false`. |
+| `escalated` | The payment was held while a human reviewed it (then resolved as approved or blocked). |
+| `blocked` | A budget, trust, vendor, or settlement check failed. `reason` says which. |
+
+## Direct protocol detection
+
+If you just want to know which protocol an endpoint expects without making a payment:
+
+```ts
+import { detectProtocol } from "@vanditk2/agentvault-sdk";
+
+const protocol = await detectProtocol("https://api.someservice.com/data");
+// → "x402" | "mpp" | "acp" | "unknown"
+```
+
+## License
+
+[MIT](./LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+import type { PaymentResult, Protocol } from "./types.js";
+export type { Protocol, CheckpointStatus, PaymentReceipt, CheckpointResponse, PaymentResult, } from "./types.js";
+export interface AgentVaultConfig {
+    /** The signed JWT spending credential. Rules live inside it, not here. */
+    credential: string;
+    /** Base URL of the AgentVault checkpoint. Defaults to http://localhost:4000. */
+    checkpointUrl?: string;
+}
+export interface PayArgs {
+    /** The service endpoint the agent wants to pay. */
+    endpoint: string;
+    /** Maximum amount (USD) the agent is willing to pay for this call. */
+    maxAmount: number;
+}
+/**
+ * Detects which agentic payment protocol a service endpoint expects by
+ * probing it and reading the X-Payment-Protocol header on a 402 response.
+ */
+export declare function detectProtocol(endpoint: string): Promise<Protocol>;
+export declare class AgentVault {
+    private readonly config;
+    constructor(config: AgentVaultConfig);
+    /**
+     * Pays for a service. Detects the protocol the endpoint expects, then routes
+     * the request through the AgentVault checkpoint, which verifies trust,
+     * enforces budget rules, escalates if needed, and routes to the protocol.
+     */
+    pay(args: PayArgs): Promise<PaymentResult>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE1D,YAAY,EACV,QAAQ,EACR,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,aAAa,GACd,MAAM,YAAY,CAAC;AAIpB,MAAM,WAAW,gBAAgB;IAC/B,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,OAAO;IACtB,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAaxE;AAED,qBAAa,UAAU;IACT,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,gBAAgB;IAErD;;;;OAIG;IACG,GAAG,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC;CAuBjD"}

package/dist/index.js

@@ -0,0 +1,55 @@
+const DEFAULT_CHECKPOINT_URL = "http://localhost:4000";
+/**
+ * Detects which agentic payment protocol a service endpoint expects by
+ * probing it and reading the X-Payment-Protocol header on a 402 response.
+ */
+export async function detectProtocol(endpoint) {
+    try {
+        const res = await fetch(endpoint, { method: "GET" });
+        if (res.status === 402) {
+            const header = res.headers.get("x-payment-protocol");
+            if (header === "x402" || header === "mpp" || header === "acp") {
+                return header;
+            }
+        }
+        return "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+export class AgentVault {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Pays for a service. Detects the protocol the endpoint expects, then routes
+     * the request through the AgentVault checkpoint, which verifies trust,
+     * enforces budget rules, escalates if needed, and routes to the protocol.
+     */
+    async pay(args) {
+        const protocol = await detectProtocol(args.endpoint);
+        let vendor;
+        try {
+            vendor = new URL(args.endpoint).hostname;
+        }
+        catch {
+            vendor = args.endpoint;
+        }
+        const baseUrl = this.config.checkpointUrl ?? DEFAULT_CHECKPOINT_URL;
+        const res = await fetch(`${baseUrl}/checkpoint`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                credential: this.config.credential,
+                vendor,
+                amount: args.maxAmount,
+                protocol,
+                endpoint: args.endpoint,
+            }),
+        });
+        return (await res.json());
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAUA,MAAM,sBAAsB,GAAG,uBAAuB,CAAC;AAgBvD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,QAAgB;IACnD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;QACrD,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YACvB,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;YACrD,IAAI,MAAM,KAAK,MAAM,IAAI,MAAM,KAAK,KAAK,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;gBAC9D,OAAO,MAAM,CAAC;YAChB,CAAC;QACH,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,MAAM,OAAO,UAAU;IACQ;IAA7B,YAA6B,MAAwB;QAAxB,WAAM,GAAN,MAAM,CAAkB;IAAG,CAAC;IAEzD;;;;OAIG;IACH,KAAK,CAAC,GAAG,CAAC,IAAa;QACrB,MAAM,QAAQ,GAAG,MAAM,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACrD,IAAI,MAAc,CAAC;QACnB,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,QAAQ,CAAC;QAC3C,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC;QACzB,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,aAAa,IAAI,sBAAsB,CAAC;QACpE,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,OAAO,aAAa,EAAE;YAC/C,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;gBACnB,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,UAAU;gBAClC,MAAM;gBACN,MAAM,EAAE,IAAI,CAAC,SAAS;gBACtB,QAAQ;gBACR,QAAQ,EAAE,IAAI,CAAC,QAAQ;aACxB,CAAC;SACH,CAAC,CAAC;QACH,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAkB,CAAC;IAC7C,CAAC;CACF"}

package/dist/types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Public types for the AgentVault SDK. These mirror the shapes used inside
+ * the checkpoint and are inlined here so the published SDK has no internal
+ * workspace dependencies.
+ */
+export type Protocol = "x402" | "mpp" | "acp" | "unknown";
+export type CheckpointStatus = "approved" | "blocked" | "escalated" | "recognized";
+export interface PaymentReceipt {
+    protocol: Protocol;
+    receiptId: string;
+    vendor: string;
+    amount: number;
+    currency: "USDC";
+    settled: boolean;
+    timestamp: string;
+}
+export interface CheckpointResponse {
+    status: CheckpointStatus;
+    reason?: string;
+    protocol?: Protocol;
+    trustTier?: string;
+    receipt?: PaymentReceipt;
+}
+export type PaymentResult = CheckpointResponse;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,SAAS,CAAC;AAE1D,MAAM,MAAM,gBAAgB,GACxB,UAAU,GACV,SAAS,GACT,WAAW,GACX,YAAY,CAAC;AAEjB,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,QAAQ,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,gBAAgB,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B;AAED,MAAM,MAAM,aAAa,GAAG,kBAAkB,CAAC"}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Public types for the AgentVault SDK. These mirror the shapes used inside
+ * the checkpoint and are inlined here so the published SDK has no internal
+ * workspace dependencies.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@vanditk2/agentvault-sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for AgentVault — the open-source trust and control layer for AI-agent payments.",
+  "keywords": [
+    "agentvault",
+    "agentic-payments",
+    "ai-agents",
+    "x402",
+    "mpp",
+    "acp",
+    "sdk",
+    "payments"
+  ],
+  "license": "MIT",
+  "author": "Vandit Kunapareddi",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vandit-kunapareddi/agentvault.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://github.com/vandit-kunapareddi/agentvault#readme",
+  "bugs": {
+    "url": "https://github.com/vandit-kunapareddi/agentvault/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  }
+}