# npm
npm install @novault/sdk

# pnpm
pnpm add @novault/sdk

# yarn
yarn add @novault/sdk

import { NoVault } from "@novault/sdk";

export const nv = new NoVault({
  apiKey: process.env.NOVAULT_API_KEY!,
  // Optional: pin to testnet during development
  environment: "sandbox",
});

import { nv } from "./novault";

const result = await nv.intent.execute({
  capability: "image/upscale",
  input: {
    url: "https://example.com/photo.png",
    scale: 4,
  },
  budget: {
    maxUsd: "0.05",
  },
});

console.log(result.output.url);     // → upscaled image URL
console.log(result.receipt.hash);   // → cryptographic execution receipt

import { verifyReceipt } from "@novault/sdk";

const isValid = await verifyReceipt(result.receipt);
// → true

curl https://api.novault.xyz/v1/intents \
  -H "Authorization: Bearer nv_live_sk_…" \
  -H "Content-Type: application/json"

import { generateAgentIdentity } from "@novault/sdk";

// Run once; persist the identity securely
const identity = await generateAgentIdentity();
// { did: "did:novault:0x…", privateKey: "…", publicKey: "…" }

const nv = new NoVault({
  apiKey: process.env.NOVAULT_API_KEY!,
  agentIdentity: identity,
});

{
  "capability": "image/upscale",          // namespaced capability identifier
  "version": "^1.0",                      // semver range accepted
  "input": {                              // capability-specific input
    "url": "https://…/photo.png",
    "scale": 4
  },
  "budget": {
    "maxUsd": "0.10",                     // hard maximum for this request
    "preferLowestPrice": true             // resolution hint
  },
  "policy": {
    "ttlMs": 8000,                        // abort if not settled within 8 s
    "retries": 2,                         // retry on provider failure
    "requireVerification": true           // reject unverified receipts
  },
  "agentDid": "did:novault:0xabc…",      // agent's public identity
  "nonce": "f3c9…",                       // prevents replay
  "signature": "ed25519:0x7e3f…"         // agent co-signature over intent hash
}

budget: {
  maxUsd: "0.10",
  preferLowestPrice: true,       // weight price 80%
  requireSlaCompliant: true,     // exclude any provider with SLA miss in last 7 days
  pinProvider: "did:novault:0x…" // bypass resolution, pin to specific provider
}

X-Payment: {
  "version": "1",
  "scheme": "exact",
  "network": "base-mainnet",
  "maxAmountRequired": "40000",   // in USDC microunits (6 decimals)
  "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "payTo": "0xEscrowContract…",
  "extra": {
    "intentHash": "sha256:3f4a…",
    "agentSignature": "ed25519:0x…"
  }
}

{
  "receiptVersion": "1",
  "intentHash": "sha256:3f4a…",
  "outputHash": "sha256:9c1b…",
  "provider": "did:novault:0xabcd…",
  "capabilityId": "image/upscale",
  "executedAt": 1753996800,
  "settledAt": 1753996802,
  "latencyMs": 1240,
  "amountPaidUsd": "0.0040",
  "verificationMethod": "deterministic-reexecution",
  "verifierNode": "did:novault:0xverif…",
  "signature": "ed25519:0x7e3f…"
}

const result = await nv.intent.execute({ … });

// Receipt is always present on success
const { receipt } = result;

console.log(receipt.hash);            // content-addressed receipt ID
console.log(receipt.amountPaidUsd);   // exact amount settled
console.log(receipt.latencyMs);       // provider execution latency
console.log(receipt.verifierNode);    // DID of verifier that checked the output

// Independently verify the receipt at any time
const valid = await nv.receipts.verify(receipt.hash);

// List receipts for an agent
const receipts = await nv.receipts.list({
  agentDid: "did:novault:0xabc…",
  capability: "image/upscale",
  from: "2026-01-01",
  to: "2026-08-01",
  limit: 50,
});

// Fetch a single receipt
const receipt = await nv.receipts.get("sha256:9c1b…");

import { NoVault, generateAgentIdentity, verifyReceipt } from "@novault/sdk";

// 1. Generate a persistent agent identity (do this once, store it securely)
const identity = await generateAgentIdentity();

// 2. Initialise the client
const nv = new NoVault({
  apiKey: process.env.NOVAULT_API_KEY!,
  agentIdentity: identity,
  environment: "sandbox", // switch to "production" when ready
});

