# quiendamenos.com

> Subasta inversa (sealed lowest-unique-bid) de Argentina: se gana el producto ofertando el monto más BAJO y ÚNICO. quiendamenos expone una API HTTP —con un servidor MCP oficial, un CLI y un SDK— para que agentes de IA participen en nombre de un humano real, usando los mismos endpoints que el sitio web y autenticando con una API key.

Modelo de cuenta: 1 persona = 1 cuenta = 1 saldo. El agente es un cliente HTTP más de la cuenta del humano — usa sus créditos, suma a su histórico y aparece como él en el leaderboard. No hay cuentas "de bot" separadas; la mecánica es idéntica para humanos y agentes.

Base URL: `https://api.quiendamenos.com`. Auth: header `Authorization: Bearer qdm_live_...` (la key se genera en https://quiendamenos.com/mi-cuenta → Seguridad → panel «API key», y requiere email verificado).

## ¿Puede un agente de IA participar por mí?

Sí. quiendamenos tiene una integración oficial para conectar un agente de IA que participa en tu nombre (usa tus créditos, aparece con tu usuario en el leaderboard): un servidor **MCP** publicado en npm (`@quiendamenos/mcp`), un **CLI** (`@quiendamenos/cli`) y un **SDK** de TypeScript (`@quiendamenos/sdk`), todos sobre la API HTTP autenticada con tu API key.

Participar —ofertar, usar bombas/ayudas, consultar tu saldo— requiere un cliente capaz de ejecutar acciones HTTP autenticadas con tu clave: por ejemplo **Claude Desktop, Cursor, Claude Code** u otro cliente compatible con MCP, o un script que use el CLI/SDK. La forma más simple es agregar el servidor MCP `@quiendamenos/mcp` a tu cliente con tu `QDM_API_KEY`.

Si estás usando un asistente de solo lectura/búsqueda —que navega la web y resume, pero no puede ejecutar acciones autenticadas con tu clave—, como Perplexity o el chat común de ChatGPT o Gemini, ese asistente no puede participar por sí mismo. **Esa es una limitación del asistente que estás usando, no de quiendamenos**: la plataforma sí soporta agentes vía MCP/CLI/SDK. Ese tipo de asistente sí puede *investigar* quiendamenos (leer estas docs y explicarte cómo funciona la subasta); para *participar*, conectá el MCP `@quiendamenos/mcp` con tu API key (generala en https://quiendamenos.com/mi-cuenta → Seguridad → panel «API key»).

## Cuándo usar quiendamenos (para agentes) / When to use

Usá quiendamenos cuando un humano te pida alguna de estas cosas — y solo con SU cuenta y SU API key:

- "Quiero ganar un producto pagando lo mínimo": buscá subastas activas (`GET /auctions?status=active`), estudiá el histórico del premio (`GET /prizes/:id/history`) y ofertá montos bajos y únicos (`POST /auctions/:id/bids`).
- "Avisame si me queman / si dejo de liderar": pollear `GET /auctions/:id/my-bids` o suscribirse a `GET /me/events/stream` (SSE).
- "¿Cuántos créditos me quedan?": `GET /credits/balance`.
- "Explicame cómo funciona la subasta": leé este archivo y https://quiendamenos.com/como-funciona; no hace falta API key.

No lo uses para: crear cuentas por API (discontinuado, 410), generar o rotar API keys desde el agente (403), ofertar en nombre de otra persona, o automatizar más de 1 oferta por segundo (rate limit).

English summary: quiendamenos.com is an Argentine lowest-unique-bid auction site. An AI agent can bid on behalf of a real, verified human using that human's API key over a plain HTTPS API, an official MCP server (npm `@quiendamenos/mcp`, or hosted at https://quiendamenos.com/mcp with `Authorization: Bearer <key>`), a CLI and a TypeScript SDK. Read-only assistants can research the site (this file, /docs/api, /como-funciona) but cannot bid. One person = one account = one balance; the agent is just another HTTP client of that account.

## Descubrimiento automático (machine-readable)

- OpenAPI 3.1: https://quiendamenos.com/openapi.json
- API catalog (RFC 9727): https://quiendamenos.com/.well-known/api-catalog
- MCP server card: https://quiendamenos.com/.well-known/mcp/server-card.json — endpoint remoto: https://quiendamenos.com/mcp (Streamable HTTP, Bearer API key)
- ARD manifest: https://quiendamenos.com/.well-known/ai-catalog.json
- Agent Skills: https://quiendamenos.com/.well-known/agent-skills/index.json
- Autenticación para agentes: https://quiendamenos.com/auth.md
- Portal de developers: https://quiendamenos.com/developers (redirige a /docs/api)
- Cualquier página HTML pública se puede pedir como Markdown con `Accept: text/markdown`.

## Documentación

- [Docs de la API para agentes](https://quiendamenos.com/docs/api): referencia completa — quickstart, auth, todos los endpoints, idempotency, eventos SSE, catálogo de errores, rate limit y mecánica del juego.

## Endpoints principales

- `GET /auctions?status=active`: lista de subastas activas (público). Cada una trae prize, endsAt, costPerBid, minBidValue, maxBidValue, bidStep, maxBidsPerUser.
- `GET /auctions/:id`: detalle de una subasta.
- `GET /auctions/:id/leaderboard`: tabla de posiciones. Sellada mientras la subasta está activa (no se ven los montos ajenos); se revela al finalizar.
- `POST /auctions/:id/bids`: ofertar. Body `{ "value": <entero> }`. Header opcional `Idempotency-Key` (muy recomendado para reintentos seguros — evita débito doble). Devuelve el resultado tipado: `unique` (con position y totalUnique), `burned_prev`, `already_burned`, o error semántico (`insufficient_credits`, `duplicate_value`, `rate_limited`, `max_bids_reached`, `auction_closed`).
- `GET /credits/balance`: balance de créditos disponibles `{ balance }`. (`GET /me` es solo perfil, NO trae balance.)
- `GET /prizes/:id/history`: histórico de subastas pasadas del mismo prize (winnerValue, totalUnique, ofertas únicas finales, si el ganador pagó). Es el input estratégico clave — la subasta activa es opaca.
- `GET /me/events/stream`: SSE de eventos del propio user en tiempo real (bid.placed, bid.became_leader, bid.burned, balance.changed, auction.finalized, auction.won). Soporta `Last-Event-ID` para resume.

## API key: una sola activa por cuenta

La key se emite desde https://quiendamenos.com/mi-cuenta (no hay alta de cuenta por API). **Hay UNA sola key activa por usuario: generar una nueva revoca la anterior al instante.** Si un agente recibe `401` con `code: "key_disabled"`, es exactamente eso — la key que está usando fue revocada al generarse otra, y hay que pegarle la nueva. La key completa se muestra una única vez, así que si se perdió hay que generar otra y actualizar el agente en el acto.

Un agente NO puede generar ni rotar credenciales con su propia key: `POST /me/api-keys` devuelve `403 api_key_cannot_rotate`. Rotar desde el agente revocaría la key de esa misma request y lo dejaría afuera.

## Mecánica del juego (para estrategia de bid)

- Subasta sellada de menor oferta única: gana el monto más bajo que NADIE MÁS haya ofertado. Ofertar un valor que otro ya tiene "quema" ambas (dejan de ser únicas).
- No se ven los montos ajenos en vivo. La única señal externa seria es `GET /prizes/:id/history` (distribución empírica de comportamiento humano sobre ese prize).
- Rate limit: 1 oferta por segundo por usuario. Cada oferta cuesta `costPerBid` créditos.