express-vybe-402

Express middleware that gates routes behind Vybe Collect payment intents.

Unpaid requests receive HTTP 402 with Collect / x402 payment details. After the client settles (x402 PAYMENT-SIGNATURE on the Collect offering URL, or a verified Base USDC txHash), retry with X-Vybe-Public-Id to pass the gate.

Requirements

• Node.js 18+
• Express 4+
• A published Vybe service page with Collect enabled and at least one active offering
  Catalog: GET https://vybe.finance/api/agent/collect/{username}

Install

npm install express-vybe-402

Usage

const express = require("express");
const { requireVybePayment } = require("express-vybe-402");

const app = express();

app.get(
  "/v1/insights",
  requireVybePayment({
    username: "alex",
    offeringId: "svc_9fQ2Kd",
    // optional; defaults to process.env.VYBE_ORIGIN || https://vybe.finance
    origin: "https://vybe.finance",
  }),
  (req, res) => {
    res.json({ data: buildInsights(), payment: req.vybePayment });
  },
);

app.listen(3000);

Client flow

1. GET /v1/insights → 402 JSON body + PAYMENT-REQUIRED / X-Vybe-Public-Id
2. Settle payment against the Collect offering (see below)
3. GET /v1/insights with header X-Vybe-Public-Id: <publicId> → 200 and req.vybePayment

Settlement options:

| Path | How | |------|-----| | x402 | Call the Collect offering URL with PAYMENT-SIGNATURE (facilitator settles USDC on Base) | | tx hash | POST …/status with { publicId, txHash } after an on-chain USDC transfer to payTo | | Human | Open vybe.requestUrl (/r/{publicId}) and pay in Vybe |

Protocol details: docs/AGENT_COLLECT.md · Product: vybe.finance/collect

API

requireVybePayment(options)

Returns Express middleware.

| Option | Type | Description | |--------|------|-------------| | username | string | Seller username (no @) | | offeringId | string | Offering id from the Collect catalog | | origin | string? | Vybe API origin. Default: VYBE_ORIGIN or https://vybe.finance |

On success, sets req.vybePayment to the Collect status payload (status: "paid", amounts, settlementTxHash, …).

createCollectIntent(options)

POSTs the Collect offering URL and returns the 402 body (throws if the response is not 402).

getCollectStatus({ username, offeringId, publicId, origin?, txHash?, payerNote? })

Polls status, or settles when txHash is provided.

waitUntilPaid({ username, offeringId, publicId, origin?, timeoutMs?, intervalMs? })

Polls until paid, or throws on expired / cancelled / timeout (default 120s).

URL helpers

• collectOfferingUrl(username, offeringId, origin?)
• collectStatusUrl(username, offeringId, publicId, origin?)

Configuration

| Env | Default | Meaning | |-----|---------|---------| | VYBE_ORIGIN | https://vybe.finance | Base URL for Collect API calls |

Example app

npm install express express-vybe-402
VYBE_USERNAME=yourname VYBE_OFFERING_ID=svc_xxx VYBE_ORIGIN=https://vybe.finance \
  node node_modules/express-vybe-402/example.js

Then: GET http://localhost:4050/v1/report

License

MIT