// 3. Execute an intent
const result = await nv.intent.execute({
  capability: "data/price",
  input: {
    asset: "ETH",
    currency: "USD",
    sources: ["chainlink", "pyth"],
    aggregation: "median",
  },
  budget: {
    maxUsd: "0.002",
  },
  policy: {
    ttlMs: 5000,
    requireVerification: true,
  },
});

// 4. Use the output
console.log("ETH price:", result.output.price, result.output.currency);

// 5. Verify the receipt
const isValid = await verifyReceipt(result.receipt);
console.log("Receipt valid:", isValid);
console.log("Paid:", result.receipt.amountPaidUsd, "USD");

budget: {
  maxUsd: "0.10",                // hard cap — request rejected if all providers cost more
  preferLowestPrice: true,       // resolution hint: weight price heavily
}

const session = await nv.sessions.create({
  budget: {
    totalMaxUsd: "5.00",           // session hard cap
    capabilityLimits: {
      "image/*": "2.00",           // wildcard cap for all image capabilities
      "llm/complete": "1.50",
    },
  },
  ttlSeconds: 3600,               // session expires after 1 hour
});

// All intents executed within this session share the budget pool
const result = await nv.intent.execute(
  { capability: "image/upscale", … },
  { sessionId: session.id }
);

import { createProviderIdentity } from "@novault/sdk/provider";

const provider = await createProviderIdentity({
  name: "Acme Upscaling Inc.",
  contact: "ops@acme.example",
  website: "https://acme.example",
});
// → { did: "did:novault:0x…", privateKey: "…", publicKey: "…" }

await nv.provider.bondCollateral({
  providerDid: provider.did,
  amountUsd: "500.00",  // minimum: $100 for <100 req/min; $1 000 for <1 000 req/min
});

{
  "capability": "image/upscale",
  "version": "1.3.0",
  "provider": "did:novault:0xabcd…",
  "input": {
    "type": "object",
    "properties": {
      "url":   { "type": "string", "format": "uri" },
      "scale": { "type": "integer", "enum": [2, 4, 8] }
    },
    "required": ["url", "scale"]
  },
  "output": {
    "type": "object",
    "properties": {
      "url":    { "type": "string", "format": "uri" },
      "width":  { "type": "integer" },
      "height": { "type": "integer" }
    }
  },
  "pricing": {
    "model": "per-request",
    "unit": "megapixel",
    "rate": "0.0004",
    "currency": "USDC"
  },
  "sla": {
    "p99LatencyMs": 3000,
    "uptimePct": 99.5,
    "maxConcurrentRequests": 200
  },
  "settlement": {
    "method": "x402",
    "payTo": "0xYourWalletAddress…",
    "network": "base-mainnet"
  }
}

import schema from "./capability-schema.json";

await nv.provider.publishSchema({
  providerDid: provider.did,
  schema,
  // SDK validates the schema locally before submitting
});
// → { schemaId: "sha256:…", status: "pending_review" }
// Schemas enter the registry after a 1-hour automated validation pass.

const result = await nv.intent.execute({
  capability: "llm/complete",
  input: { prompt: "Summarise this contract: …", maxTokens: 512 },
  budget: { maxUsd: "0.05" },
  policy: {
    ttlMs: 12000,
    retries: 3,           // try up to 3 additional providers on failure
    retryOnCodes: [       // only retry on these provider error codes
      "PROVIDER_TIMEOUT",
      "PROVIDER_RATE_LIMITED",
      "PROVIDER_UNAVAILABLE",
    ],
  },
});

// The receipt tells you which provider ultimately settled the request
console.log(result.receipt.provider);
console.log(result.metadata.providerAttempts); // → 2 (if first failed)

await nv.webhooks.create({
  url: "https://your-server.example/novault/events",
  events: [
    "intent.settled",
    "intent.failed",
    "receipt.verified",
    "receipt.disputed",
    "provider.slashed",
  ],
  secret: process.env.WEBHOOK_SECRET!,
});

import { verifyWebhookSignature } from "@novault/sdk";

// In your express handler (or equivalent):
app.post("/novault/events", (req, res) => {
  const isValid = verifyWebhookSignature({
    payload: req.rawBody,          // must be the raw buffer, not parsed JSON
    signature: req.headers["x-novault-signature"] as string,
    secret: process.env.WEBHOOK_SECRET!,
  });

  if (!isValid) return res.status(401).send("Invalid signature");

  const event = req.body;
  if (event.type === "intent.settled") {
    console.log("Settled:", event.data.intentHash, event.data.amountPaidUsd);
  }

  res.status(200).send("ok");
});

