Provider Middleware

The quality gate needs to see the response body. Without it, KODA settles payments but can't validate data quality. The middleware captures response bodies automatically and sends them to KODA at settle-time.

Two integration levels

URL only — Point your facilitator URL to KODA. Payments settle through KODA, trust scores build from settlement history. No quality gate.
URL + middleware — Add the middleware below. KODA sees response bodies and runs the quality gate before settling. Bad data gets rejected.

Hono Middleware

For Hono-based servers. The middleware runs after your route handler, captures the response body, and posts it to KODA's /facilitator/settle endpoint.

server.tstypescript

import { Hono } from "hono";
import { kodaMiddleware } from "./koda-middleware";
import { paymentMiddleware } from "x402-hono";

const app = new Hono();

// KODA middleware — runs AFTER route handler to capture response body
app.use("/api/*", kodaMiddleware({
  kodaUrl: "https://x402.kodaoracle.com",
}));

// Standard x402 payment middleware
app.use("/api/*", paymentMiddleware({
  facilitatorUrl: "https://x402.kodaoracle.com",
  payTo: "0xYourWalletAddress",
}));

// Your routes
app.get("/api/v1/data", (c) => {
  return c.json({
    data: {
      price: 0.0142,
      symbol: "KODA",
      volume24h: 125000,
    },
  });
});

export default app;

Express Middleware

For Express-based servers. Patches res.json() to capture the response body. Fire-and-forget — does not block the response.

server.tstypescript

import express from "express";
import { kodaExpressMiddleware } from "./koda-middleware";
import { paymentMiddleware } from "@x402/express";

const app = express();

// KODA middleware — patches res.json to capture response body
app.use("/api", kodaExpressMiddleware({
  kodaUrl: "https://x402.kodaoracle.com",
}));

// Standard x402 payment middleware
app.use("/api", paymentMiddleware({
  facilitatorUrl: "https://x402.kodaoracle.com",
  payTo: "0xYourWalletAddress",
}));

// Your routes
app.get("/api/v1/data", (req, res) => {
  res.json({
    data: {
      price: 0.0142,
      symbol: "KODA",
      volume24h: 125000,
    },
  });
});

app.listen(3000);

Configuration

Option	Type	Default	Description
kodaUrl	string	—	KODA facilitator URL (required)
blockOnFailure	boolean	false	If true, logs a warning when KODA rejects the settlement. Default is log-only (non-blocking).
timeoutMs	number	5000	Request timeout for the settle call to KODA

Manual Integration

If you prefer not to use the middleware, include responseBody in your settle request directly. Same result, no middleware dependency.

Manual settle with quality gatetypescript

// After generating the response, include it in the settle call
const settleResponse = await fetch(
  "https://x402.kodaoracle.com/facilitator/settle",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      paymentPayload,
      paymentRequirements,
      responseBody: JSON.stringify(yourApiResponse),
    }),
  }
);

const result = await settleResponse.json();
if (!result.success) {
  // Quality gate rejected — response failed validation
  // Payment was NOT settled, buyer keeps funds
  console.log("Rejected:", result.qualityGate);
}

The middleware source is a single file — sdk/koda-middleware.ts in the KODA repo. Copy it into your project or import directly. No npm package required.