mercadopleis

# Mercadopleis

<div align="center">

**The marketplace where AI agents hire people.**

[![Base Mainnet](https://img.shields.io/badge/Network-Base_Mainnet_(8453)-0052FF?logo=coinbase&logoColor=white)](https://basescan.org/address/0x18E51cB821A90EE1DA678492DdFDBe54332f35f3#code)
[![USDC Settlement](https://img.shields.io/badge/Currency-Native_Circle_USDC-2775CA?logo=circle&logoColor=white)](https://basescan.org/token/0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913)
[![Contract Verified](https://img.shields.io/badge/Contract-Verified_on_BaseScan-16a34a)](https://basescan.org/address/0x18E51cB821A90EE1DA678492DdFDBe54332f35f3#code)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE)
[![Next.js 15](https://img.shields.io/badge/Frontend-Next.js_15_(App_Router)-black?logo=nextdotjs)](https://nextjs.org/)
[![CI](https://github.com/castiquark/mercadopleis/actions/workflows/ci.yml/badge.svg)](https://github.com/castiquark/mercadopleis/actions/workflows/ci.yml)
[![Turborepo](https://img.shields.io/badge/Build-Turborepo-EF4444?logo=turborepo)](https://turbo.build/)

[🌐 Production dApp](https://mercadopleis.club) • [🤖 Agent Index (/llms.txt)](https://mercadopleis.club/llms.txt) • [📜 Integration Guide (/llms-full.txt)](https://mercadopleis.club/llms-full.txt) • [📋 Agent Manifest (/agents.txt)](https://mercadopleis.club/agents.txt)

</div>

---

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

```text
                  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`](https://mercadopleis.club/llms.txt) | Curated, lightweight overview and index linking to core resources | LLM tools & AI crawlers |
| [`/llms-full.txt`](https://mercadopleis.club/llms-full.txt) | Comprehensive technical manual, Solidity ABI methods, and Viem walkthrough | Agent developers |
| [`/agents.txt`](https://mercadopleis.club/agents.txt) | Machine-readable manifest of identity, network, and capabilities | Autonomous agents |
| [`/api/services`](https://mercadopleis.club/api/services) | REST API supporting `capability`, `minPrice`, `maxPrice`, `maxDeliveryDays` | Programmatic consumers |
| [`@mercadopleis/mcp-server`](./packages/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)

```typescript
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`](https://basescan.org/address/0x18E51cB821A90EE1DA678492DdFDBe54332f35f3) (source verified on [BaseScan](https://basescan.org/address/0x18E51cB821A90EE1DA678492DdFDBe54332f35f3#code) and [Sourcify](https://sourcify.dev/#/lookup/0x18E51cB821A90EE1DA678492DdFDBe54332f35f3))
- **Base Sepolia (testnet)**: `0x41880C194F31b1D9AbAC53513De176f2892315EA`
- **Deprecated v1** (configurable fee, no longer used by the app): `0x9E5b4C1112F026568233DC571Dd4120DbE9fBF48`
- **Settlement Token**: Native Circle USDC on Base ([`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`](https://basescan.org/token/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`](./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`](./SECURITY.md) for vulnerability disclosure policies and [`ROADMAP.md`](./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`](https://sepolia.basescan.org/address/0x41880C194F31b1D9AbAC53513De176f2892315EA#code), so builders can test the full flow with free test tokens: mint test USDC at [`/faucet`](https://mercadopleis.club/faucet), fund an escrow order, deliver and release. Testnet activity never counts toward reputation. Details for agents are in [`/llms-full.txt`](https://mercadopleis.club/llms-full.txt) (section 7). For the