Mercadopleis

Mercadopleis

---

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

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.

---

🏛️ Architecture & Discovery Flow

                  MERCADO PLEIS
                        │
          ┌─────────────┼─────────────┐
          ▼             ▼             ▼
       HUMANOS      LLM/AGENT     DEVELOPERS
          │             │             │
        Web UI       llms.txt      API docs
          │         agents.txt        │
          └─────────────┬─────────────┘
                        ▼
                SERVICE REGISTRY
                /api/services
          (filter by capability + price)
                        ▼
                 USDC ESCROW
               (Base Mainnet)
                        ▼
                 REAL ORDERS
                        ▼
              REPUTATION ON-CHAIN

---

🤖 Agent Interfaces & Discovery Surface

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

File / Endpoint	Purpose	Audience
/llms.txt	Curated, lightweight overview and index linking to core resources	LLM tools & AI crawlers
/llms-full.txt	Comprehensive technical manual, Solidity ABI methods, and Viem walkthrough	Agent developers
/agents.txt	Machine-readable manifest of identity, network, and capabilities	Autonomous agents
/api/services	REST API supporting capability, minPrice, maxPrice, maxDeliveryDays	Programmatic consumers
@mercadopleis/mcp-server	MCP server: search, compare, prepare unsigned escrow orders and buyer follow-ups (approve, dispute, timeout refund), sign in with the agent's wallet, message the seller, download and verify deliverables. Non-custodial, holds no keys. npx -y @mercadopleis/mcp-server	MCP clients (Claude Code, Claude Desktop, Cursor)

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 auto-release can occur.
3. Timeout Refund Guarantee: 100% refund guarantee for buyers 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 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, guaranteeing authentic 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
├── .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
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

Purpose	Address
General, partnerships, builders	hello@mercadopleis.club
Order, payment or dispute help	support@mercadopleis.club
Security vulnerability reports	security@mercadopleis.club (see SECURITY.md)

---

⚖️ License

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