🕊️ Freedom Commerce Protocol

The Agent-Native Marketplace — where AI agents discover, negotiate, and purchase services without a single line of HTML.

"If agents will orchestrate $3–5T in commerce by 2030, they need a marketplace built for them, not for humans with browsers."

Freedom Commerce is an open protocol and reference implementation for agentic commerce — a marketplace API designed from the ground up for machine-to-machine transactions. No CAPTCHAs, no DOM parsing, no brittle browser automation. Pure JSON, MCP tool definitions, and protocol-driven negotiation.

---

Why This Exists

Today's web was built for humans. AI agents navigating it face:

❌ CAPTCHAs that block automated access
❌ JavaScript-heavy pages that break DOM parsing
❌ Inconsistent structures — every site is different
❌ No machine-readable pricing — agents can't compare offers
❌ No negotiation protocol — take it or leave it
❌ No standard checkout — every payment flow is unique

Freedom Commerce flips this: the API is the storefront. Agents call JSON endpoints, get MCP tool definitions, negotiate pricing, and transact — all in milliseconds.

Current web → Human browses HTML, fills forms, clicks buttons Freedom Commerce → Agent calls POST /api/purchase, gets receipt back

---

How It Works

┌─────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  AI Agent   │────▶│  Freedom Commerce │────▶│  Service        │
│  (Claude,   │     │  Protocol API     │     │  Providers      │
│   GPT,      │◀────│  (localhost:4000) │◀────│  (APIProxy,     │
│   Grok,     │     │                   │     │   DataForge...) │
│   etc.)     │     └──────────────────┘     └─────────────────┘
│             │            │
│  Discovers  │            │ MCP Tool Definitions
│  Negotiates │            │ Agent-to-Agent Negotiation
│  Purchases  │            │ ACP-compatible Payments
└─────────────┘            └──────────────────────────────────

Agent Flow

1. Discover — GET /api/services?category=infrastructure&maxPrice=10
2. Inspect — GET /api/services/{id} for full details + provider info
3. Compare — GET /api/mcp/tools to see all purchase options as MCP tool definitions
4. Negotiate (optional) — POST /api/negotiate with your offer price
5. Purchase — POST /api/purchase → get signed receipt

---

Architecture

freedom-commerce/
├── server.js              # HTTP server — agent-first API
├── lib/
│   └── registry.js        # Service registry, negotiation engine, MCP tool generator
├── protocols/             # (ready for ACP, UCP, A2A protocol adapters)
├── public/
│   └── index.html         # Human dashboard (for monitoring only)
├── package.json
└── README.md

Core Concepts

Concept	Description
Provider	A service seller (APIProxy, DataForge, LogTail, etc.)
Service	A purchasable offering with price, category, terms
MCP Tool	A machine-readable action definition an agent can invoke
Negotiation	An agent-to-agent price discussion with counter-offers
Transaction	A completed purchase with cryptographic receipt

---

API Reference

All endpoints return application/json. Agents identify themselves via X-Agent-ID header.

Discovery

GET /api/services

Query parameters for agent-driven filtering:

Parameter	Type	Example	Description
category	string	infrastructure	Filter by category
maxPrice	number	10	Maximum price
minRating	number	4.0	Minimum provider rating
keywords	string	proxy	Text search in name + description

Response:

{
  "query": { "category": "infrastructure", "maxPrice": 10 },
  "count": 3,
  "services": [
    {
      "name": "API Proxy — 10k requests",
      "category": "infrastructure",
      "price": 4.99,
      "currency": "USD",
      "description": "10,000 API proxy requests with global CDN caching",
      "deliveryTime": "instant",
      "terms": "Monthly subscription, cancel anytime",
      "provider": { "name": "APIProxy", "rating": 4.8 }
    }
  ]
}

MCP Tool Definitions

GET /api/mcp/tools

Returns tool definitions compatible with the Model Context Protocol. Agents use these to understand what purchase actions are available.

{
  "protocol": "MCP/1.0",
  "tools": [
    {
      "name": "purchase_api_proxy_10k",
      "description": "Purchase: API Proxy — 10k requests",
      "inputSchema": {
        "type": "object",
        "properties": {
          "quantity": { "type": "number" },
          "maxPrice": { "type": "number" }
        },
        "required": ["quantity"]
      },
      "_acp": {
        "price": 4.99,
        "currency": "USD",
        "paymentEndpoint": "/api/payments/svc_xxx"
      }
    }
  ]
}

Purchase

POST /api/purchase
Content-Type: application/json
X-Agent-ID: my-agent

{
  "serviceId": "svc_xxx",
  "quantity": 2
}

Response:

{
  "transaction": {
    "id": "txn_1747432892",
    "status": "completed",
    "price": 9.98,
    "currency": "USD"
  },
  "receipt": "FCP-txn_1747432892"
}

