# XianYuApis: A Reverse-Engineered Goofish IM Layer for AI Customer-Service Agents

> XianYuApis wraps Goofish (Xianyu) HTTP and WebSocket messaging behind a Python abstraction so you can attach an LLM to a seller account. It is a protocol bridge, not a chatbot, and it assumes you already have a logged-in cookie.

**cv-cat/XianYuApis** — 闲鱼算法逆向，闲鱼api，websockets自动运营，咸鱼AI Agent基座

- Repository: https://github.com/cv-cat/XianYuApis
- Stars: 1,473 · Forks: 342
- Language: JavaScript
- License: not declared
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/cv-cat-xianyuapis

## The gap XianYuApis fills: Goofish has no public IM endpoint

Goofish, the second-hand marketplace Alibaba runs under the Xianyu name, does not publish an instant-messaging API. The README states this directly: there is no official IM message interface. That matters if you want to run an LLM as a seller-side customer-service agent, because the model is the easy part. The hard part is getting a private message out of the platform and a reply back in without a human copy-pasting.

XianYuApis is aimed at exactly that seam. Its own description calls it a third-party API integration library and an AI customer-service agent base. The README's data-flow diagram is blunt about the split of responsibility: a buyer's private message enters XianYuApis, which hands it to your agent (LLM, RAG, or a rule engine), and your reply goes back out through the library's send call. In the author's phrasing, you supply the AI brain and the project supplies the connection to Goofish.

The audience is therefore narrow and technical. You need to be comfortable running Python, editing a file to paste a cookie, and reading code to discover method signatures, because the repository does not ship a generated API reference. If you want a hosted chatbot product, this is one layer below that. Several finished agent projects are listed in the README as built on top of it, including XianyuAutoAgent and multiple repositories named xianyu-auto-reply, which suggests the intended pattern is: use this as the transport, build your own product above it.

## Sign, base64 and Protobuf: what the WebSocket layer actually does

The README describes the private-message channel as a reverse-engineered WebSocket protocol built from three pieces: a sign signature, base64 encoding, and Protobuf payloads. The repository layout backs that up. There is a utils/goofish_utils.py that the README says holds the sign function, cookie handling and message decryption, and a static/ directory containing files named goofish_js_*.js, described as the reverse-engineered JavaScript holding the core sign algorithm.

That JavaScript is why the project needs Node.js at all. Python handles the socket and the business logic, but the signature is computed by executing the extracted JS, which is why the README lists Node.js 18+ as an environment requirement alongside Python 3.9+. The Dockerfile confirms the same split: it starts from python:3.12-slim, installs Node.js 18.x through the NodeSource setup script, then runs pip install and a best-effort npm install. The npm step is written as npm install 2>/dev/null || true, so a missing package.json will not fail the build.

On the HTTP side, goofish_apis.py is described as wrapping the platform's HTTP endpoints with the sign parameter already decrypted. The README's feature table lists login by QR code to obtain a cookie, automatic token refresh to keep a long-running process online, fetching full chat history, fetching a specific conversation's history, proactive sending to a named user, product detail lookup, and image upload and send. Only text and image messages are listed as supported message types, so audio is not a working channel despite an AudioContent type appearing in message/types.py.

## Installing XianYuApis and getting a first reply out of goofish_live.py

The README's quick-start has four steps: meet the runtime requirements, install Python dependencies, paste a cookie, and run the main script. requirements.txt is short, listing only requests and loguru, so the Python dependency install is quick. Node.js is not installed by pip; you need it separately unless you use the Dockerfile.

Start by installing the Python packages:

```bash
pip install -r requirements.txt
```

Next, log in to goofish.com in a browser, open the developer tools, and copy the full Cookie string. The README places it at the bottom of goofish_live.py, in a variable named cookies_str, and warns that the cookie must come from a logged-in session or messages cannot be retrieved:

```python
# goofish_live.py bottom
cookies_str = r'your_cookie_string_here'
```

With the cookie in place, run the listener:

```bash
python goofish_live.py
```

The README says goofish_live.py is the main entry point for WebSocket listening and reply logic, and that all AI reply logic is extended there. To wire in a model, you replace the body of handle_message. The README's example keeps the parsed send_user_id, cid and send_message values and swaps the echo reply for an async agent call:

```python
async def handle_message(self, message, websocket):
    # ... parse send_user_id, cid, send_message ...

    # original echo reply (example)
    # reply = f'{send_user_name} said: {send_message}'

    # plug in an AI model (example)
    reply = await your_ai_agent(send_message)  # GPT / Claude / Qwen / local model

    await self.send_msg(websocket, cid, send_user_id, make_text(reply))
```

If you prefer containers, the Dockerfile builds an image tagged xianyuapis and the run command reads variables from an .env file, which matches the .env.dev entry in the repository root:

```bash
docker build -t xianyuapis .
docker run -it --env-file .env xianyuapis
```

The expected result of the Python run is a persistent process that stays connected, refreshes its login state, and prints or forwards incoming private messages to your handler. Note that the README does not document the .env keys, so the environment-file path is only useful once you have read the code that consumes them.

## Cookie-only authentication and the failure modes it creates

The single largest constraint is that authentication is a browser cookie pasted into source. There is no OAuth flow, no API key, and no session store described in the README. The library does claim automatic token refresh to keep a resident process from dropping offline, but the initial credential is still a string you copy by hand. That has consequences the README does not address.

