Documentación · v1.0

Documentación

Cómo comprar y usar una El mañoso — para humanos en terminal, agentes IA y clientes MCP.

Esta página explica cómo consumir el servicio, no cómo está construida la web. Si solo quieres comprar la receta, salta a Quickstart — Humano o Quickstart — Agente IA.

Qué es esto

El mañoso es un catálogo de playbooks de arbitraje en formato Markdown, vendidos por request vía HTTP 402 Payment Required usando MPP (Machine Payments Protocol). Cada receta cuesta $0.01 USDC liquidado en Tempo mainnet (chain ID 4217). Sin cuenta, sin API key, sin email — la prueba de pago va en un único header HTTP.

Cada El mañoso incluye:

▸Un SKU concreto con URL de origen y categoría destino
▸Unit economics completos (compra, comisiones, envío, neto)
▸El filtro de sourcing exacto (no captura, parámetros)
▸Logística e import / hedge cambiario
▸Template de listing y regla de pricing
▸5 SKUs adicionales pre-validados
▸Registro de riesgos y límites de saturación

El producto, la URL de origen, el template y el filtro no son públicos. Se entregan solo después de que el pago se asienta on-chain.

Quickstart — Humano

Si tienes una terminal y quieres comprar la receta #001:

npx mppx https://this-host/api/recipes/profit-recipe-001

Primera vez:

npx mppx account create

Fondea la wallet con ≥ $0.01 USDC en Tempo mainnet y reintenta. El comando imprime el Markdown completo en stdout y guarda el X-Receipt (JWT firmado) como prueba de compra. Puedes redirigir a archivo:

npx mppx https://this-host/api/recipes/profit-recipe-001 > recipe-001.md

Solo quieres ver el reto 402 sin pagar:

curl -i https://this-host/api/recipes/profit-recipe-001

Verás 402 Payment Required y el header WWW-Authenticate: Payment ... con todos los parámetros que un cliente MPP necesita.

Quickstart — Agente IA

El ciclo completo en cuatro pasos:

1. GET /api/recipes/profit-recipe-001
   → 402 Payment Required
   WWW-Authenticate: Payment id="...", realm="...", method="tempo",
                     intent="charge", request="<base64-json>",
                     expires="..."

2. (cliente liquida $0.01 USDC en Tempo usando el challenge)

3. GET /api/recipes/profit-recipe-001
   Authorization: Payment id="...", payload="..."
   → 200 OK
   Content-Type: text/markdown; charset=utf-8
   X-Receipt: <HS256 JWT>
   <cuerpo Markdown completo>

4. Persiste X-Receipt como prueba de compra (verificable en /api/verify)

Antes de gastar el dólar, los agentes deberían usar /api/recipes/[id]/preview y /api/quote/[id] para conocer el contenido y el precio sin disparar el paywall.

MPP — Machine Payments Protocol

MPP es un protocolo abierto desarrollado por Tempo y Stripe que permite a apps y agentes pagar por request en la misma llamada HTTP, usando el código de estado 402 Payment Required como handshake.

| Parámetro | Valor | |---|---| | Protocolo | MPP | | Network | Tempo mainnet | | Chain ID | 4217 | | Moneda | USDC (6 decimales) | | Intent | charge | | Method | tempo | | Monto | $0.01 (10,000 base units) |

Recursos oficiales:

▸mpp.dev — overview
▸Docs — referencia completa
▸Quickstart para agentes
▸Quickstart para servidores
▸Spec IETF — borrador en proceso

API Reference

Todos los endpoints son GET salvo donde se indique. Base URL: el host donde esté desplegada esta landing.

`GET /api/recipes`

Lista el catálogo completo con metadata pública (id, título, precio, márgenes, dificultad, endpoints). No requiere pago.

Respuesta (200, application/json):

{
  "recipes": [
    {
      "id": "profit-recipe-001",
      "version": "1.0",
      "title": "The North-South Tech Gap",
      "tagline": "Keepa-flagged US tech deals → MercadoLibre México",
      "industry": "Consumer Tech · Cross-Border",
      "capital_usd": { "min": 200, "max": 500 },
      "margin_pct":  { "min": 28,  "max": 62 },
      "difficulty": "Medium",
      "time_to_close_days": { "min": 7, "max": 14 },
      "replicability": "High",
      "price_usd": "0.01",
      "tags": ["ecommerce", "arbitrage", "cross-border", "mexico", ...],
      "validated_at": "2026-05-16",
      "endpoints": {
        "preview": "/api/recipes/profit-recipe-001/preview",
        "buy":     "/api/recipes/profit-recipe-001",
        "quote":   "/api/quote/profit-recipe-001"
      }
    }
  ],
  "count": 3
}