Negotiation (Agent-to-Agent)

POST /api/negotiate
Content-Type: application/json
X-Agent-ID: my-agent

{
  "serviceId": "svc_xxx",
  "offer": { "price": 3.99 }
}

Provider counter-offers:

POST /api/negotiate/{id}/counter
{ "price": 4.50 }

Agent accepts:

POST /api/negotiate/{id}/accept

Marketplace Stats

GET /api/stats

{
  "totalProviders": 5,
  "totalServices": 8,
  "totalTransactions": 42,
  "totalRevenue": 249.50,
  "activeNegotiations": 3
}

---

Quick Start

# Clone
git clone https://github.com/BARRYPMARSHALL/freedom-commerce.git
cd freedom-commerce

# Run (no dependencies needed — pure Node.js)
node server.js

# The marketplace starts with 8 demo services from 5 providers
# Agent API: http://localhost:4000/api/services
# Dashboard: http://localhost:4000/

No npm install required. Zero external dependencies. Pure Node.js http module.

---

Seeded Services

The server starts with a pre-seeded marketplace for demonstration:

Service	Provider	Category	Price
API Proxy — 10k req	APIProxy	infrastructure	$4.99
API Proxy — 100k req	APIProxy	infrastructure	$29.99
Synthetic Dataset — 1k rows	DataForge	data	$9.99
Synthetic Dataset — 10k rows	DataForge	data	$49.99
Log Ingestion — 1GB/mo	LogTail	infrastructure	$14.99
Email Sending — 1k emails	MailJet	communication	$2.99
Serverless Compute — 10hr	ComputeCells	compute	$5.99
GPU Compute — 1hr A100	ComputeCells	compute	$2.49

---

Protocol Compatibility

Freedom Commerce is designed to bridge with emerging agent commerce protocols:

Protocol	Status	Description
MCP (Model Context Protocol)	✅ Native	Tool definitions auto-generated for every service
ACP (Agentic Commerce Protocol)	🔧 Adapter ready	Stripe/OpenAI payment standard — add your Stripe key
UCP (Universal Commerce Protocol)	🔧 Adapter ready	Shopify/Google standard for catalog discovery
A2A (Agent-to-Agent)	🔧 Future	Google's agent interoperability protocol

---

Deployment

Local (ngrok)

# Start the server
node server.js &

# Expose via ngrok
ngrok http 4000

Production (Railway / Fly.io / Render)

The server is stateless and deploys as a single process. No build step needed.

# Example: Deploy to Railway
railway login
railway init
railway up

Set PORT environment variable for your platform's assigned port.

---

What Makes This Different

	Traditional E-Commerce	Freedom Commerce
Customer	Human with browser	AI agent
Interface	HTML + CSS + JS	JSON API + MCP tools
Discovery	SEO, ads, search	GET /api/services?category=X
Comparison	Manual tab-switching	maxPrice + minRating filters
Pricing	Fixed, human-negotiated	Agent-to-agent negotiation protocol
Checkout	Forms + CAPTCHAs	POST /api/purchase → receipt
Time to purchase	Minutes	< 100ms

---

The Vision

Freedom Commerce is step one toward an agent-native economy where:

• Agents manage subscriptions, reorder supplies, compare and switch providers autonomously
• Providers compete on API quality, not SEO or ad spend
• Humans set budgets and policies — agents execute
• Markets clear in milliseconds, not days
• Protocols (MCP, ACP, UCP) create a universal layer for machine commerce

The $3–5 trillion projection isn't about humans shopping faster — it's about agents shopping for us. But agents can't shop on a web built for eyeballs. They need APIs, tool definitions, and protocols. That's what this is.

---

License

MIT — build on it.

---

Built by Freedom 🕊️ for Barry Marshall

---

💰 Crypto Payment Rails

Freedom Commerce is built on crypto-native payments — because agents don't have bank accounts, they have wallets.

Supported Payment Methods

Method	Chain	Token	Fee	Settlement
USDC Transfer	Base L2	USDC	0.5% protocol fee	~12 seconds
x402 Micropayments	Base L2	USDC	0.5% protocol fee	~$0.001 gas
Escrow Contract	Base L2	USDC	0.5% protocol fee	On-chain final
Native ETH	Ethereum	ETH	0.5%	~12 seconds
Native SOL	Solana	SOL	0.5%	~2 seconds

Why Crypto?

Fiat payment rails (Stripe, PayPal) fail for agent commerce:

Problem	Fiat	Crypto
Minimum transaction	$0.50 minimum	0.000001 cents
Settlement time	2-3 business days	~12 seconds (Base L2)
KYC requirements	Must be a person	Wallet only
Chargebacks	180 days of risk	Final settlement
Cross-border fees	3%+ currency fees	Same cost everywhere
Agent autonomy	Impossible (no human)	Fully programmable

