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.

Choose Remote Or Local MCP

Use remote MCP for hosted connectors and agents that can reach Yolfi over HTTPS. It does not require a local package or a copied API key:

https://app.yolfi.com/mcp

Use local MCP when the coding agent runs on your machine and needs local project access. The local server is distributed with @yolfi/agent:

npx -y @yolfi/agent mcp

Both transports expose the same core payment workflow, knowledge resources, and guided prompts. Local MCP additionally exposes browser setup/check-in and local webhook-signature verification helpers.

Email-confirmed signup for a new user

If the user does not have a Yolfi account, the agent can ask them to confirm an email and project name, then start signup without opening the dashboard:

npx -y @yolfi/agent auth:agent-register \
  --email "owner@example.com" \
  --project-name "Space Shop" \
  --agent-name "Codex" \
  --integration-intent accept_payments

The first call sends the owner a confirmation link and stores only a temporary check-in token in the protected local config. After the owner opens that link, run the same command again with the same arguments. The second call retrieves and stores the one-time agent credential without exposing it in CLI or MCP output, after which the agent can continue with yolfi_auth_status.

This is signup-only. An existing email is rejected and must use OAuth or local browser setup. If a pending signup expires or fails after provisioning, connect the account through browser setup instead of trying to register the same email again.

Verify The Connection In The Agent

The hosted MCP URL is a public service endpoint. Reaching that URL only proves that the Yolfi server is online; it does not prove that Codex, ChatGPT, Claude, or another client completed OAuth for your account. Yolfi therefore does not use a dashboard ping as connection confirmation.

After the MCP host finishes OAuth, or after local setup and check-in, ask the agent to run:

yolfi_auth_status

A successful authenticated tool result is the source of truth for that agent session. If it fails, finish authorization in that client or start a new local browser setup.

Remote MCP Setup

Codex

codex mcp add yolfi --url https://app.yolfi.com/mcp
codex mcp login yolfi

Claude Code

claude mcp add --transport http yolfi https://app.yolfi.com/mcp

Then open Claude Code, run /mcp, select Yolfi, and complete the browser authorization flow.

Claude Web, Desktop, And Mobile

Add a custom connector named Yolfi with this URL:

https://app.yolfi.com/mcp

When the agent first connects, Yolfi opens a browser consent page. Sign in, review the requested read/write access and approve only a connection you initiated.

ChatGPT

In the ChatGPT desktop app, open Settings → MCP servers, add a Streamable HTTP server named Yolfi, use https://app.yolfi.com/mcp, restart, and select Authenticate. ChatGPT web uses a remote MCP-backed plugin in Work mode; it cannot start the local package or read Codex's local MCP configuration.

Cursor

Add a remote MCP server through Cursor settings, or place this entry in the relevant mcp.json:

{
  "mcpServers": {
    "yolfi": {
      "url": "https://app.yolfi.com/mcp"
    }
  }
}

Complete OAuth when Cursor asks you to authenticate the server.

Hermes

Add Yolfi to the Hermes MCP configuration:

mcp_servers:
  yolfi:
    url: https://app.yolfi.com/mcp
    auth: oauth

Then run hermes mcp login yolfi if the browser flow does not start automatically.

OpenClaw And Other Local Agents

Agents without remote OAuth MCP support can use the local stdio server and browser setup flow described below. Generic clients that support Streamable HTTP, protected-resource discovery, DCR, Authorization Code + PKCE, and refresh-token rotation can connect directly to the remote URL.

Local CLI And MCP Setup

Run the package directly:

npx -y @yolfi/agent help

Start the MCP server:

npx -y @yolfi/agent mcp

The local authentication flow avoids copying an organization API key:

npx -y @yolfi/agent setup --agent codex
# Open the returned loginUrl and approve the connection in Yolfi.
npx -y @yolfi/agent checkin --agent codex
npx -y @yolfi/agent auth:status

The CLI stores the resulting agent credential in ~/.yolfi/config.json with owner-only permissions. Set YOLFI_CONFIG_HOME only for CI, tests, or isolated profiles.

Add the local server to Codex:

codex mcp add yolfi -- npx -y @yolfi/agent mcp

Or to Claude Code:

claude mcp add --transport stdio yolfi -- npx -y @yolfi/agent mcp

Environment variables:

Manual API-Key Setup

Use a manually managed API key for CI or another non-interactive environment where browser authorization is unavailable. Create or rotate the key in Settings → API keys, then store it in an ignored environment file or secret manager:

export YOLFI_API_KEY="<your API key>"
npx -y @yolfi/agent auth:status

Yolfi never inserts or reveals an existing organization key on the Agent Kit page. Copy it explicitly from API-key settings. Do not use it as a webhook signing secret.

Generic Local MCP Configuration

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

If browser setup has already stored an agent credential, omit the env block. The same server exposes API tools, knowledge resources, and guided prompts.

Generic clients that support Streamable HTTP and OAuth should use the remote URL. Clients that only support custom headers may use a manually created API key as a fallback:

{
  "url": "https://app.yolfi.com/mcp",
  "transport": "streamable-http",
  "headers": {
    "Authorization": "Bearer yolfi_agent_..."
  }
}

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 authentication with yolfi_auth_status.
4. If authentication is missing, use remote OAuth or local browser setup for an existing account. For a new user, confirm their email and project name before calling yolfi_agent_register.
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

Knowledge Resources And Guided Prompts

MCP hosts can read embedded resources for the agent quickstart, paylinks, webhooks, and Codex, Claude Code, or Cursor setup. The remote and local servers also expose prompts for:

• integrating Yolfi checkout and verified webhook handling;
• creating or reusing a paylink;
• adding a raw-body webhook handler;
• verifying the complete payment flow;
• reusing a Stripe-style webhook path through a Yolfi adapter.

These resources contain workflow guidance, not credentials. Current organization state must still be read through scoped tools.

CLI Commands

npx -y @yolfi/agent setup --agent codex
npx -y @yolfi/agent checkin --agent codex
npx -y @yolfi/agent auth:agent-register --email "owner@example.com" --project-name "App" --agent-name "Codex" --integration-intent accept_payments
npx -y @yolfi/agent auth:status
npx -y @yolfi/agent organization:update --json organization.json
npx -y @yolfi/agent settlement:configure --json settlement.json
npx -y @yolfi/agent webhooks:configure --url https://example.com/api/yolfi/webhook --adapter STRIPE
npx -y @yolfi/agent paylinks:create --json paylink.json
npx -y @yolfi/agent paylinks:list --page 1 --rows 10
npx -y @yolfi/agent paylinks:get --id <paylinkId>
npx -y @yolfi/agent paylinks:disable --id <paylinkId> --confirm
npx -y @yolfi/agent payments:create --json payment.json
npx -y @yolfi/agent payments:status --id <paymentId>
npx -y @yolfi/agent webhooks:verify --payload payload.json --signature <sig>
npx -y @yolfi/agent mcp

Webhook Verification

Yolfi signs webhook payloads using X-Yolfi-Signature. Each webhook endpoint has its own signing secret, returned only when that endpoint is created or rotated.

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

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

Always verify the raw request body. Do not parse and re-stringify JSON before verification. Never use YOLFI_API_KEY as the webhook signing secret.

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