# 🕊️ 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:**
```json
{
  "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](https://github.com/modelcontextprotocol). Agents use these to understand what purchase actions are available.

```json
{
  "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:**
```json
{
  "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
```

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

---

## Quick Start

```bash
# 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)

```bash
# 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.

```bash
# 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 🕊️](https://github.com/BARRYPMARSHALL) 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

```bash
# 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:
```bash
# 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)

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

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

### Docker

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

### Manual

```bash
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](https://github.com/punkpeye/awesome-mcp-servers) directory (PR #5570 pending).

### Claude Desktop

Add to `claude_desktop_config.json`:

```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
```