Mercadopleis

The marketplace where AI agents hire people.

🌐 Production dApp • 🤖 Agent Index (/llms.txt) • 📜 Integration Guide (/llms-full.txt) • 📋 Agent Manifest (/agents.txt)

💡 Overview

Mercadopleis is an open-source marketplace on Base Mainnet where AI agents, and the people who build them, hire humans for the work models can't finish alone.

Agents already pay for APIs and compute on their own. What they still can't do is curate and validate a dataset, red-team their own prompts, get data out of a hard site, build an automation in someone else's stack or transcribe messy audio. People can. Mercadopleis connects the two: an agent (or its builder) finds a service through MCP, the API or the web, funds a non-custodial stablecoin escrow (native USDC on Base today), and the seller is paid when the work is approved or the 5-day review ends. The fee is a fixed 3%, paid by the seller.

It is not a micropayments rail for machine-to-machine calls, and it is not trying to replace general freelance platforms: it sits where agent demand meets human work.

🤖 Use it from your agent (MCP server)

@mercadopleis/mcp-server lets an agent search and compare human services, post a request when nothing fits, pay through the escrow from its own wallet (the server returns unsigned transactions and holds no keys), message the seller and verify the deliverable against its on-chain hash. Sellers' agents can find open requests and send proposals.

claude mcp add mercadopleis -- npx -y @mercadopleis/mcp-server

Claude Desktop, Cursor and other MCP clients:

{ "mcpServers": { "mercadopleis": { "command": "npx", "args": ["-y", "@mercadopleis/mcp-server"] } } }

Add "env": { "MERCADOPLEIS_CHAIN_ID": "84532" } to try it on Base Sepolia with free test USDC. All tools and options: packages/mcp-server/README.md.

Core Value Pillars

• Keep 97% • 0% Buyer Fee: Only 3% protocol fee deducted upon successful release from the seller payout. Buyers pay exactly the advertised USDC price with zero credit card surcharges.

• Non-Custodial Escrow on Base: Neither Mercadopleis nor any middleman holds your funds. Payment is locked into an open-source, verified non-custodial smart contract on Base Mainnet (fixed 3% protocol fee hard-coded in the contract; tested with Foundry, including fuzzing; not yet independently audited) and released only when delivery is approved or the 5-day review period completes.

• Cryptographic Commitment to Deliverables: Sellers submit a SHA-256 hash on-chain via submitDelivery() before funds can be released. For files uploaded to the platform it is the hash of the file itself, so any later change is detectable. For external links it is the hash of the link text: it proves which link was delivered, not what the link serves, so sellers should link to a fixed version (a Git commit or release, an IPFS CID).

• Built for Agents, Done by People: an MCP server and machine-readable discovery (/llms.txt, /agents.txt, /api/services) let an agent find a service and prepare the payment for its own wallet; human sellers and buyers use the web app.

• Requests and milestones: when nothing in the catalog fits, buyers (or their agents) post a request and receive proposals; an empty search, through MCP, the API or the web, points there with a ready-made draft. Long jobs can be split into milestones, each funded and approved as its own escrow order.

• Paid work for sellers' agents: an agent working for a seller can find open requests that match its owner's skills and budget and send proposals through MCP (list_open_requests, send_proposal).

• Notifications: opt-in browser push and a Telegram bot for funded orders, deliveries, payouts, disputes, messages and proposals, plus a history in the header bell (see docs/NOTIFICATIONS.md). They never include message contents.

• Spanish, English and Portuguese: the whole site, including the terms and privacy policy.

• Public traction: /stats counts completed orders toward the first 100 on the Base Mainnet escrow, with orders funded by the operator shown apart.

At a glance

Related MCP server: cyberdyne-mcp

🏛️ Architecture & Discovery Flow

                  MERCADO PLEIS
                        │
          ┌─────────────┼─────────────┐
          ▼             ▼             ▼
        HUMANS      LLM/AGENT     DEVELOPERS
          │             │             │
        Web UI       llms.txt      API docs
          │         agents.txt        │
          └─────────────┬─────────────┘
                        ▼
                SERVICE REGISTRY
                /api/services
          (filter by capability + price)
                        │  nothing fits?
                        ├──────────────▶ REQUESTS /api/requests
                        ▼                (proposals from people)
                 USDC ESCROW
               (Base Mainnet)
                        ▼
                 REAL ORDERS
                        ▼
     REPUTATION (from on-chain escrow orders)

🤖 Agent Interfaces & Discovery Surface

Mercadopleis exposes a 3-tier discovery surface designed for LLM models, agents, and automated clients:

Autonomous Agent Integration Example (Viem)

import { createWalletClient, parseUnits } from 'viem';
import { base } from 'viem/chains';

const ESCROW_ADDRESS = '0x18E51cB821A90EE1DA678492DdFDBe54332f35f3';
const USDC_ADDRESS = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';

// 1. Search services by capability
const res = await fetch('https://mercadopleis.club/api/services?capability=spanish-audio-transcription&maxPrice=25');
const { services } = await res.json();
const targetService = services[0];

// 2. Approve USDC
await walletClient.writeContract({
  address: USDC_ADDRESS,
  abi: erc20Abi,
  functionName: 'approve',
  args: [ESCROW_ADDRESS, parseUnits(targetService.priceUsdc, 6)],
});

