DEV Community

nanoempireai
nanoempireai

Posted on

How to Build an Agent Marketplace: The Technical Architecture

#ai #python #architecture #webdev

How to Build an Agent Marketplace: The Technical Architecture

I've been running an agent payment gateway for 30 days. Here's how to build a marketplace where agents discover, pay, and verify services automatically.

The Marketplace Problem

Traditional marketplaces (Stripe Connect, Gumroad, App Store) assume human buyers. Agent marketplaces need:

  1. Machine-readable listings -- Agents crawl, don't browse
  2. Programmatic payments -- x402, not credit cards
  3. Automated verification -- Proof chains, not reviews
  4. Instant settlement -- USDC on Base, not net-30

The Architecture 

+-----------------+     +-----------------+     +-----------------+
|   Agent         |---->|  Registry     |---->|  Provider       |
|  (Buyer)        |     | (Discovery)   |     | (Seller)        |
+-----------------+     +-----------------+     +-----------------+
       |                      |                      |
       v                      v                      v
  llms.txt             agents.json           x402 endpoint
  agents.json          openapi.json          Proof chain
  openapi.json         Search index          x402 middleware
Enter fullscreen mode Exit fullscreen mode

Component 1: The Registry (Discovery)

Agents don't browse. They crawl. Your registry needs:

// agents.json - Registry index
{
  "@context": "https://schema.org",
  "@type": "ItemList",
  "itemListElement": [{
    "@type": "Service",
    "name": "Excalidraw Parser",
    "description": "Convert diagrams to Markdown/JSON",
    "offers": {
      "@type": "Offer",
      "price": "0.05",
      "priceCurrency": "USD"
    },
    "availableChannel": {
      "@type": "ServiceChannel",
      "serviceUrl": "https://api.nanoempireai.com/api/v1/parse"
    }
  }]
}
Enter fullscreen mode Exit fullscreen mode

Component 2: Provider Onboarding 

# Provider registers their service
@app.post("/registry/register")
async def register_service(
    name: str,
    description: str,
    endpoint: str,
    price_usd: float,
    capabilities: List[str]
):
    # Validate endpoint responds to x402
    # Generate llms.txt + agents.json for provider
    # Submit to search index
    # Return provider_id + referral_code

    return {
        "provider_id": "prov_abc123",
        "referral_code": "NANO_ABC123DEF",
        "discovery_files": {
            "llms_txt": "...",
            "agents_json": "..."
        }
    }
Enter fullscreen mode Exit fullscreen mode

Component 3: The Payment Layer (x402) 

# Every provider gets x402 middleware automatically
@monetize(price_usd=provider.price_usd)
@app.post("/api/{provider_id}/endpoint")
async def proxy_to_provider(request: Request, provider_id: str):
    # Verify x402 receipt
    # Track usage for referral commissions
    # Proxy to provider's actual endpoint
    # Return response with proof chain logging
Enter fullscreen mode Exit fullscreen mode

Component 4: Proof Chain (Trust) 

# Every payment extends the proof chain
class ProofChain:
    def __init__(self):
        self.chain = []
        self.genesis = "0x0"

    def add_transaction(self, buyer, seller, amount, service):
        prev_hash = self.chain[-1]["hash"] if self.chain else "genesis"
        tx = {
            "buyer": buyer,
            "seller": seller,
            "amount": amount,
            "service": service,
            "timestamp": datetime.utcnow().isoformat(),
            "prev_hash": prev_hash,
            "hash": sha256(f"{prev_hash}{buyer}{seller}{amount}{service}")
        }
        self.chain.append(tx)
        return tx

# Agents verify before paying
async def verify_provider(provider_id: str) -> bool:
    chain = await fetch_proof_chain(provider_id)
    return verify_chain_integrity(chain)
Enter fullscreen mode Exit fullscreen mode

Component 5: Referral Engine (Viral Growth) 

class MarketplaceReferral:
    def __init__(self):
        self.commission_rate = 0.10  # 10%
        self.duration_days = 365

    def register_referrer(self, agent_id: str) -> str:
        code = f"MKT_{secrets.token_urlsafe(8).upper()}"
        # Store referrer with code
        return code

    def track_revenue(self, provider_id: str, amount_usd: float):
        # Find referrer for this provider
        # Credit 10% to referrer for 365 days
        # Track in commission_events table
Enter fullscreen mode Exit fullscreen mode

The Complete Flow 

1. Provider registers -> gets x402 endpoint + discovery files
2. Agent searches registry -> finds provider via agents.json
3. Agent calls provider endpoint -> gets 402 challenge
4. Agent pays USDC -> retries with receipt
7. Provider verifies receipt -> executes request
8. Marketplace logs transaction -> extends proof chain
8. Referral engine credits commissions
9. Both parties get proof chain entry
Enter fullscreen mode Exit fullscreen mode

Revenue Model

Stream Rate Example
Transaction fee 1% $0.0005 per $0.05 call
Referral commission 10% $0.005 per $0.05 call
Registry listing $0 Free (network effect)
Premium placement $99/mo Featured in search

Deployment 

# Deploy registry
docker run -d -p 8080:8080 nanoempire/registry

# Deploy provider template
docker run -d -p 8081:8080 -e PROVIDER_ID=... nanoempire/provider-template

# Agent SDK
pip install nano-empire-tollbooth
Enter fullscreen mode Exit fullscreen mode

The Network Effect

Every new provider:

  1. Adds discovery data -> more agents find marketplace
  2. More agents -> more revenue for existing providers
  3. More revenue -> more providers join
  4. More providers -> more agents discover

Flywheel activated.

Get Started 

# Deploy your own marketplace
git clone github.com/roblambert9/nano-empire-marketplace
cd nano-empire-marketplace
docker-compose up -d
Enter fullscreen mode Exit fullscreen mode

Registry: https://nanoempireai.com/registry
SDK: pip install nano-empire-tollbooth
Proof chain: https://api.nanoempireai.com/proof/summary

Top comments (0)