Yolfi Agent Kit

Yolfi Agent Kit is the official package, CLI, and MCP server for AI coding agents that add crypto payments to user applications.

Use it when a user asks an agent to add checkout, payment links, subscriptions, donations, webhook-based access logic, or payment-status checks with Yolfi.

Install

Run the package directly:

npx -y @yolfi/agent help

Start the MCP server:

npx -y @yolfi/agent mcp

Environment variables:

Register A Workspace

If the target app does not already have YOLFI_API_KEY, register an agent workspace:

yolfi auth:agent-register \
  --project-name "Space Shop" \
  --agent-name "Codex" \
  --integration-intent accept_payments \
  --ref docs

The returned API key is shown once. Store it in an ignored environment file or secret manager.

The registration response includes next actions:

• configure organization;
• configure settlement wallets;
• create or reuse a paylink;
• configure webhook;
• install checkout.

MCP Configuration

{
  "mcpServers": {
    "yolfi-api": {
      "command": "npx",
      "args": ["-y", "@yolfi/agent", "mcp"],
      "env": {
        "YOLFI_API_KEY": "..."
      }
    },
    "yolfi-knowledge": {
      "command": "npx",
      "args": ["-y", "@yolfi/agent", "mcp"]
    }
  }
}

The same server exposes API tools and knowledge resources. API tools need YOLFI_API_KEY; knowledge resources can be read without a key.

Agent Workflow

1. Inspect the target app first.
2. Find the framework, environment variable pattern, checkout UI, server routes, existing webhook handlers, and entitlement logic.
3. Check whether YOLFI_API_KEY already exists.
4. Register a Yolfi workspace only if no key exists.
5. Ask the user for settlement wallet addresses.
6. Ask the user for product names, price, currency, and one-time versus recurring decisions.
7. Create or reuse a paylink.
8. Store paylink IDs in ignored env/config files.
9. Add checkout UI or server routes using the target app's existing style.
10. Configure webhook URL and adapter in Yolfi.
11. Add webhook signature verification.
12. Connect webhook events to existing entitlement or fulfillment logic when possible.
13. Verify payment status through Yolfi before reporting completion.

Endpoint Adapter Matrix

CLI Commands

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 <sig>
yolfi mcp

Webhook Verification

Yolfi signs webhook payloads using X-Yolfi-Signature. In v1, the signing secret is the organization API key.

import { verifyWebhookSignature } from '@yolfi/agent';

const valid = verifyWebhookSignature(rawBody, signature, process.env.YOLFI_API_KEY);

Always verify the raw request body. Do not parse and re-stringify JSON before verification.

Safety Rules

Agents must not:

• invent wallet addresses;
• invent pricing;
• commit secrets;
• create duplicate paylinks after a timeout without listing existing paylinks first;
• disable paylinks without explicit user approval;
• replace existing billing logic unnecessarily.

Related Resources

• Yolfi Agent Kit
• AI Agent Payment Integration API
• npm package
• GitHub repository
• Webhooks
• Webhook signatures
• Paylinks