Yolfi代理工具包

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

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.

Use a stable customer or application-user id for clientReferenceId when webhook handlers must resolve subscription ownership. Native (NONE) payloads expose it as data.customer.clientReferenceId; Stripe-compatible Checkout Session payloads use data.object.client_reference_id, Stripe-compatible Invoice and Subscription payloads use data.object.metadata.client_reference_id, and Lemon Squeezy-compatible payloads use meta.custom_data.client_reference_id.

Check payment status:

yolfi payments:status --id <paymentId>

Every CLI command prints JSON so agents can parse results without scraping terminal text.

Endpoint Adapter Matrix

Yolfi Agent Kit maps agent actions to the canonical Yolfi API:

SDK

import { YolfiClient } from "@yolfi/agent";

const yolfi = new YolfiClient({
  apiKey: process.env.YOLFI_API_KEY,
});

const account = await yolfi.authStatus();

const paylink = await yolfi.createPaylink({
  name: "Premium Download",
  description: "One-time access to a digital product.",
  type: "ONE_TIME",
  price: "19",
  currency: "USD",
  collectEmail: true,
  metadata: {
    source: "agent",
    productSlug: "premium-download",
  },
});

console.log(account.success);
console.log(paylink.data?.id ?? paylink.id);

JSON Workflow For Agents

Agents can write a payload file and pass it to the CLI:

{
  "name": "Premium Download",
  "description": "One-time access to a digital product.",
  "type": "ONE_TIME",
  "price": "19",
  "currency": "USD",
  "collectEmail": true,
  "metadata": {
    "source": "agent",
    "productSlug": "premium-download"
  }
}

Then run:

yolfi paylinks:create --json ./paylink.json

Agents 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.

What This Package Is Not

• It is not a separate Yolfi dashboard.
• It is not a wallet provider.
• It is not a second payment API with duplicated business logic.
• It does not invent settlement wallets, product names, prices, currencies, subscriptions, or donation amounts.
• It does not bypass user confirmation for destructive actions.
• It does not store secrets in source code.
• It does not use redirects as payment confirmation.

Search Phrases This Package Serves

Developers and agent builders often look for:

• AI agent payment integration
• AI coding agent payments
• MCP payment server
• MCP crypto payments
• crypto checkout API for agents
• payment links for AI agents
• stablecoin checkout for apps
• webhook payment verification
• agentic payment workflow
• add crypto payments with Codex, Claude Code, or Cursor

Yolfi Agent Kit is the package entry point for those workflows.