curl "https://api.novault.xyz/v1/registry/capabilities?category=image" \
  -H "Authorization: Bearer nv_live_…"

{
  "intentHash": "sha256:3f4a…",
  "state": "released",              // pending | open | released | refunded | slashed
  "amount": "40000",                // USDC microunits
  "openedAt": 1753996798,
  "settledAt": 1753996802,
  "provider": "did:novault:0xabcd…",
  "txHash": "0xchain…"
}

{
  "error": {
    "code": "INTENT_BUDGET_EXCEEDED",
    "message": "No eligible provider found within the declared maxUsd budget of $0.01.",
    "intentHash": "sha256:3f4a…",
    "docs": "https://docs.novault.xyz/errors/INTENT_BUDGET_EXCEEDED"
  }
}

npm install @novault/sdk
# peer dep for streaming intents (optional)
npm install eventsource

const stream = await nv.intent.stream({
  capability: "llm/complete",
  input: { prompt: "Explain non-custodial settlement in one paragraph.", maxTokens: 200 },
  budget: { maxUsd: "0.02" },
});

for await (const chunk of stream) {
  process.stdout.write(chunk.delta);
}

const receipt = await stream.receipt();  // available after stream ends
console.log("Paid:", receipt.amountPaidUsd);

pip install novault

import asyncio
from novault import NoVault, generate_agent_identity

async def main():
    identity = await generate_agent_identity()

    nv = NoVault(
        api_key="nv_live_sk_…",
        agent_identity=identity,
        environment="sandbox",
    )

    result = await nv.intent.execute(
        capability="data/price",
        input={"asset": "BTC", "currency": "USD", "aggregation": "median"},
        budget={"max_usd": "0.001"},
    )

    print(f"BTC price: {result.output['price']} {result.output['currency']}")
    print(f"Receipt:   {result.receipt.hash}")
    print(f"Paid:      {result.receipt.amount_paid_usd} USD")

asyncio.run(main())

from novault.sync import NoVaultSync

nv = NoVaultSync(api_key="nv_live_sk_…")
result = nv.intent.execute(capability="data/price", input={…}, budget={…})

curl -X POST https://api.novault.xyz/v1/intents \
  -H "Authorization: Bearer nv_live_sk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "capability": "data/price",
    "input": { "asset": "ETH", "currency": "USD", "aggregation": "median" },
    "budget": { "maxUsd": "0.001" },
    "policy": { "ttlMs": 5000, "requireVerification": true }
  }'

{
  "intentHash": "sha256:3f4a…",
  "status": "settled",
  "output": {
    "price": "3421.87",
    "currency": "USD",
    "timestamp": 1753996800
  },
  "receipt": {
    "hash": "sha256:9c1b…",
    "provider": "did:novault:0xabcd…",
    "amountPaidUsd": "0.0004",
    "latencyMs": 312,
    "verificationMethod": "deterministic-reexecution",
    "signature": "ed25519:0x7e3f…"
  }
}

HTTP/1.1 402 Payment Required
X-Payment-Required: {
  "version": "1",
  "scheme": "exact",
  "network": "base-mainnet",
  "maxAmountRequired": "40000",
  "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "payTo": "0xEscrowContract…",
  "extra": { "capability": "image/upscale" }
}

POST /execute HTTP/1.1
X-Payment: {
  "version": "1",
  "scheme": "exact",
  "network": "base-mainnet",
  "payload": "0x…",       // signed EIP-712 authorization
  "extra": {
    "intentHash": "sha256:3f4a…",
    "agentSignature": "ed25519:0x…"
  }
}

HTTP/1.1 200 OK
X-Payment-Response: {
  "success": true,
  "txHash": "0xchain…",
  "receipt": { … }
}

import { NoVault, generateAgentIdentity } from "@novault/sdk";

const identity = await generateAgentIdentity();
const nv = new NoVault({ apiKey: process.env.NOVAULT_API_KEY!, agentIdentity: identity });

// ── Step 1: fetch ETH price ────────────────────────────────────────────────
const priceResult = await nv.intent.execute({
  capability: "data/price",
  input: { asset: "ETH", currency: "USD", aggregation: "median" },
  budget: { maxUsd: "0.001" },
});
const ethPrice = priceResult.output.price;
console.log("ETH/USD:", ethPrice);

