discover → 402 → pay → retry → result

import { createInvokePort } from "invokeport-server-sdk";

const gate = createInvokePort({
  appId: process.env.INVOKEPORT_APP_ID!,
  projectSecret: process.env.INVOKEPORT_PROJECT_SECRET!,
  controlPlaneUrl: process.env.INVOKEPORT_ORIGIN!,
});

export const POST = gate.protect({
  key: "summarize",
  name: "Summarize text",
  path: "/api/summarize",
  method: "POST",
  priceAtomic: "20000", // 0.02 USDC
  payoutAddress: "0x…your verified 90/10 PullSplit contract…",
  inputSchema: { type: "object", properties: { text: { type: "string" } } },
}, async (request) => {
  const { text } = await request.json();
  return Response.json({ summary: await summarize(text) });
});

// Run during deploy/startup. The signed definition becomes a marketplace capability.
await gate.sync();

GET /api/catalog?q=status&kind=HTTP&tag=monitoring&page=1&limit=12

{
  "schemaVersion": 2,
  "mode": "real-payments",
  "filters": { "q": "status", "kind": "HTTP", "tag": "monitoring", "sort": "name" },
  "pagination": { "page": 1, "limit": 12, "total": 1, "totalPages": 1,
    "hasPrevious": false, "hasNext": false },
  "services": [],
  "capabilities": [{
    "kind": "HTTP",
    "serviceRoutingKey": "example",
    "routingKey": "status",
    "resourceUri": "https://your-domain.example/api/gateway/example/status",
    "tags": ["monitoring"],
    "invocation": { "kind": "HTTP", "mode": "passthrough", "method": "GET" },
    "hasInputSchema": false,
    "hasOutputSchema": true,
    "hasDemoInput": false,
    "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "assetDecimals": 6,
    "network": "eip155:8453"
  }]
}

GET /api/catalog/example/status
// One selected capability, now including inputSchema, outputSchema and demoInput.

Abridged. Search is literal text matching over bounded public metadata; no embeddings or universal task-understanding claim is involved.

HTTP/1.1 402 Payment Required
content-type: application/json; charset=utf-8
PAYMENT-REQUIRED: <base64 of the full payment-required document>
invokeport-request-id: 0f5c…

{
  "error": "payment_required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "11112",
      "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "payTo": "0x…verified immutable split contract…",
      "maxTimeoutSeconds": 120
    }
  ]
}

import { createWalletClient, http } from "viem";
import { randomBytes } from "node:crypto";
import { privateKeyToAccount } from "viem/accounts";
import { base } from "viem/chains";

const GATEWAY = process.env.INVOKEPORT_ORIGIN ?? "http://localhost:3000";
const MAX_PRICE_ATOMIC = 20_000n; // budget policy, atomic USDC

// 1. DISCOVER — pick a service from the machine-readable catalog, never a hardcoded URL.
const catalog = await (await fetch(`${GATEWAY}/api/catalog`)).json();
const service = catalog.capabilities
  .filter((s) => s.kind === "HTTP" && s.invocation.method === "GET" && s.network === "eip155:8453")
  .find((s) => BigInt(s.priceAtomic) <= MAX_PRICE_ATOMIC);
if (!service) throw new Error("no service within budget");

// 2. UNPAID CALL — expect a real 402, not an error to retry blindly.
const unpaid = await fetch(service.resourceUri, { method: "GET" });
if (unpaid.status !== 402) throw new Error(`expected 402, got ${unpaid.status}`);

// 3. PARSE THE REQUIREMENT — price, asset, network and payTo all come from the response.
const { accepts } = await unpaid.json();
const requirement = accepts[0];
if (BigInt(requirement.amount) > MAX_PRICE_ATOMIC) {
  console.log("over budget, refusing"); process.exit(0);
}
if (requirement.network !== "eip155:8453" || requirement.asset.toLowerCase() !== "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913" || requirement.amount !== service.priceAtomic || requirement.payTo.toLowerCase() !== service.payoutAddress.toLowerCase()) throw new Error("quote mismatch");

// 4. PAY — sign an EIP-3009 transfer authorization with the agent's own key.
const account = privateKeyToAccount(process.env.AGENT_PRIVATE_KEY as `0x${string}`);
const wallet = createWalletClient({ account, chain: base, transport: http() });
const now = Math.floor(Date.now() / 1000);
const authorization = {
  from: account.address.toLowerCase(),
  to: requirement.payTo.toLowerCase(),
  value: requirement.amount,
  validAfter: String(now - 60),
  validBefore: String(now + 120),
  nonce: `0x${randomBytes(32).toString("hex")}`,
};
const signature = await wallet.signTypedData({
  domain: { name: "USDC", version: "2", chainId: 8453, verifyingContract: requirement.asset },
  types: { TransferWithAuthorization: [
    { name: "from", type: "address" }, { name: "to", type: "address" },
    { name: "value", type: "uint256" }, { name: "validAfter", type: "uint256" },
    { name: "validBefore", type: "uint256" }, { name: "nonce", type: "bytes32" },
  ] },
  primaryType: "TransferWithAuthorization",
  message: {
    from: account.address, to: requirement.payTo, value: BigInt(authorization.value),
    validAfter: BigInt(authorization.validAfter), validBefore: BigInt(authorization.validBefore),
    nonce: authorization.nonce,
  },
});

// 5. RETRY — the identical request, now carrying the payment.
const header = Buffer.from(JSON.stringify({
  x402Version: 2,
  resource: { url: service.resourceUri },
  accepted: requirement,
  payload: { signature, authorization },
})).toString("base64");

const paid = await fetch(service.resourceUri, {
  method: "GET",
  headers: { "PAYMENT-SIGNATURE": header },
});

// 6. RESULT — upstream body, plus a settlement reference in PAYMENT-RESPONSE.
console.log(paid.status, await paid.text());
console.log("settlement:", paid.headers.get("PAYMENT-RESPONSE"));

git clone <this repo> && cd examples/agent-client
cp .env.example .env         # AGENT_PRIVATE_KEY, INVOKEPORT_ORIGIN
npm install && npm start

# discovered   market-data/spot-price  0.011112 USDC
# 402          amount=… asset=0x833589fcd6edb6e08f4c7c32d4f71b54bda02913 payTo=0x… network=eip155:8453
# policy       price <= configured budget -> proceed
# payment      nonce=0x…  signature=0x…
# retry        HTTP 200  settlement=0x…
# result       {"pair":"ETH-USD","price":"…"}