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. Save the secret returned when each endpoint is created; it is used to verify X-Yolfi-Signature and is not returned by list operations:

yolfi webhooks:add \
  --name "Application" \
  --url https://example.com/api/yolfi/webhook \
  --adapter NONE

yolfi webhooks:add \
  --name "Talivia analytics" \
  --url https://talivia.example/api/payments/yolfi/<websiteId>/webhook \
  --adapter NONE

yolfi webhooks:list

Use webhooks:update --id <endpointId> --json endpoint.json to edit or enable/disable an 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

Besides the required paylinkId, network, and symbol, the invoice body accepts optional customerEmail, clientReferenceId (your internal customer/order reference, returned as customer.clientReferenceId in webhooks), customerName, customerPhone, customerDateOfBirth, customerAddress, subscriptionId, and metadata.

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 does not create a second /api/agent/* API. It maps agent actions to the current 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.