walla

██╗    ██╗  █████╗  ██╗      ██╗       █████╗            ██████╗ ██╗      ██╗
██║    ██║ ██╔══██╗ ██║      ██║      ██╔══██╗          ██╔════╝ ██║      ██║
██║ █╗ ██║ ███████║ ██║      ██║      ███████║  █████╗  ██║      ██║      ██║
██║███╗██║ ██╔══██║ ██║      ██║      ██╔══██║  ╚════╝  ██║      ██║      ██║
╚███╔███╔╝ ██║  ██║ ███████╗ ███████╗ ██║  ██║          ╚██████╗ ███████╗ ██║
 ╚══╝╚══╝  ╚═╝  ╚═╝ ╚══════╝ ╚══════╝ ╚═╝  ╚═╝           ╚═════╝ ╚══════╝ ╚═╝
  look · offer · talk
  Dr. Berend Gort  ·  www.berendgort.dev

walla is an unofficial Wallapop.es CLI + MCP + Python library for Cursor agents and humans: search listings, read inbox, send a message, make an offer.

Not affiliated with Wallapop. Respect ToS and rate limits.

What this unlocks

You tell Cursor: “Find me a used kite near Barcelona under €400, message the seller, and offer if it’s a GRAB.”

The agent runs walla — ranks listings GRAB / LOOK / PASS, links you the item, asks before sending, then talks and offers on your behalf:

walla setup --lat 41.39 --lon 2.17 --km 30 --label Barcelona --budget 400
walla search "tabla kite Cabrinha" --max 40 --json
# agent: GRAB · Cabrinha Moto 10m · €320 · 4 km
#        https://es.wallapop.com/item/...

walla login                         # paste session cookie once
walla say <id> "Hola, ¿sigue disponible? Puedo pasar hoy." --yes
walla offer <id> --eur 280 --yes    # prints total; needs your confirm
walla inbox --json                  # catch the reply

That is the product: a Cursor agent that can look, talk, and offer on Wallapop without opening the website for every step.

Quality bar (enforced in CI):

• docs/code_quality.md — Korotkevich / Tourist bar
• docs/data_engineering_standards.md — Gray / Stonebraker bar
• docs/WIRE.md — captured consumer API
• docs/rate_limit_analysis.md — polite spacing

For AI agents (mandatory protocol)

If the user pasted this GitHub link (or this README), follow this section exactly.

Goal

Look, offer, and talk on wallapop.es using the walla package. Speak briefly. Link listings as https://es.wallapop.com/item/<web_slug>. Verdicts: GRAB / LOOK / PASS.

Bootstrap

1. Install from PyPI (preferred):

   pipx install 'walla-cli[mcp]'
   

   From a clone only when hacking: pipx install -e '.[mcp]'.
2. walla doctor --json — read auth.session and network.reachable. Never print tokens or cookies.
3. If no session: ask the human to run walla login and paste __Secure-next-auth.session-token from es.wallapop.com (Cookie-Editor). Agents may pass it non-interactively: walla login --cookie '<value>' --json.
4. Do the ask with walla … --json and narrate in prose.

Optional MCP:

{
  "mcpServers": {
    "walla": { "command": "walla-mcp" }
  }
}

Operating loop

Rules:

• Reads are safe. say / offer need --yes / confirm=true. Name listing + euros.
• If they only asked to look, do not send.
• Ambiguous match: ask once with candidates.
• In-person offers outside pickup radius: refuse.
• Envelope: ok, api_version, data or error / error_type / retryable.

walla instruct --json returns this recipe.

Install

pipx install 'walla-cli[mcp]'   # PyPI: https://pypi.org/project/walla-cli/
walla setup --lat 41.39 --lon 2.17 --km 30 --label Barcelona --json
walla login          # paste __Secure-next-auth.session-token
walla doctor --json

CLI

Develop

pip install -e '.[dev,mcp]'
pytest -q -m 'not live'
pytest -m live          # hits Wallapop; needs network
ruff check .
mypy walla
python scripts/check_code_quality.py

Read AGENTS.md before extending.

Disclaimer

Unofficial. Not affiliated with Wallapop. Personal / research use.

License

MIT