Yolfi Agent Kit

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

Languages

Read this package guide in: English, Español, Deutsch, Français, 简体中文, Русский, हिन्दी, Türkçe, 한국어, 日本語.

Why Developers Use It

• Add AI agent payments to SaaS products, games, marketplaces, donation pages, digital downloads, internal tools, and agent-built apps.
• Give coding agents a safe payment workflow: inspect the app, authorize or reuse a workspace, ask for wallet and price decisions, create paylinks, install checkout, verify webhooks, and check payment status.
• Use one package for MCP crypto payments, JSON CLI automation, JavaScript SDK calls, webhook signature verification, and agent-readable instructions.
• Build with the existing Yolfi API instead of maintaining a second agent-only payment API.
• Help agents discover Yolfi through npm, GitHub, MCP directories, 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.

What It Can Add To An App

• Hosted crypto checkout through Yolfi paylinks.
• One-time payment links for digital products, credits, files, tools, or game items.
• Recurring or subscription-style payment link setup when the Yolfi account supports it.
• Donation and creator-support payment pages.
• Server routes that create public payment invoices from a paylink.
• Payment status polling through Yolfi public payment endpoints.
• Webhook handlers that verify X-Yolfi-Signature.
• Webhook-based entitlement logic that unlocks access only after confirmed payment events.
• Agent workflows for Codex, Claude Code, Cursor, OpenClaw, and custom automation.

Agent Skill

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 -> setup agent -> browser authorization -> checkin -> auth status -> 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

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

Authentication

The preferred local flow opens browser authorization and stores the resulting yolfi_agent_* credential in ~/.yolfi/config.json:

npx -y @yolfi/agent setup --agent codex
# Open the returned loginUrl and finish authentication.
npx -y @yolfi/agent checkin --agent codex
npx -y @yolfi/agent auth:status

The config directory and file are created with 0700 and 0600 permissions where supported. Set YOLFI_CONFIG_HOME to override the config directory in isolated development or CI environments.

Explicit credentials still work and take precedence over stored credentials:

export YOLFI_API_KEY="yolfi_agent_..."

The CLI and local MCP server also support email-confirmed signup for a new Yolfi user. The agent must ask the user to confirm the email and project name before registration:

export YOLFI_REGISTRATION_IDEMPOTENCY_KEY="76cd8dd3-b92a-42d6-ae2f-bc013752cf30"
yolfi auth:agent-register \
  --email "owner@example.com" \
  --project-name "Space Shop" \
  --agent-name "Codex" \
  --integration-intent accept_payments \
  --ref npm \
  --idempotency-key "$YOLFI_REGISTRATION_IDEMPOTENCY_KEY"

The first call creates a pending signup, emails the owner a confirmation link, and stores a protected check-in token locally. After the owner opens that link, run the exact same command again. The second call checks the pending signup, stores the one-time yolfi_agent_* credential in the protected local config, and removes the full credential from CLI/MCP output.

This command is signup-only. If the email already has a Yolfi account, use OAuth or local browser setup instead. If the pending signup expires or fails, use yolfi setup followed by yolfi checkin for the provisioned account rather than trying to register the same email again.

The CLI generates and persists a UUID when --idempotency-key is omitted. It automatically reuses that key and the protected check-in token for the repeated command and after a lost response. A new registration intent may pass a different 16–200 character key. The MCP yolfi_agent_register tool follows the same behavior through its optional idempotencyKey argument: call it once to send the email and again after confirmation.

Never print a full API key in logs, commit it, or write it into target-project documentation. See Agent and MCP setup for host-specific instructions.

Quick Start

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 one or more webhook endpoints. Deliveries, retries, and signing secrets are independent. The CLI stores each create/rotate secret in the protected local Yolfi config and prints only redacted metadata:

yolfi webhooks:add \
  --name "Application" \
  --url https://example.com/api/yolfi/webhook \
  --adapter NONE

yolfi webhooks:add \
  --name "Analytics endpoint" \
  --url https://analytics.example/api/payments/yolfi/<websiteId>/webhook \
  --adapter NONE \
  --metadata-filters '{"website_id":"<websiteId>"}'

yolfi webhooks:list

Endpoint create and update payloads accept optional flat metadataFilters string maps (at most 10 entries; keys at most 100 characters; values at most 255 characters); deliveries must match every configured key/value. Analytics routing uses the single key website_id; do not introduce alternative analytics keys. The CLI accepts filters as validated JSON through --metadata-filters. Use webhooks:update --id <endpointId> --json endpoint.json (optionally with --metadata-filters '{"website_id":"<websiteId>"}') to edit or enable/disable an analytics endpoint. webhooks:remove requires --confirm; endpoints with delivery history are disabled rather than deleting their audit relationship.

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

The invoice body requires paylinkId, network, symbol, and customerEmail. It also accepts optional clientReferenceId (your internal customer/order reference, returned as customer.clientReferenceId in webhooks), customerName, customerPhone, customerDateOfBirth, customerAddress, subscriptionId, language, and metadata.

Hosted Paylink URLs accept the same payment-scoped metadata through explicitly namespaced query parameters such as metadata[order_id]=order-123. Metadata keys must use letters, numbers, underscores, or dashes; values passed through the hosted URL are strings. The payment API also accepts finite numbers and booleans. Metadata is limited to 20 keys, 64 characters per key, and 500 characters per string value.