// ── Step 2: upscale a chart image ─────────────────────────────────────────
const imageResult = await nv.intent.execute({
  capability: "image/upscale",
  input: { url: `https://charts.example.com/eth?price=${ethPrice}`, scale: 4 },
  budget: { maxUsd: "0.01" },
});
console.log("Upscaled chart:", imageResult.output.url);

// ── Step 3: log receipts ──────────────────────────────────────────────────
for (const result of [priceResult, imageResult]) {
  console.log({
    capability: result.receipt.capabilityId,
    provider:   result.receipt.provider,
    paid:       result.receipt.amountPaidUsd,
    latency:    result.receipt.latencyMs + "ms",
  });
}

import { NoVault, generateAgentIdentity } from "@novault/sdk";

const nv = new NoVault({ apiKey: process.env.NOVAULT_API_KEY!, agentIdentity: await generateAgentIdentity() });

// Create a session with a $1 total budget
const session = await nv.sessions.create({
  budget: { totalMaxUsd: "1.00" },
  ttlSeconds: 300,
});

const opts = { sessionId: session.id, policy: { retries: 2, ttlMs: 10_000 } };

// ── Concurrent data fetch ─────────────────────────────────────────────────
const [eth, btc, sol] = await Promise.all([
  nv.intent.execute({ capability: "data/price", input: { asset: "ETH", currency: "USD", aggregation: "median" }, budget: { maxUsd: "0.001" }, ...opts }),
  nv.intent.execute({ capability: "data/price", input: { asset: "BTC", currency: "USD", aggregation: "median" }, budget: { maxUsd: "0.001" }, ...opts }),
  nv.intent.execute({ capability: "data/price", input: { asset: "SOL", currency: "USD", aggregation: "median" }, budget: { maxUsd: "0.001" }, ...opts }),
]);

console.log("Prices:", eth.output.price, btc.output.price, sol.output.price);

// ── Sequential analysis (depends on prices) ───────────────────────────────
const risk = await nv.intent.execute({
  capability: "data/risk-score",
  input: { portfolio: { ETH: 0.6, BTC: 0.3, SOL: 0.1 }, prices: { ETH: eth.output.price, BTC: btc.output.price, SOL: sol.output.price } },
  budget: { maxUsd: "0.02" },
  ...opts,
});

console.log("Portfolio risk score:", risk.output.score, "/100");
console.log("Session total spent:", (await nv.sessions.get(session.id)).totalSpentUsd);

import { createProviderIdentity, NoVault } from "@novault/sdk/provider";
import { serve } from "@hono/node-server";
import { Hono } from "hono";

// 1. Create provider identity (run once, store securely)
const identity = await createProviderIdentity({ name: "My Upscale Service" });
console.log("Provider DID:", identity.did);

// 2. Bond collateral ($200 covers up to 200 req/min throughput)
const nv = new NoVault({ apiKey: process.env.NOVAULT_PROVIDER_KEY!, providerIdentity: identity });
await nv.provider.bondCollateral({ amountUsd: "200.00" });

// 3. Publish schema
await nv.provider.publishSchema({
  providerDid: identity.did,
  schema: {
    capability: "image/upscale",
    version: "1.0.0",
    input: { type: "object", properties: { url: { type: "string" }, scale: { type: "integer", enum: [2, 4] } }, required: ["url", "scale"] },
    output: { type: "object", properties: { url: { type: "string" } } },
    pricing: { model: "per-request", unit: "request", rate: "0.005", currency: "USDC" },
    sla: { p99LatencyMs: 5000, uptimePct: 99.0 },
    settlement: { method: "x402", payTo: "0xYourWallet…", network: "base-mainnet" },
  },
});

// 4. Execution server (receives requests from NoVault after escrow opens)
const app = new Hono();
app.post("/execute", async (c) => {
  const { input, intentHash } = await c.req.json();

  // Verify the x402 payment header before doing any work
  const isAuthorized = await nv.provider.verifyPaymentHeader(c.req.header("X-Payment")!, { intentHash });
  if (!isAuthorized) return c.json({ error: "Unauthorized" }, 401);

  // Do the actual work
  const upscaled = await upscaleImage(input.url, input.scale);

  // Return output + issue a signed receipt
  const receipt = await nv.provider.issueReceipt({ intentHash, outputHash: await sha256(upscaled.url) });
  return c.json({ output: upscaled, receipt }, 200, { "X-Payment-Response": JSON.stringify(receipt) });
});

serve({ fetch: app.fetch, port: 3000 });
console.log("Provider server running on :3000");