@yolfi/agent
Advanced tools
AI agent payment integration SDK, CLI, and MCP server for adding Yolfi crypto checkout, payment links, webhooks, and payment status checks.
AI agent payment integration for crypto checkout. Yolfi Agent Kit is a JSON-first SDK, CLI, Agent Skill, and MCP server that lets AI coding agents add stablecoin checkout, payment links, payment status checks, webhook verification, and webhook-based access logic to applications through Yolfi.
Use @yolfi/agent when Codex, Claude Code, Cursor, OpenClaw, an MCP host, or a custom AI agent can build the product but still needs a reliable payment API to register a Yolfi workspace, create a paylink, configure webhooks, and verify crypto payment status without sending the user through manual dashboard setup.
Website | Agent Kit | Docs | npm | GitHub | Glama | Guide
Read this package guide in: English, Español, Deutsch, Français, 简体中文, Русский, हिन्दी, Türkçe, 한국어, 日本語.
llms.txt, docs, examples, and integration guides.Yolfi handles crypto payment infrastructure, hosted checkout, paylinks, public payment invoices, organization settings, settlement wallet configuration, and webhook delivery. Your agent handles project inspection, code changes, user confirmation, and target-app integration.
X-Yolfi-Signature.This package includes the Yolfi Payments Skill in SKILL.md. Use it with coding agents when the user asks to add crypto payments, payment links, checkout, subscriptions, donations, paid downloads, paid access, or webhook-based entitlements.
Recommended safe workflow:
inspect app -> check YOLFI_API_KEY -> register if needed -> ask user for wallet and price -> configure organization -> create or reuse paylink -> add checkout -> add webhook verification -> verify status
The skill tells agents what they may do automatically and what they must ask the user to decide. Agents must never invent wallet addresses, prices, plans, currencies, secret storage locations, or destructive paylink actions.
Install in a project:
npm install @yolfi/agent
Or run without installing:
npx -y @yolfi/agent help
Start the stdio MCP server:
npx -y @yolfi/agent mcp
For local development inside this repository:
node packages/yolfi-agent/src/cli.js help
Private commands use a Yolfi organization API key:
export YOLFI_API_KEY="yolfi_..."
export YOLFI_API_BASE_URL="https://app.yolfi.com/api"
export YOLFI_PAY_BASE_URL="https://pay.yolfi.com"
YOLFI_API_BASE_URL and YOLFI_PAY_BASE_URL are optional unless you need a non-default Yolfi environment.
If the target app does not already have YOLFI_API_KEY, an agent can register a workspace through the agent registration endpoint:
yolfi auth:agent-register \
--project-name "Space Shop" \
--agent-name "Codex" \
--integration-intent accept_payments \
--ref npm
The returned API key is shown once. Store it in an ignored env file, deployment secret, or secret manager. Do not print the full key in logs, commit it, or write it into README files in the target project.
Check the workspace linked to the API key:
yolfi auth:status
Configure settlement wallets after the user provides wallet addresses:
yolfi settlement:configure --json examples/organization.settlement.json
Configure webhook delivery:
yolfi webhooks:configure \
--url https://example.com/api/yolfi/webhook \
--adapter STRIPE
List existing paylinks before creating duplicates:
yolfi paylinks:list --page 1 --rows 10
Create a one-time payment link:
yolfi paylinks:create --json examples/paylink.one-time.json
Create a public payment invoice from a paylink:
yolfi payments:create --json examples/payment.create.json
Check payment status:
yolfi payments:status --id <paymentId>
Every CLI command prints JSON so agents can parse results without scraping terminal text.
Yolfi Agent Kit includes a stdio MCP server in the same npm package:
{
"mcpServers": {
"yolfi-api": {
"command": "npx",
"args": ["-y", "@yolfi/agent", "mcp"],
"env": {
"YOLFI_API_KEY": "..."
}
},
"yolfi-knowledge": {
"command": "npx",
"args": ["-y", "@yolfi/agent", "mcp"]
}
}
}
yolfi-api tools call the Yolfi API and require YOLFI_API_KEY. yolfi-knowledge resources help an agent understand the integration path before a key exists.
Available MCP tools:
yolfi_auth_statusyolfi_organization_getyolfi_organization_updateyolfi_settlement_configureyolfi_webhooks_configureyolfi_paylinks_createyolfi_paylinks_listyolfi_paylinks_getyolfi_paylinks_disableyolfi_payments_createyolfi_payments_statusyolfi_webhooks_verifyDestructive tools such as yolfi_paylinks_disable must only run after explicit user confirmation.
Agents can write a payload file and pass it to the CLI:
{
"name": "Premium Download",
"description": "One-time access to a digital product.",
"type": "ONE_TIME",
"price": "19",
"currency": "USD",
"collectEmail": true,
"metadata": {
"source": "agent",
"productSlug": "premium-download"
}
}
Then run:
yolfi paylinks:create --json ./paylink.json
Agents should keep the returned paylink ID in env/config for the target app and use Yolfi public payment endpoints for customer-facing checkout and status polling.
yolfi auth:agent-register --project-name "App" --agent-name "Codex" --integration-intent accept_payments
yolfi auth:status
yolfi organization:update --json organization.json
yolfi settlement:configure --json settlement.json
yolfi webhooks:configure --url https://example.com/api/yolfi/webhook --adapter STRIPE
yolfi paylinks:create --json paylink.json
yolfi paylinks:list --page 1 --rows 10
yolfi paylinks:get --id <paylinkId>
yolfi paylinks:disable --id <paylinkId> --confirm
yolfi payments:create --json payment.json
yolfi payments:status --id <paymentId>
yolfi webhooks:verify --payload payload.json --signature <signature>
yolfi mcp
Yolfi Agent Kit does not create a second /api/agent/* API. It maps agent actions to the current Yolfi API:
| Agent action | Backend endpoint | Auth |
|---|---|---|
| Register Yolfi workspace | POST /api/auth/agent/register | public |
| Check account | GET /api/private/organization/current | bearer API key |
| Configure organization, webhook, settlement wallets | PUT /api/private/organization/current | bearer API key |
| Get API key status | GET /api/private/organization/api-key | bearer API key or cookie |
| Create paylink | POST /api/private/paylinks/create | bearer API key |
| List paylinks | GET /api/private/paylinks | bearer API key |
| Get paylink | GET /api/private/paylinks/:id | bearer API key |
| Edit paylink | POST /api/private/paylinks/edit | bearer API key |
| Disable paylink | POST /api/private/paylinks/disable | bearer API key plus confirmation |
| Public paylink checkout info | GET /api/public/paylinks/:id | public |
| Create public payment invoice | POST /api/public/payments | public |
| Payment status | GET /api/public/payments/:id | public |
| Merchant transactions | GET /api/private/transactions | bearer API key |
import { YolfiClient } from "@yolfi/agent";
const yolfi = new YolfiClient({
apiKey: process.env.YOLFI_API_KEY,
});
const account = await yolfi.authStatus();
const paylink = await yolfi.createPaylink({
name: "Premium Download",
description: "One-time access to a digital product.",
type: "ONE_TIME",
price: "19",
currency: "USD",
collectEmail: true,
metadata: {
source: "agent",
productSlug: "premium-download",
},
});
console.log(account.success);
console.log(paylink.data?.id ?? paylink.id);
Yolfi signs webhook payloads with X-Yolfi-Signature. Verify the raw request body before parsing and trusting the event:
import { verifyWebhookSignature } from "@yolfi/agent";
const valid = verifyWebhookSignature(
rawBody,
request.headers["x-yolfi-signature"],
process.env.YOLFI_API_KEY,
);
if (!valid) {
throw new Error("Invalid Yolfi webhook signature");
}
Do not treat a frontend redirect as proof of payment. Use verified webhooks and Yolfi payment status checks.
Yolfi Agent Kit is designed for agentic payment workflows where the user gives a high-level instruction like "add payments", "sell this digital product", "add a donation button", "charge for this game", or "gate this feature behind payment".
Recommended agent path:
auth:status -> organization:get -> paylinks:list -> user approval -> settlement:configure -> webhooks:configure -> paylinks:create -> install checkout -> verify webhook -> payments:status
The examples/ folder includes copy-paste workflows and JSON payloads:
examples/codex/add-yolfi-payments.mdexamples/claude-code/add-yolfi-payments.mdexamples/cursor/add-yolfi-payments.mdexamples/paylink.one-time.jsonexamples/paylink.recurring.jsonexamples/organization.settlement.jsonexamples/payment.create.jsonexamples/webhook.stripe-adapter.jsonDevelopers and agent builders often look for:
Yolfi Agent Kit is the package entry point for those workflows.
FAQs
AI agent payment integration SDK, CLI, and MCP server for adding Yolfi crypto checkout, payment links, webhooks, and payment status checks.
The npm package @yolfi/agent receives a total of 42 weekly downloads. As such, @yolfi/agent popularity was classified as not popular.
We found that @yolfi/agent demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
Socket joins more than 100 technology, cybersecurity, and financial organizations calling for a global surge in cyber defense.
Product
Enterprise security teams can now detect malware, credential theft, suspicious network activity, and risky updates across Microsoft Edge extensions.
Research
/Security News
Socket researchers found 18 Chrome extensions and one Edge extension delivering a wallet drainer, credential theft, and other malicious payloads.