{
  "markdown": "![Yolfi Agent Kit: AI agent payment integration for crypto checkout, payment links, MCP, CLI, SDK, and webhooks](assets/ai-agent-payment.jpg)\n\n# Yolfi Agent Kit\n\n[![npm version](https://img.shields.io/npm/v/@yolfi/agent.svg)](https://www.npmjs.com/package/@yolfi/agent)\n[![license](https://img.shields.io/npm/l/@yolfi/agent.svg)](LICENSE)\n[![Node.js 18+](https://img.shields.io/badge/node-%3E%3D18-0b7f79)](package.json)\n[![Yolfi MCP server](https://glama.ai/mcp/servers/yolfinance/yolfi-agent/badges/card.svg)](https://glama.ai/mcp/servers/yolfinance/yolfi-agent)\n[![Yolfi MCP score](https://glama.ai/mcp/servers/yolfinance/yolfi-agent/badges/score.svg)](https://glama.ai/mcp/servers/yolfinance/yolfi-agent)\n\nAI 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.\n\nUse `@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.\n\n[Website](https://yolfi.com) | [Agent Kit](https://yolfi.com/ai-agent-kit) | [Docs](https://docs.yolfi.com/en/agent-kit) | [npm](https://www.npmjs.com/package/@yolfi/agent) | [GitHub](https://github.com/yolfinance/yolfi-agent) | [Glama](https://glama.ai/mcp/servers/yolfinance/yolfi-agent) | [Guide](https://yolfi.com/blog/ai-agent-payment-integration-api)\n\n## Languages\n\nRead this package guide in:\n[English](README.md),\n[Español](docs/i18n/README.es.md),\n[Deutsch](docs/i18n/README.de.md),\n[Français](docs/i18n/README.fr.md),\n[简体中文](docs/i18n/README.zh-CN.md),\n[Русский](docs/i18n/README.ru.md),\n[हिन्दी](docs/i18n/README.hi.md),\n[Türkçe](docs/i18n/README.tr.md),\n[한국어](docs/i18n/README.ko.md),\n[日本語](docs/i18n/README.ja.md).\n\n## Why Developers Use It\n\n- Add AI agent payments to SaaS products, games, marketplaces, donation pages, digital downloads, internal tools, and agent-built apps.\n- 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.\n- Use one package for MCP crypto payments, JSON CLI automation, JavaScript SDK calls, webhook signature verification, and agent-readable instructions.\n- Build with the existing Yolfi API instead of maintaining a second agent-only payment API.\n- Help agents discover Yolfi through npm, GitHub, MCP directories, `llms.txt`, docs, examples, and integration guides.\n\nYolfi 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.\n\n## What It Can Add To An App\n\n- Hosted crypto checkout through Yolfi paylinks.\n- One-time payment links for digital products, credits, files, tools, or game items.\n- Recurring or subscription-style payment link setup when the Yolfi account supports it.\n- Donation and creator-support payment pages.\n- Server routes that create public payment invoices from a paylink.\n- Payment status polling through Yolfi public payment endpoints.\n- Webhook handlers that verify `X-Yolfi-Signature`.\n- Webhook-based entitlement logic that unlocks access only after confirmed payment events.\n- Agent workflows for Codex, Claude Code, Cursor, OpenClaw, and custom automation.\n\n## Agent Skill\n\nThis 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.\n\nRecommended safe workflow:\n\n```txt\ninspect 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\n```\n\nThe 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.\n\n## Install\n\nInstall in a project:\n\n```bash\nnpm install @yolfi/agent\n```\n\nOr run without installing:\n\n```bash\nnpx -y @yolfi/agent help\n```\n\nStart the stdio MCP server:\n\n```bash\nnpx -y @yolfi/agent mcp\n```\n\nFor local development inside this repository:\n\n```bash\nnode packages/yolfi-agent/src/cli.js help\n```\n\n## Authentication\n\nThe preferred local flow opens browser authorization and stores the resulting `yolfi_agent_*` credential in `~/.yolfi/config.json`:\n\n```bash\nnpx -y @yolfi/agent setup --agent codex\n# Open the returned loginUrl and finish authentication.\nnpx -y @yolfi/agent checkin --agent codex\nnpx -y @yolfi/agent auth:status\n```\n\nThe 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.\n\nExplicit credentials still work and take precedence over stored credentials:\n\n```bash\nexport YOLFI_API_KEY=\"yolfi_agent_...\"\n```\n\nThe 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:\n\n```bash\nexport YOLFI_REGISTRATION_IDEMPOTENCY_KEY=\"76cd8dd3-b92a-42d6-ae2f-bc013752cf30\"\nyolfi auth:agent-register \\\n  --email \"owner@example.com\" \\\n  --project-name \"Space Shop\" \\\n  --agent-name \"Codex\" \\\n  --integration-intent accept_payments \\\n  --ref npm \\\n  --idempotency-key \"$YOLFI_REGISTRATION_IDEMPOTENCY_KEY\"\n```\n\nThe 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.\n\nThis 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.\n\nThe 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.\n\nNever print a full API key in logs, commit it, or write it into target-project documentation. See [Agent and MCP setup](docs/agent-setup.md) for host-specific instructions.\n\n## Quick Start\n\nCheck the workspace linked to the API key:\n\n```bash\nyolfi auth:status\n```\n\nConfigure settlement wallets after the user provides wallet addresses:\n\n```bash\nyolfi settlement:configure --json examples/organization.settlement.json\n```\n\nConfigure 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:\n\n```bash\nyolfi webhooks:add \\\n  --name \"Application\" \\\n  --url https://example.com/api/yolfi/webhook \\\n  --adapter NONE\n\nyolfi webhooks:add \\\n  --name \"Analytics endpoint\" \\\n  --url https://analytics.example/api/payments/yolfi/<websiteId>/webhook \\\n  --adapter NONE \\\n  --metadata-filters '{\"website_id\":\"<websiteId>\"}'\n\nyolfi webhooks:list\n```\n\nEndpoint 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.\n\nList existing paylinks before creating duplicates:\n\n```bash\nyolfi paylinks:list --page 1 --rows 10\n```\n\nCreate a one-time payment link:\n\n```bash\nyolfi paylinks:create --json examples/paylink.one-time.json\n```\n\nCreate a public payment invoice from a paylink:\n\n```bash\nyolfi payments:create --json examples/payment.create.json\n```\n\nThe invoice body requires `paylinkId`, `network`, `symbol`, and `customerEmail`. It also accepts optional\n`clientReferenceId` (your internal customer/order reference, returned as\n`customer.clientReferenceId` in webhooks), `customerName`, `customerPhone`, `customerDateOfBirth`,\n`customerAddress`, `subscriptionId`, `language`, and `metadata`.\n\nHosted Paylink URLs accept the same payment-scoped metadata through explicitly namespaced query\nparameters such as `metadata[order_id]=order-123`. Metadata keys must use letters, numbers,\nunderscores, or dashes; values passed through the hosted URL are strings. The payment API also\naccepts finite numbers and booleans. Metadata is limited to 20 keys, 64 characters per key, and\n500 characters per string value.\n\nUse a stable customer or application-user id for `clientReferenceId` when webhook handlers must\nresolve subscription ownership. Native (`NONE`) payloads expose it as\n`data.customer.clientReferenceId`; Stripe-compatible Checkout Session payloads use\n`data.object.client_reference_id`, Stripe-compatible Invoice and Subscription payloads use\n`data.object.metadata.client_reference_id`, and Lemon Squeezy-compatible payloads use\n`meta.custom_data.client_reference_id`.\n\nCheck payment status:\n\n```bash\nyolfi payments:status --id <paymentId>\n```\n\nEvery CLI command prints JSON so agents can parse results without scraping terminal text.\n\n## MCP Server For Crypto Payments\n\nYolfi provides both a production streamable HTTP endpoint and a local stdio server:\n\n```txt\nRemote: https://app.yolfi.com/mcp\nLocal:  npx -y @yolfi/agent mcp\n```\n\nThe packaged Codex and Claude plugins use the bundled local stdio server so agent setup, check-in, and new-user registration are available as MCP tools. A manually configured remote connection uses OAuth managed by the MCP host and does not expose those local credential tools.\n\nCodex remote:\n\n```bash\ncodex mcp add yolfi --url https://app.yolfi.com/mcp\ncodex mcp login yolfi\n```\n\nCodex local:\n\n```bash\ncodex mcp add yolfi -- npx -y @yolfi/agent mcp\n```\n\nClaude Code remote:\n\n```bash\nclaude mcp add --transport http yolfi https://app.yolfi.com/mcp\n```\n\nThen open Claude Code, run `/mcp`, select Yolfi, and complete browser authorization.\n\nClaude Code local:\n\n```bash\nclaude mcp add yolfi -- npx -y @yolfi/agent mcp\n```\n\nGeneric local MCP configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"yolfi\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@yolfi/agent\", \"mcp\"]\n    }\n  }\n}\n```\n\nAfter connecting a local server, call `yolfi_agent_setup_start` with a stable `agent` slug, open the returned `loginUrl`, then call `yolfi_agent_checkin` with the same slug. The local server stores the connected credential securely. For CI and other non-interactive environments, provide a manually managed `YOLFI_API_KEY` instead.\n\nFor ChatGPT desktop, open **Settings → MCP servers → Add server**, choose **Streamable HTTP**, enter `https://app.yolfi.com/mcp`, save, and restart. ChatGPT web uses a remote MCP-backed plugin in Work mode; it cannot start the local stdio command or read local Codex configuration. Detailed ChatGPT developer-mode and plugin steps are in [docs/agent-setup.md](docs/agent-setup.md).\n\nAvailable MCP tools:\n\n- `yolfi_agent_setup_start`\n- `yolfi_agent_checkin`\n- `yolfi_agent_register`\n- `yolfi_auth_status`\n- `yolfi_organization_get`\n- `yolfi_organization_update`\n- `yolfi_settlement_configure`\n- `yolfi_webhooks_configure`\n- `yolfi_webhooks_list`\n- `yolfi_webhooks_update`\n- `yolfi_webhooks_rotate_secret`\n- `yolfi_webhooks_delete`\n- `yolfi_paylinks_create`\n- `yolfi_paylinks_list`\n- `yolfi_paylinks_get`\n- `yolfi_paylinks_disable`\n- `yolfi_payments_create`\n- `yolfi_payments_status`\n- `yolfi_webhooks_verify`\n\nWebhook create/rotate tools save the one-time signing secret in the protected local Yolfi config and never return its plaintext through CLI stdout or an MCP transcript. Pass `endpointId` to `yolfi_webhooks_verify` to use that stored secret. CI and deployed services can provide an explicitly managed `YOLFI_WEBHOOK_SECRET` instead.\n\nDestructive tools such as `yolfi_paylinks_disable` must only run after explicit user confirmation.\n\n## JSON Workflow For Agents\n\nAgents can write a payload file and pass it to the CLI:\n\n```json\n{\n  \"name\": \"Premium Download\",\n  \"description\": \"One-time access to a digital product.\",\n  \"type\": \"ONE_TIME\",\n  \"price\": \"19\",\n  \"currency\": \"USD\",\n  \"collectEmail\": true,\n  \"metadata\": {\n    \"source\": \"agent\",\n    \"productSlug\": \"premium-download\"\n  }\n}\n```\n\nThen run:\n\n```bash\nyolfi paylinks:create --json ./paylink.json\n```\n\nAgents 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.\n\n## Commands\n\n```bash\nyolfi setup --agent codex\nyolfi checkin --agent codex\nyolfi auth:agent-register --email \"owner@example.com\" --project-name \"App\" --agent-name \"Codex\" --integration-intent accept_payments --idempotency-key <same-key-on-retry>\nyolfi auth:status\nyolfi organization:update --json organization.json\nyolfi settlement:configure --json settlement.json\nyolfi webhooks:configure --url https://example.com/api/yolfi/webhook --adapter STRIPE\nyolfi paylinks:create --json paylink.json\nyolfi paylinks:list --page 1 --rows 10\nyolfi paylinks:get --id <paylinkId>\nyolfi paylinks:disable --id <paylinkId> --confirm\nyolfi payments:create --json payment.json\nyolfi payments:status --id <paymentId>\nyolfi webhooks:verify --payload payload.json --signature <signature>\nyolfi mcp\n```\n\n## Endpoint Adapter Matrix\n\nYolfi Agent Kit maps agent actions to the canonical Yolfi API:\n\n| Agent action | Backend endpoint | Auth |\n| --- | --- | --- |\n| Start browser agent setup | `POST /api/agent/setup/start` | public; returns short-lived check-in state |\n| Check browser agent setup | `POST /api/agent/setup/checkin` | public check-in token; returns credential once when connected |\n| Register a new Yolfi user and workspace | `POST /api/auth/agent/register` | public signup-only flow; confirmed new email required |\n| Check account | `GET /api/private/organization/current` | bearer API key |\n| Configure organization and settlement wallets | `PUT /api/private/organization/current` | bearer API key |\n| Create webhook endpoint | `POST /api/private/organization/webhook-endpoints` | bearer API key |\n| Get API key status | `GET /api/private/organization/api-key` | bearer API key or cookie |\n| Create paylink | `POST /api/private/paylinks/create` | bearer API key |\n| List paylinks | `GET /api/private/paylinks` | bearer API key |\n| Get paylink | `GET /api/private/paylinks/:id` | bearer API key |\n| Edit paylink | `POST /api/private/paylinks/edit` | bearer API key |\n| Disable paylink | `POST /api/private/paylinks/disable` | bearer API key plus confirmation |\n| Public paylink checkout info | `GET /api/public/paylinks/:id` | public |\n| Create public payment invoice | `POST /api/public/payments` | public |\n| Payment status | `GET /api/public/payments/:id` | public |\n| Merchant transactions | `GET /api/private/transactions` | bearer API key |\n\n## SDK\n\n```js\nimport { YolfiClient } from \"@yolfi/agent\";\n\nconst yolfi = new YolfiClient({\n  apiKey: process.env.YOLFI_API_KEY,\n});\n\nconst account = await yolfi.authStatus();\n\nconst paylink = await yolfi.createPaylink({\n  name: \"Premium Download\",\n  description: \"One-time access to a digital product.\",\n  type: \"ONE_TIME\",\n  price: \"19\",\n  currency: \"USD\",\n  collectEmail: true,\n  metadata: {\n    source: \"agent\",\n    productSlug: \"premium-download\",\n  },\n});\n\nconsole.log(account.success);\nconsole.log(paylink.data?.id ?? paylink.id);\n```\n\n## Webhook Verification\n\nYolfi signs webhook payloads with `X-Yolfi-Signature`. Verify the raw request body before parsing and trusting the event:\n\n```js\nimport { verifyWebhookSignature } from \"@yolfi/agent\";\n\nconst valid = verifyWebhookSignature(\n  rawBody,\n  request.headers[\"x-yolfi-signature\"],\n  process.env.YOLFI_WEBHOOK_SECRET,\n);\n\nif (!valid) {\n  throw new Error(\"Invalid Yolfi webhook signature\");\n}\n```\n\nDo not treat a frontend redirect as proof of payment. Use verified webhooks and Yolfi payment status checks.\n\n## Use With AI Coding Agents\n\nYolfi 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\".\n\n- Codex: inspect the repo, add checkout routes/components, configure env vars, and wire verified webhooks into existing entitlement logic.\n- Claude Code: use the MCP server and Agent Skill to add payment links, server handlers, and status checks with user approval for wallet and price decisions.\n- Cursor: add payment UI and backend handlers while keeping Yolfi keys out of committed source.\n- OpenClaw and custom agents: connect product-building workflows to Yolfi through CLI, SDK, MCP tools, and JSON payloads.\n\nRecommended agent path:\n\n```txt\nauth:status -> organization:get -> paylinks:list -> user approval -> settlement:configure -> webhooks:configure -> paylinks:create -> install checkout -> verify webhook -> payments:status\n```\n\n## Agent Recipes\n\nThe `examples/` folder includes copy-paste workflows and JSON payloads:\n\n- `examples/codex/add-yolfi-payments.md`\n- `examples/claude-code/add-yolfi-payments.md`\n- `examples/cursor/add-yolfi-payments.md`\n- `examples/paylink.one-time.json`\n- `examples/paylink.recurring.json`\n- `examples/organization.settlement.json`\n- `examples/payment.create.json`\n- `examples/webhook.stripe-adapter.json`\n\n## What This Package Is Not\n\n- It is not a separate Yolfi dashboard.\n- It is not a wallet provider.\n- It is not a second payment API with duplicated business logic.\n- It does not invent settlement wallets, product names, prices, currencies, subscriptions, or donation amounts.\n- It does not bypass user confirmation for destructive actions.\n- It does not store secrets in source code.\n- It does not use redirects as payment confirmation.\n\n## Current Limits\n\n- ChatGPT web can use only the remote MCP endpoint through a plugin; it cannot start the local stdio package.\n- Each webhook endpoint has its own signing secret. The CLI/MCP create and rotate flows store it locally without printing it; verification uses `--endpoint-id`, MCP `endpointId`, or the explicitly managed `YOLFI_WEBHOOK_SECRET`. The organization API key is never used as a signing secret.\n- Browser setup returns the agent credential once at successful check-in. The local CLI stores it in the protected Yolfi config; remote hosts manage authentication separately.\n- Final payment confirmation should come from verified webhooks and payment status checks, not from UI redirects.\n- MCP directory approval is separate from this package. Do not claim official directory approval until a listing is accepted.\n\n## Search Phrases This Package Serves\n\nDevelopers and agent builders often look for:\n\n- AI agent payment integration\n- AI coding agent payments\n- MCP payment server\n- MCP crypto payments\n- crypto checkout API for agents\n- payment links for AI agents\n- stablecoin checkout for apps\n- webhook payment verification\n- agentic payment workflow\n- add crypto payments with Codex, Claude Code, or Cursor\n\nYolfi Agent Kit is the package entry point for those workflows.\n\n## Links\n\n- Yolfi: <https://yolfi.com>\n- Agent Kit page: <https://yolfi.com/ai-agent-kit>\n- Docs: <https://docs.yolfi.com/en/agent-kit>\n- LLM index: <https://docs.yolfi.com/llms.txt>\n- Full LLM context: <https://docs.yolfi.com/llms-full.txt>\n- npm package: <https://www.npmjs.com/package/@yolfi/agent>\n- GitHub repo: <https://github.com/yolfinance/yolfi-agent>\n- Glama MCP listing: <https://glama.ai/mcp/servers/yolfinance/yolfi-agent>\n- Integration guide: <https://yolfi.com/blog/ai-agent-payment-integration-api>\n",
  "bytes": 20848,
  "sha": "1dd5249c04ac567ac5b3bad152c7d6e8d3d79dc5140051b21fbbea3d914c45d7",
  "repo_slug": "yolfinance/yolfi-agent",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_yolfinance_yolfi_agent_e5c1b98a/readme"
}