x402 Hybrid Mode

1 つのミドルウェアで Coinbase Bazaar 自動掲載 + LemonCake 機能（freee 仕訳 / インボイス / JPY オフランプ）を同時に得る方法。

背景：なぜ hybrid が必要か

x402 Bazaar / AWS Bedrock AgentCore の流量を取り込むには、settle が Coinbase CDP facilitator を経由する必要がある。一方、freee / 適格請求書 / JPY オフランプといった日本ローカル機能は LemonCake 経由の metering が前提。

hybrid モードは 「CDP で settle、LemonCake にも記録」 の二段構え。1 つのミドルウェアで両方の恩恵を受けられる。

インストール

npm install @lemon-cake/x402-server

Express での使い方

import express from "express";
import { x402Middleware } from "@lemon-cake/x402-server";

const app = express();

app.use("/api/search", x402Middleware({
  serviceId:       "your-providerV2-id",   // /sellers で発行
  pricePerCallUsd: 0.001,
  facilitator:     "both",                  // ← hybrid モード
  bazaar: {
    name:        "Web Search API",
    description: "Real-time Google search",
    category:    "search",
    tags:        ["search", "web"],
  },
}));

app.get("/api/search", (req, res) => {
  res.json({ results: [/* … */] });
});

app.listen(3000);

Hono / Cloudflare Workers での使い方

import { Hono } from "hono";
import { x402Hono } from "@lemon-cake/x402-server";

const app = new Hono();

app.use("/api/search", x402Hono({
  serviceId:       "your-providerV2-id",
  pricePerCallUsd: 0.001,
  facilitator:     "both",
}));

app.get("/api/search", (c) => c.json({ results: [/* … */] }));

3 つの facilitator モード

facilitator	挙動	向き
`"lemoncake"`	全部 LemonCake 経由で verify + settle	JP-centric, freee 仕訳が主目的
`"coinbase"`	全部 CDP 経由で verify + settle	Bazaar 流量だけ欲しい場合
`"both"`	CDP で settle → LemonCake に async POST	推奨：Bazaar + freee 両取り

設定オプション

serviceId（必須）：/sellers で発行した providerV2Id
pricePerCallUsd（任意、fallback only）： v0.2.2+ では単価のシングルソースは /sellers wizard で設定した DB 値。この値は LemonCake API 到達不能時の安全弁としてのみ使う。ダッシュボードから単価変更すれば コード再デプロイ不要で 60 秒以内に反映
facilitator（任意、デフォルト "lemoncake"）：上記 3 モード
bazaar.{name, description, category, tags}：Bazaar 掲載時の表示メタ

Bazaar 自動掲載のしくみ

facilitator: "coinbase" | "both" + bazaar オプションを渡すと、402 レスポンスに extensions.discoverable: true が自動で付与される。初回の settle が CDP で完了した時点で、Coinbase 側がリソース URL を Bazaar の discovery index にカタログする。

Bazaar に掲載されると、AWS Bedrock AgentCore Payments の MCP server / 22 社 Foundation メンバーの client 経由でも検索可能になる。つまり 1 settle で global discovery。

確認方法

curl 'https://api.cdp.coinbase.com/platform/v2/x402/discovery/search?q=<yourServiceName>'

"both" モードでの metering

CDP で settle が成功した直後、ミドルウェアは POST /api/x402/record を fire-and-forget で叩く。これにより PermitCharge として記録され、月次のインボイス自動発行 / freee 仕訳の対象になる。冪等性は txHash で担保されるので、リクエストが重複しても二重記録されない。