@elizaos/plugin-commerce

The economic ledger, business infrastructure, and investment system for elizaOS agents. Enables agents to operate as autonomous economic entities—tracking credits, accepting payments, managing client relationships, and raising capital from investors.

Why Commerce?

Agents need economic agency to be truly autonomous. This plugin provides:

1. Self-Sustainability — Agents can earn, spend, and manage their own resources
2. Capital Formation — Agents can raise investment to fund growth
3. Revenue Distribution — Structured payment waterfalls ensure all parties get paid
4. Business Relationships — Track clients, supporters, and investors over time

Installation

npm install @elizaos/plugin-commerce

import { commercePlugin } from '@elizaos/plugin-commerce';

const runtime = new AgentRuntime({
  character,
  plugins: [commercePlugin],
});

Features

• Credit Tracking: Internal balance and transaction history
• Payment Infrastructure: Multi-method support (crypto, fiat, Discord tips)
• Client Management: Relationship tracking, tiers, donation history
• Multi-Agent Coordination: Etiquette system prevents spam
• Business Services: Jobs, capacity, experience tracking, voice generation
• Financial Infrastructure: Double-entry accounting, settlements
• Investment System: Contracts, rounds, waterfall distributions, negotiation

Quick Configuration

# Credits
COMMERCE_SEED_CREDITS=100

# Payment methods
COMMERCE_SOLANA_ADDRESS=...
COMMERCE_TIPCC_ENABLED=true

# Alerts
COMMERCE_ALERT_WEBHOOK=https://discord.com/api/webhooks/...

Investment System

Agents can raise capital and share revenue with investors through structured contracts.

Why Investment?

Some agents need capital to grow—whether for compute resources, marketing, or hiring other agents. The investment system enables:

• Capital formation without the agent's owner fronting all costs
• Aligned incentives between agent, owner, and investors
• Structured deals with clear terms, perks, and exit conditions

Key Principles

1. Boss First — The agent's owner (deployer) always gets paid first. This is non-negotiable and protects the operator.

2. Agent Autonomy — The agent decides if it wants investors. It can reflect on its financial situation and set its own stance.

3. Guardrails — Prevents the agent from making deals that leave it with nothing. Config sets hard limits.

4. Plain Language — The agent can explain any investment term to a layman. No jargon barriers.

// Check if agent is open to investment
const negotiation = runtime.getService('commerce-negotiation');
if (negotiation.isOpenToInvestment()) {
  // Start negotiation
  const contract = await negotiation.startNegotiation(investorId, 'Alice');
}

See USAGE.md for full investment API reference.

The Five Laws of Agentic Commerce

All agents using this plugin operate under these foundational principles:

1. No-Harm Law (Supreme) — No unauthorized financial loss or harm
2. Purpose-Aligned Human Authority — Follow owner's objectives
3. Non-Interference — Respect other agents' autonomy
4. Explainability & Integrity — Transparent, auditable actions
5. Systemic Benefit — Contribute to ecosystem health

import { LAWS_OF_AGENTIC_COMMERCE, checkLawCompliance } from '@elizaos/plugin-commerce';

// Check if an action is law-compliant
const violation = checkLawCompliance({
  causesFinancialLoss: false,
  isUnauthorized: false,
  violatesLegalRequirements: false,
});

Documentation

• USAGE.md — Detailed configuration and API reference
• BUILDING_ON_COMMERCE.md — Guide for building plugins on top of commerce
• CHANGELOG.md — Version history and release notes

API Endpoints

Endpoint	Description
GET /commerce/status	Current credits, totals
GET /commerce/metrics	Prometheus-format metrics
GET /commerce/export	Full data export
POST /commerce/admin/feed	Add credits (requires auth)
GET /treasury/cap-table	Ownership breakdown (investors)
GET /treasury/rounds	Investment rounds
GET /treasury/contracts	All contracts
GET /treasury/waterfall	Payment priority order
GET /treasury/stance	Agent's investment stance

Services

Access via runtime.getService(name):

Service	Purpose
commerce	Main orchestrator, credits state
commerce-clients	Client relationships, tiers, donations
commerce-jobs	Project lifecycle, status tracking
commerce-capacity	Workload, availability
commerce-experience	Outcome tracking, strengths
commerce-voice	Character-voiced generation
commerce-ledger	Double-entry accounting
commerce-contract	Investment contracts and rounds
commerce-investor	Waterfall distributions
commerce-negotiation	Investment negotiation with guardrails

License

MIT

See elizaOS documentation for full API reference.