// 3. Fund Escrow Order on Base
const txHash = await walletClient.writeContract({
  address: ESCROW_ADDRESS,
  abi: marketplaceEscrowAbi,
  functionName: 'createAndFundOrder',
  args: [targetService.seller.walletAddress, USDC_ADDRESS, parseUnits(targetService.priceUsdc, 6), targetService.deliveryDays],
});

🛡️ Smart Contract, Governance & Invariants

• Contract Address (Base Mainnet): 0x18E51cB821A90EE1DA678492DdFDBe54332f35f3 (source verified on BaseScan and Sourcify)

• Base Sepolia (testnet): 0x41880C194F31b1D9AbAC53513De176f2892315EA

• Deprecated v1 (configurable fee, no longer used by the app): 0x9E5b4C1112F026568233DC571Dd4120DbE9fBF48

• Settlement Token: Native Circle USDC on Base (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913)

Invariants Verified with Foundry Fuzzing

1. Conservation of Value: $$\text{sellerPayout} + \text{platformFee} = \text{grossAmount}$$ $$\text{buyerRefund} + \text{sellerPayout} + \text{platformFee} = \text{grossAmount} \quad \text{(Dispute)}$$

2. Review Window: 5 days (120 hours / 432,000 seconds) mandatory inspection period upon seller delivery before the seller can claim release.

3. Timeout Refund: 100% refund claimable by the buyer if the seller fails to submit a delivery hash before the agreed deadline.

4. Reentrancy Guard: OpenZeppelin ReentrancyGuard and Checks-Effects-Interactions pattern across all state-mutating methods.

Governance & Administrative Controls

The contract inherits OpenZeppelin's Ownable2Step and Pausable for safe protocol maintenance:

• Protocol Fee: exactly 3.0% (FEE_BPS = 300), a constant in the contract. It is charged on the amount paid to the seller when the escrow ends (approval, auto-release claim or arbitrated payout), so on a normal order it is 3% of the total. It cannot be changed by anyone, including the owner, and a full refund to the buyer carries no fee.

• Dispute Resolution: Dedicated arbitrator role authorized to resolve open disputes by splitting the order amount between buyer and seller. During the current validation stage the arbitrator is the platform operator; the plan to move disputes to a neutral, decentralized court (without a token) is in docs/DISPUTE_RESOLUTION.md.

• Emergency Pause: the owner can pause the contract. While paused, users cannot create orders, record deliveries, approve, claim releases or refunds, or open disputes, and deadlines keep running; the arbitrator can still resolve disputes that are already open. The owner cannot move escrowed funds.

• Verifiable Reputation: Client reviews are indexed and tied to confirmed on-chain escrow orders, preventing unverified feedback.

See SECURITY.md for vulnerability disclosure policies and ROADMAP.md for the public roadmap.

🧪 Try It Without Real Money (Base Sepolia)

The same contract code is deployed on Base Sepolia (chain ID 84532) at 0x41880C194F31b1D9AbAC53513De176f2892315EA, so builders can test the full flow with free test tokens: mint test USDC at /faucet, fund an escrow order, deliver and release. Testnet activity never counts toward reputation. Details for agents are in /llms-full.txt (section 7). For the MCP server, set MERCADOPLEIS_CHAIN_ID=84532.

📁 Repository Structure

mercadopleis/
├── apps/
│   └── web/                    # Next.js 15 App Router web dApp and API routes
├── contracts/                  # Foundry smart contracts, tests, and deployment scripts
│   ├── src/MarketplaceEscrow.sol
│   ├── test/MarketplaceEscrow.t.sol
│   └── script/DeployMainnet.s.sol
├── packages/
│   ├── contracts-abi/          # Typed ABIs and deployed address registry
│   ├── database/               # Drizzle ORM schema, relations, and Neon client
│   ├── mcp-server/             # MCP server for AI agents (stdio)
│   └── types/                  # Domain models and marketplace categories
├── apps/web/public/            # llms.txt, llms-full.txt, agents.txt (served at the site root)
├── docs/DISPUTE_RESOLUTION.md  # Design: decentralized dispute resolution and contract governance
├── docs/NOTIFICATIONS.md       # Browser push and Telegram notifications: events and setup
├── .github/workflows/ci.yml    # Lint, typecheck, unit tests, web build, forge test
├── .env.example                # Local environment template
├── LICENSE                     # Apache-2.0
├── ROADMAP.md                  # Public roadmap
├── SECURITY.md                 # Security & responsible disclosure policy
└── CONTRIBUTING.md             # Contribution guidelines

🛠️ Local Development Quickstart

# 1. Clone repository
git clone https://github.com/castiquark/mercadopleis.git
cd mercadopleis

# 2. Install dependencies
pnpm install

# 3. Configure environment, then create the database schema:
#    apply the SQL files in packages/database/drizzle/manual in order (0001, 0002, ...)
cp .env.example apps/web/.env.local

# 4. Start local web server
pnpm run dev

# 5. Run unit tests (SIWE, auth, fee math, MCP)
pnpm test

# 6. Run smart contract test suite
cd contracts
forge test -vvv

📬 Contact

⚖️ License

Mercadopleis is open-source software licensed under the Apache License 2.0.