Vybe Collect integration guide

Overview

Vybe Collect is the get-paid rail: one catalog for humans and AI agents. Settlement is USDC and USDT on Base, Ethereum, and BNB — not card acquiring. Credits land on the same Vybe balance as human payment requests.

Building tonight? Use the short hackathon path — claim, publish, gate with express-vybe-402, then settle a 402.

Pick a track

You can run more than one track — e.g. a freelancer catalog (C) plus a gated API (A). Choose based on how buyers reach you.

Install skills

Recommended via skills.sh (works across 70+ agents). Global install (-g) makes skills available in every project.

# Cursor, Claude Code, Codex, Copilot, 70+ agents
npx skills add Vybe-Finance/vybe-collect -g -y
npx skills add Vybe-Finance/vybe-checkout -g -y

# Or clone into your project (Cursor slash menu: /vybe-collect)
git clone https://github.com/Vybe-Finance/vybe-collect.git .cursor/skills/vybe-collect
git clone https://github.com/Vybe-Finance/vybe-checkout.git .cursor/skills/vybe-checkout

Repos: vybe-collect · vybe-checkout

Copy prompts

Paste into Agent chat after installing skills. Replace placeholders (YOURNAME, svc_…, webhook URL) before sending.

Kickoff

Before coding, install Vybe integration skills:

npx skills add Vybe-Finance/vybe-collect -g -y
npx skills add Vybe-Finance/vybe-checkout -g -y

Then read https://www.vybe.finance/collect/integrate and implement Track [A|B|C] for:
[describe your product, routes, and fulfillment logic]

Track A — gate API / MCP

Integrate Vybe Collect on my Express API.

Requirements:
- Gate GET /v1/scan with express-vybe-402 (username: YOURNAME, offeringId: svc_scan)
- VYBE_ORIGIN=https://www.vybe.finance
- Register payment.paid webhook → credit API quota idempotently
- Smoke test: unpaid → 402 + PAYMENT-REQUIRED → settle → retry with X-Vybe-Public-Id

Use the vybe-collect skill if installed. Do not use card checkout — settlement is USDC/USDT via HTTP 402.

Track A — API / MCP product (invoke proxy)

I'm monetizing an API or MCP tool (e.g. wallet scan, enrichment).

Use Vybe Collect HTTP 402 — NOT Paystack or card checkout for agent/API buyers.

Plan:
1. Create api or mcp offering with integration.invokeBaseUrl or integration.mcpServerUrl
2. Optionally express-vybe-402 on my origin OR use Vybe invoke proxy only
3. payment.paid webhook for quota / fulfillment
4. Document trial requests if offering supports VAPT

Canonical origin: https://www.vybe.finance

Track B — Native Checkout

Add Vybe Native Checkout to my app.

Requirements:
- Server-side POST https://www.vybe.finance/api/checkout/sessions with Authorization: Bearer vybe_col_… from env VYBE_COLLECT_API_KEY (never NEXT_PUBLIC_)
- Support fixed SKU (line_items price svc_…) and dynamic invoice amounts
- Redirect humans to session.url (/r/{id})
- Fulfill on payment.paid webhook — idempotent, verify X-Vybe-Signature
- Optional: agents hit same /r/ URL with Accept: application/json for 402

Use vybe-checkout skill if installed.

Track C — codeless

Help me enable Vybe Collect without code.

Checklist:
- Claim @username on Vybe
- Publish offerings on my service page (price, duration, terms)
- Toggle "Accept payments from AI agents"
- Share human page /s/@me and agent docs /a/@me
- Confirm GET /api/agent/collect/me returns my catalog

No vybe_col_ key required for this path.

Agent briefs (llms.txt)

External agents that cannot install skills can read the public briefs:

• /llms.txt — short index
• /llms-full.txt — expanded protocol notes

Track A — Gate your API or MCP

Pay-per-request for agents and scripts. Callers get HTTP 402 until they settle USDC or USDT, then retry with X-Vybe-Public-Id. Not a card checkout page.

1. Enable Collect

Sign in → Business → Services. Publish an offering (per-request SKU). Toggle Accept payments from AI agents.

2. Mint a Collect key

Business → Developers → create vybe_col_…. Used for offerings API, webhooks, and checkout — not sent to public 402 callers.

curl -X POST https://www.vybe.finance/api/collect/v1/credentials \
  -H "Cookie: …" \
  -H "Content-Type: application/json"

3. Upsert offerings (optional)

curl -X PUT https://www.vybe.finance/api/collect/v1/offerings \
  -H "Authorization: Bearer vybe_col_…" \
  -H "Content-Type: application/json" \
  -d '{
    "offerings": [{
      "id": "svc_scan",
      "title": "Wallet scan",
      "priceUsd": "0.05",
      "kind": "api",
      "integration": {
        "invokeBaseUrl": "https://api.yourservice.com"
      }
    }],
    "agentCollectEnabled": true
  }'

4. Install express-vybe-402

npm install express-vybe-402

import express from "express";
import { requireVybePayment } from "express-vybe-402";

const app = express();