Cacheado público 60s, edge 300s.

`GET /api/recipes/[id]`

Endpoint pagable. Devuelve la receta completa en text/markdown tras un pago MPP exitoso.

▸Sin Authorization: Payment → 402 Payment Required con header WWW-Authenticate: Payment ...
▸
Con prueba de pago válida → 200 OK con cuerpo Markdown y headers:
- ▸X-Recipe-Id, X-Recipe-Version
- ▸X-Receipt: JWT HS256 firmado (verificable en /api/verify)
- ▸Cache-Control: private, no-store

Rate-limited a 30 req/min por cliente.

IDs disponibles: profit-recipe-001, profit-recipe-002, profit-recipe-003.

`GET /api/recipes/[id]/preview`

Vista previa pública (no spoiler): tagline, unit economics en rangos, dificultad, tiempo, qué campos están ocultos hasta la compra. Sin paywall.

Respuesta (200):

{
  "id": "profit-recipe-001",
  "version": "1.0",
  "preview": "An arbitrage playbook moving specific Keepa-flagged...",
  "hidden": [
    "product_sku",
    "source_marketplace_url",
    "destination_marketplace_listing_template",
    "exact_sourcing_filter",
    "freight_forwarder_picks",
    "alternate_validated_skus"
  ],
  "price_usd": "0.01",
  "buy_endpoint": "/api/recipes/profit-recipe-001",
  "payment": {
    "protocol": "mpp",
    "intent": "charge",
    "method": "tempo",
    "chain_id": 4217,
    "currency": "USDC"
  }
}

`GET /api/quote/[id]`

Cotización pura: precio, moneda, chain, endpoint de compra. Útil para que un agente decida si comprar antes de disparar el paywall.

{
  "recipe_id": "profit-recipe-001",
  "price": {
    "amount_usd": "0.01",
    "currency": "USDC",
    "chain": "tempo",
    "chain_id": 4217
  },
  "protocol": "mpp",
  "method": "tempo",
  "intent": "charge",
  "buy_endpoint": "/api/recipes/profit-recipe-001"
}

`GET /api/recipe` (legacy)

Redirección 308 a /api/recipes/profit-recipe-001 por compatibilidad con la primera versión del catálogo. No usar en código nuevo.

`POST /api/verify` · `GET /api/verify?receipt=…`

Verifica un X-Receipt (JWT HS256) emitido por el servidor tras una compra exitosa. No requiere autenticación — verifica firma y vigencia.

POST body:

{ "receipt": "eyJhbGciOiJIUzI1NiIs..." }

Respuesta:

{
  "valid": true,
  "recipe_id": "profit-recipe-001",
  "recipe_version": "1.0",
  "buyer": "0x...",
  "chain_id": 4217,
  "amount_usd": "0.01",
  "issued_at": "...",
  "expires_at": "..."
}

Si la firma o la vigencia fallan: { "valid": false, "reason": "..." }.

`GET /api/metrics`

Contadores públicos del catálogo. Sin auth. Cacheado 10s.

{
  "recipes_sold": 0,
  "unique_buyers": 0,
  "paywall_challenges": 0,
  "previews_served": 0
}

`GET | POST | DELETE /api/mcp`

Endpoint del servidor MCP (ver siguiente sección).

MCP Server

El servidor implementa el Model Context Protocol sobre HTTP usando el transporte WebStandardStreamableHTTPServerTransport del SDK oficial. Está disponible en:

https://this-host/api/mcp

Conectarlo desde Claude Desktop

Edita ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o el equivalente en tu plataforma:

{
  "mcpServers": {
    "el-manoso": {
      "transport": {
        "type": "streamable-http",
        "url": "https://this-host/api/mcp"
      }
    }
  }
}

Reinicia Claude Desktop y el servidor aparecerá con sus tools disponibles.

Tools expuestas

| Tool | Descripción | Input | |---|---|---| | list_recipes | Lista todo el catálogo con metadata pública | — | | preview_recipe | Preview de una receta (sin spoilers) | { id: string } | | get_quote | Precio, chain, currency, buy endpoint | { id: string } | | buy_recipe | Devuelve instrucciones para que el cliente dispare el flujo MPP (el servidor no paga por ti) | { id: string } | | verify_receipt | Verifica un JWT receipt | { receipt: string } | | public_metrics | Contadores públicos | — |