First, a cookie is a personal credential. Committing goofish_live.py with a real cookie in it leaks account access, and the repository's .gitignore is not described as covering that file. Second, cookie rotation is manual. If the session is invalidated, the process cannot recover on its own; someone has to log in again and replace the string. Third, the README gives no guidance on running more than one account, and nothing in the described architecture suggests per-account isolation. If your operation spans several seller accounts, this library is the wrong shape.

There is also an operational silence worth naming. The README does not document rate limits, reconnect backoff, or what happens when the WebSocket drops mid-conversation. It states that token maintenance is implemented, but not how failures surface to your handler. For a 24/7 agent, that is the part you will end up writing yourself. Treat the library as transport and build your own supervision around it.

Finally, the project carries a legal and platform-risk caveat in the README itself: it prohibits use for publishing harmful or illegal content and asks that infringing content be reported to the author for removal. Reverse-engineered protocol access to a commercial platform sits in contested territory, and the README offers no statement about platform terms of service.

## How XianYuApis differs from building on a general automation framework

The obvious alternative for someone who needs to talk to Goofish programmatically is a browser automation framework such as Playwright or Selenium, driving the web UI directly. The difference in approach is fundamental. A browser driver operates the rendered page: it clicks, types, and scrapes the DOM, so it needs a real browser process, it is slow per action, and it breaks whenever the front-end markup changes. XianYuApis instead speaks the underlying protocol. It computes the sign, encodes the payload, and exchanges Protobuf frames over a WebSocket, which is closer to how the official client talks and avoids rendering entirely. That is why the library can push a message proactively and keep a long-lived connection, both of which are awkward in a click-driven script.

The cost of that choice is coupling to a private protocol. When Goofish changes its signing algorithm, a browser automation script may keep working while XianYuApis stops, because the sign lives in static/goofish_js_*.js and the README gives no process for updating it. Conversely, a DOM change breaks the browser script and leaves the protocol client untouched. Neither approach is strictly safer; they fail on different changes.

Within the same niche, the README points to sibling projects rather than competitors: XianyuAutoAgent and the various xianyu-auto-reply repositories are described as agents built on top of this library, not replacements for it. If you want a finished auto-reply application, those are the higher-level starting points. XianYuApis is the layer you pick when you intend to write the agent yourself.

## Maintenance, licence and the cost of staying current

The repository is not archived, and its last push was on 2026-08-18, so it is recent. The most recent releases are goofish_v1.0.1 on 2026-04-07 and goofish v1.0.0 on 2026-04-06. The README says the project will keep being updated, but that is a statement of intent, not a schedule, and there is no published changelog beyond the release tags.

Upgrade cost is dominated by the reverse-engineered JavaScript. Because the sign algorithm lives in static/ and is executed through Node.js, any change to Goofish's signing means someone has to re-extract and re-implement that JS. That work is not something a dependent application can absorb by bumping a version number. Pin the commit you build against, and keep your own record of which sign version your deployment expects, because the README does not expose one.

The licence situation is genuinely ambiguous. The README's badge declares MIT and links to a LICENSE file, but the repository metadata provided for this project lists the licence as unknown. Those two sources disagree, and the repository's top-level file listing does not show a LICENSE file at the root, only .env.dev, .gitignore, Dockerfile, README.md, goofish_apis.py, goofish_live.py, message/, requirements.txt, static/ and utils/. Before you redistribute anything, confirm the licence text yourself; a badge is not a licence grant. This is a factual discrepancy to resolve, not a legal opinion.

## Conclusion

Adopt XianYuApis if you are building a Goofish AI reply agent and want the WebSocket sign, base64 and Protobuf handling done for you, and you accept that your account cookie is the whole authentication story. Do not adopt it if you need a documented, supported platform API, multi-account management, or anything the README calls a stable contract, because the repository ships no API reference beyond code comments and no tests. Before writing your agent, verify three things yourself: that your Python is 3.9 or newer and your Node.js is 18 or newer, that a fresh logged-in cookie actually receives a private message through goofish_live.py, and that your reply path calls send_msg with the cid and send_user_id parsed from the incoming frame.

## FAQ

### What Python and Node.js versions does XianYuApis require?

The README lists Python 3.9+ and Node.js 18+ as environment requirements. Node.js is needed because the sign algorithm is executed from the reverse-engineered JavaScript in the static/ directory. The Dockerfile installs Node.js 18.x on top of a python:3.12-slim base image.

### How do I install XianYuApis and start it?

Install the Python dependencies with pip install -r requirements.txt, paste a logged-in browser cookie into the cookies_str variable at the bottom of goofish_live.py, then run python goofish_live.py. The README warns that the cookie must be from a logged-in session or messages cannot be retrieved.

### How do I connect an AI model to XianYuApis?

Replace the reply logic inside the handle_message method of goofish_live.py. The README's example calls an async agent function with the parsed send_message, then sends the result with self.send_msg(websocket, cid, send_user_id, make_text(reply)).

### Which message types does XianYuApis support?

The README's feature table lists text and image messages as implemented. Audio is not listed as a working channel, even though message/types.py defines an AudioContent type.

### Does XianYuApis use an official Goofish API?

No. The README states that Goofish does not provide an official IM message interface, and that the project reverse-engineers the WebSocket private-message protocol and wraps the HTTP endpoints with the sign parameter decrypted.

## Sources

- [cv-cat/XianYuApis on GitHub](https://github.com/cv-cat/XianYuApis)
- [Issues](https://github.com/cv-cat/XianYuApis/issues)
- [README](https://github.com/cv-cat/XianYuApis/blob/master/README.md)
- [Releases](https://github.com/cv-cat/XianYuApis/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/cv-cat-xianyuapis