Yolfi Agent

Thin SDK, CLI, and MCP adapter for AI coding agents that add Yolfi crypto payments to user apps.

This package does not create a second Yolfi API. It maps agent actions to the existing Yolfi endpoints:

Agent action	Endpoint
Register workspace	`POST /api/auth/agent/register`
Check account	`GET /api/private/organization/current`
Configure organization/webhooks/settlement	`PUT /api/private/organization/current`
Create paylink	`POST /api/private/paylinks/create`
List paylinks	`GET /api/private/paylinks`
Create payment	`POST /api/public/payments`
Payment status	`GET /api/public/payments/:id`

Install

npx -y @yolfi/agent help

Register Agent Workspace

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

The returned apiKey is shown once. Store it in an ignored env file as YOLFI_API_KEY.

MCP

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

Safety Rules

Ask the user for settlement wallet addresses.
Ask the user for product names, price, currency, and recurring interval.
Do not commit YOLFI_API_KEY.
Do not treat redirects as payment confirmation.
Verify X-Yolfi-Signature on webhook payloads.
List existing paylinks before creating another paylink after a timeout.
Require explicit user approval before disabling paylinks.

Webhook Verification

Yolfi signs the raw JSON payload with HMAC-SHA256 base64 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);