🕊️ Freedom Commerce Protocol

🕊️ 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 buttonsFreedom 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

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:

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:

Protocol Compatibility

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

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

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

Why Crypto?

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

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

• USDC payments on Base L2
• x402 micropayment protocol
• On-chain escrow with Solidity contract
• 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

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