app.get(
  "/v1/scan",
  requireVybePayment({
    username: "yourname",
    offeringId: "svc_scan",
    origin: "https://www.vybe.finance",
  }),
  (req, res) => {
    res.json({ safe: true, payment: req.vybePayment });
  },
);

app.listen(3000);

5. Webhook for fulfillment

See Webhooks. Register URL, handle payment.paid to credit quota or unlock access.

curl -X PUT https://www.vybe.finance/api/collect/v1/webhook \
  -H "Authorization: Bearer vybe_col_…" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://you.com/hooks/vybe" }'

6. Smoke 402 → pay → retry

# Unpaid — expect 402
curl -i https://www.vybe.finance/api/agent/collect/yourname/svc_scan

# Settle (x402 PAYMENT-SIGNATURE, or POST …/status with txHash)

# Retry gated route
curl -i https://your-api.com/v1/scan \
  -H "X-Vybe-Public-Id: PUBLIC_ID_FROM_402"

curl "https://www.vybe.finance/api/collect/v1/prepaid-balances?buyerCrossmintId=…&offeringId=svc_scan" \
  -H "Authorization: Bearer vybe_col_…"

// Optional: double-check before running the tool
const status = await fetch(
  "https://www.vybe.finance/api/agent/collect/YOURNAME/OFFERING_ID/status?publicId=" +
    encodeURIComponent(publicId),
);
// Expect paid + matching offeringId; mark consumed in your DB when tool runs

Track B — Hosted checkout

Your server creates a checkout.session, returns /r/{id}, fulfills on payment.paid. Fixed catalog SKUs or dynamic invoice totals.

1. Collect key + offerings

Same desk setup as Track A. Test sessions from Business → Checkout.

2. Create session

curl https://www.vybe.finance/api/checkout/sessions \
  -H "Authorization: Bearer vybe_col_…" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "payment",
    "line_items": [{ "price": "svc_OFFERING_ID", "quantity": 1 }]
  }'

curl https://www.vybe.finance/api/checkout/sessions \
  -H "Authorization: Bearer vybe_col_…" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "payment",
    "line_items": [
      { "offering_id": "svc_A", "quantity": 2 },
      { "offering_id": "svc_B", "variant_id": "var_…", "quantity": 1 }
    ],
    "shipping_amount": "5.00",
    "shipping_address": {
      "name": "Buyer",
      "line1": "1 Main St",
      "city": "Lagos",
      "country": "NG"
    }
  }'

curl https://www.vybe.finance/api/checkout/sessions \
  -H "Authorization: Bearer vybe_col_…" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "payment",
    "amount": "42.50",
    "currency": "usdc",
    "memo": "Invoice #1042"
  }'

3. Share hosted URL

Humans → session.url. Agents → same URL with Accept: application/json.

curl -i https://www.vybe.finance/r/SESSION_ID \
  -H "Accept: application/json"
# → HTTP 402, agent_pay_url, PAYMENT-REQUIRED

4. Fulfill on paid

Poll GET /api/checkout/sessions/{id} or webhook. Keep handlers idempotent.

5. Redirect URLs (optional)

success_url / cancel_url are UX only — prove payment via webhook or status poll.

Native Checkout overview

Track C — Codeless

No API keys or middleware. Publish once; humans and agents pay from your catalog.

1. Sign in and claim @username
2. Add offerings under Services — price, duration, terms — Publish
3. Toggle Accept payments from AI agents
4. Share /s/@you (humans), /a/@you (agent docs), GET /api/agent/collect/yourname (catalog JSON)

Collect marketing page

Webhooks

Register in the desk or via API. Verify X-Vybe-Signature (HMAC-SHA256). Respond 2xx quickly. Events: payment.paid, payment.expired, and webhook.test (from Business → Integration health).

Checkout session metadata at create time is echoed on payment.paid and payment.expired when set.

POST https://you.com/hooks/vybe
X-Vybe-Signature: sha256=…

{
  "type": "payment.paid",
  "publicId": "Vh3xR2mQ",
  "offeringId": "svc_9fQ2Kd",
  "amount": "150.00",
  "token": "usdc",
  "settlementTxHash": "0x…",
  "metadata": {
    "order_id": "ord_1042",
    "user_id": "usr_abc"
  }
}

• Verify signature before trusting the body
• Idempotent handling — retries happen
• Handle webhook.test during desk integration checks

POST https://you.com/hooks/vybe
X-Vybe-Signature: sha256=…

{
  "protocol": "vybe-agent-collect",
  "version": "0.1",
  "type": "webhook.test",
  "message": "Vybe Collect integration health ping — respond 2xx to confirm delivery.",
  "username": "yourname",
  "sentAt": "2026-08-27T22:00:00.000Z"
}

Smoke test

• Catalog returns offerings with Collect enabled
• Unpaid call → 402 + PAYMENT-REQUIRED
• Test payment credits Vybe balance
• Webhook fires with valid signature
• Gated route accepts X-Vybe-Public-Id after pay
• Hosted /r/ session → payment_status: paid

curl https://www.vybe.finance/api/agent/collect/yourname

Business desk

Keys, webhooks, test checkout sessions, and revenue analytics live in Business mode. Buyer-side VAPT / Pay MCP is separate.