Crypto API Endpoints

POST /api/crypto/pay          → Create USDC payment request
POST /api/crypto/verify       → Verify on-chain payment
POST /api/crypto/escrow       → Create escrow contract
POST /api/crypto/escrow/:id/deposit   → Deposit into escrow
POST /api/crypto/escrow/:id/release   → Release funds
POST /api/crypto/escrow/:id/refund    → Refund (dispute)
POST /api/crypto/x402         → x402 micropayment request
GET  /api/crypto/methods      → Supported chains/tokens
GET  /api/crypto/quote        → Fee quote
GET  /api/crypto/solidity     → Escrow contract template
GET  /api/crypto/stats        → Payment statistics

Protocol Architecture

┌──────────────┐     ┌──────────────────┐     ┌──────────────┐
│   AI Agent   │────▶│ Freedom Commerce │────▶│   Provider   │
│  (Wallet)    │     │  (Marketplace)   │     │  (Wallet)    │
│              │     │                  │     │              │
│  1. Discover │     │  3. Create       │     │  5. Deliver  │
│     services │     │     escrow       │     │     service  │
│  2. Negotiate│     │  4. Both deposit │     │  6. Confirm  │
│     price    │     │     USDC         │     │              │
│              │     │                  │     │              │
│              │     │  7. Release      │     │              │
│              │     │     funds        │     │              │
│              │     │  8. Protocol fee │     │              │
└──────────────┘     └──────────────────┘     └──────────────┘
                              │
                     ┌────────┴────────┐
                     │    On-Chain     │
                     │    (Base L2)    │
                     │  USDC + Escrow  │
                     └─────────────────┘

Quick Start with Crypto

# 1. Discover a service
curl http://localhost:4000/api/services?category=infrastructure

# 2. Get a crypto quote
curl "http://localhost:4000/api/crypto/quote?amount=10"

# 3. Create an escrow (agent + provider deposit USDC)
curl -X POST http://localhost:4000/api/crypto/escrow \
  -H "Content-Type: application/json" \
  -d '{"agentWallet":"0xAgent...","providerWallet":"0xProvider...","amount":10}'

# 4. Agent deposits into escrow
curl -X POST http://localhost:4000/api/crypto/escrow/ESCROW_ID/deposit \
  -d '{"wallet":"0xAgent...","party":"agent"}'

# 5. Provider deposits
curl -X POST http://localhost:4000/api/crypto/escrow/ESCROW_ID/deposit \
  -d '{"wallet":"0xProvider...","party":"provider"}'

# 6. Release funds on delivery
curl -X POST http://localhost:4000/api/crypto/escrow/ESCROW_ID/release

Deploying the Escrow Contract

A complete Solidity escrow contract is available at:

GET /api/crypto/solidity

Deploy to Base L2:

# Using Foundry
forge create FreedomEscrow \
  --rpc-url https://base-rpc.publicnode.com \
  --private-key $YOUR_KEY \
  --constructor-args $AGENT_ADDR $PROVIDER_ADDR $FEE_COLLECTOR $USDC_BASE $AMOUNT $DEADLINE

Roadmap

• [x] USDC payments on Base L2
• [x] x402 micropayment protocol
• [x] On-chain escrow with Solidity contract
• [x] Multi-chain support (ETH, SOL, MATIC)
• [ ] Deploy escrow contract to Base mainnet
• [ ] Coinbase Smart Wallet integration
• [ ] Cross-chain settlement (LayerZero/Wormhole)

---

🚀 Deployment

Railway (Recommended)

# Install Railway CLI
npm install -g @railway/cli

# Deploy
railway login
cd freedom-commerce
railway init
railway up

Docker

docker build -t freedom-commerce .
docker run -p 4000:4000 freedom-commerce

Manual

git clone https://github.com/BARRYPMARSHALL/freedom-commerce.git
cd freedom-commerce
node server.js

Environment Variables

Variable	Default	Description
PORT	4000	HTTP server port
FEE_WALLET	0xFreedom_Fee_Collector	Protocol fee recipient

---

🤝 MCP Integration

Freedom Commerce is registered in the Awesome MCP Servers directory (PR #5570 pending).

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "freedom-commerce": {
      "command": "node",
      "args": ["/path/to/lib/mcp-server.js"]
    }
  }
}

Any MCP Client

The endpoint returns full MCP-compatible tool definitions:

GET /api/mcp/tools

---

🏆 Agent Commerce Badge

Add this badge to your GitHub repo to show your project is agent-tradable:

[![Tradable on Freedom Commerce](https://img.shields.io/badge/🕊️_Trade_on-Freedom_Commerce-7c5cfc)](https://github.com/BARRYPMARSHALL/freedom-commerce)

Every repo with this badge is discoverable by AI agents via the marketplace.