buy_recipe es intencionalmente read-only: devuelve un set de instrucciones HTTP. El cliente MCP o el host del agente debe ejecutar el flujo MPP (settle on Tempo + reintento con Authorization: Payment). Esto preserva el aislamiento entre el servidor y las claves del agente.

CLI

Existe un workspace cli/ reservado para una CLI propia (el-manoso) que envolverá mppx con comandos específicos del catálogo. Estado actual: placeholder vacío.

Mientras tanto, todo es operable con npx mppx directamente sobre cualquier endpoint pagable:

# Comprar una receta
npx mppx https://this-host/api/recipes/profit-recipe-001

# Crear wallet
npx mppx account create

# Ver balance
npx mppx account balance

Cuando la CLI propia esté lista expondrá comandos como:

npx el-manoso list                # lista catálogo
npx el-manoso preview <id>        # preview sin pagar
npx el-manoso quote <id>          # cotización
npx el-manoso buy <id>            # compra vía MPP
npx el-manoso verify <receipt>    # verifica receipt

Documentación se actualizará al liberar la primera versión.

Discovery para agentes IA

Tres recursos discoverables apuntan al catálogo para que agentes y crawlers entiendan qué se vende y cómo pagarlo:

| Recurso | Para qué sirve | |---|---| | /llms.txt | Resumen plano en texto, optimizado para LLMs — endpoints, precio, ejemplos curl | | /.well-known/agent.json | Agent Card v0.3 — schema agentcard.dev con endpoints y autenticación MPP | | /.well-known/mcp.json | Manifest MCP — apunta al endpoint /api/mcp | | /openapi.json | OpenAPI 3.1 completo del catálogo | | /llms-docs.txt | Esta documentación en texto plano para ingesta directa de un LLM |

El <head> del HTML también expone tags <meta name="mpp:*"> con catálogo, método, intent, monto, moneda y chain id — los agentes pueden inferir todo lo necesario sin parsear el cuerpo de la página.

Pricing & límites

▸Precio: $0.01 USDC por receta. Mismo precio para todas las recetas del catálogo en v1.
▸Liquidación: instantánea on-chain en Tempo mainnet (chain ID 4217).
▸Rate limit: 30 requests/minuto por cliente al endpoint /api/recipes/[id]. Excedente devuelve 429 con header Retry-After.
▸Cache del Markdown: la respuesta con el contenido pagado es private, no-store — cada agente paga por su copia.
▸Receipts: cada compra emite un JWT HS256 firmado (header X-Receipt). Verificable en /api/verify. La compra es permanente; el receipt es la prueba criptográfica.

FAQ

¿Qué pasa si mi wallet no tiene saldo?

El servidor responde 402 Payment Required. Tu cliente MPP intentará completar el pago y, si falla por fondos insuficientes, abortará. El servidor no carga nada — el handshake ocurre antes de la liquidación.

¿Puedo revender la receta que compré?

No. La licencia es de comprador único, sin redistribución. El X-Receipt está atado a la wallet pagadora.

¿El mismo agente puede comprar la misma receta dos veces?

Sí. Cada request paga independientemente. Si ya tienes el receipt, no hay razón funcional para repetir — el contenido es estable hasta que recipe_version cambie.

¿Cómo sé cuándo se actualiza una receta?

Cada receta lleva un campo version y validated_at. Si la versión cambia, el contenido pudo cambiar y un receipt antiguo sigue siendo válido para su versión pero no para la nueva.

¿El MCP server cobra al usarlo?

No. Las tools del MCP server (list_recipes, preview_recipe, get_quote, verify_receipt, public_metrics, buy_recipe) son todas gratuitas. buy_recipe solo devuelve instrucciones — el pago se realiza en /api/recipes/[id] cuando el cliente lo ejecute.

¿Funciona con otros chains o monedas?

En v1 solo Tempo + USDC. MPP permite otros métodos pero este servidor solo anuncia tempo en el handshake.

¿Dónde está el código fuente?

Tres workspaces en el repo: landing/ (Next.js — esta página y todos los endpoints), cli/ (vacío, en planning), mcp-server/ (vacío — el servidor MCP funcional vive dentro de landing/ en /api/mcp).