XianYuApis: a reverse-engineered Goofish IM layer for AI customer service agents

The gap XianYuApis fills: no official IM interface on Xianyu

Xianyu, the second-hand marketplace operated by Alibaba and reachable at goofish.com, does not publish an instant messaging API. The README states this directly: the official platform has no open IM message interface. That single absence blocks an entire category of work. If you want an LLM to answer buyer questions on a listing, the model is the easy part. The hard part is getting the message out of Xianyu and into your process, then getting a reply back into the same conversation thread without a human copy-pasting it.

XianYuApis is aimed at developers who have already decided to build that loop. The README frames the audience as sellers who want a 24/7 automated customer service presence, and the repository name describes itself as an AI Agent foundation. The intended user is comfortable reading Python, running a Node.js process alongside it, and pulling a cookie string out of browser developer tools. This is not a hosted service and there is no dashboard. You clone it, install dependencies, paste credentials into a source file, and run a long-lived process.

The project also lists seven downstream repositories built on top of it, including XianyuAutoAgent and several forks of xianyu-auto-reply. That list is the clearest signal of what the library is for: it is a substrate, and other people have already built the agent layer above it.

How the message path actually works: sign, base64, Protobuf

The README describes the private-message channel as a WebSocket protocol that was reverse-engineered from the web client. Three transformations are named: a sign signature, base64 encoding, and Protobuf serialization. The sign algorithm is the part that matters most, because it is the piece the platform controls and can change without notice. According to the project structure, the signature core lives in static/goofish_js_*.js, a JavaScript file the Python process invokes. That is why Node.js 18+ is a hard environment requirement even though the visible code is Python. The signing logic was not ported to Python; it is executed where it was extracted.

The supporting pieces sit in utils/goofish_utils.py, which the README describes as holding sign signing, cookie handling, and message decryption. Message type definitions are separated into message/types.py, with TextContent, ImageContent and AudioContent named. The HTTP side is a separate module, goofish_apis.py, covering login, token refresh, product detail lookup, and media upload. The README claims the HTTP sign parameter has been decrypted there as well.

The data flow for a reply is short. Incoming text arrives over the WebSocket, gets parsed for send_user_id, cid and send_message, is handed to a handler, and goes back out through a send_msg call wrapped in make_text. The README's own diagram shows the loop as user message into the library, out to your agent, and back as a send. Everything between the parse and the send is yours to write.

Getting it running: two runtimes, one cookie, one file to edit

The documented setup is deliberately minimal. Install Python dependencies with pip install -r requirements.txt. Node.js 18+ must already be present because the signature step shells out to JavaScript. Then, per the README, you log into goofish.com in a browser, open developer tools, copy the full cookie string, and paste it into the bottom of goofish_live.py, replacing the placeholder value assigned to cookies_str. The README adds one warning about this step: the cookie must come from a logged-in session, otherwise message retrieval will not work.

Running the listener is a single command, python goofish_live.py. There is no configuration file, no environment variable convention documented, and no CLI flags described. Credentials live in source. The README also mentions a Dockerfile in the project structure but does not document how to build or run the image, so treat containerised deployment as unverified from the available material.

The extension point is the handle_message method in goofish_live.py. The README shows the shape of the change: replace the echo reply with a call to your own agent function, then pass the result to send_msg alongside cid and send_user_id, wrapped by make_text. A separate note says goofish_apis.py contains HTTP endpoint templates that you can extend if you need an endpoint the library does not already cover.

The cookie is the whole session, and that is the design's weak point

Nothing in the README describes an OAuth flow, an application registration, or a scoped credential. Authentication is a browser cookie pasted as a raw string into a Python file. Everything the library can do, it can do because that cookie says you are a logged-in user. The consequences follow directly from that.

The README does list automatic token refresh as an implemented feature, described as keeping a long-running process online. That mitigates expiry, not revocation. If Goofish invalidates the session, changes its cookie scheme, or rotates the sign algorithm in static/goofish_js_*.js, the library stops working, and the failure surfaces as a dead WebSocket rather than a clear error. There is no documented retry policy, backoff strategy, or health endpoint. You will be writing that yourself.

The message type support is also narrower than the feature table implies at first read. Text and image messages are listed as implemented. AudioContent appears in message/types.py according to the project structure, but the implemented-features table names only text and image. Whether audio is parsed but not sent, or defined but unused, cannot be determined from the README. If your use case involves voice notes, verify this before committing.

Finally, the licence situation is ambiguous in a way that matters for commercial deployment. The README carries an MIT badge that links to a LICENSE file, but the repository metadata supplied here lists the licence as unknown. A badge is not a licence file. Anyone planning to ship this inside a business should confirm the actual file exists and reads as expected before relying on it.

Where XianYuApis sits against a plain browser automation script

The obvious alternative is Playwright or Selenium driving a real browser session against goofish.com. The difference in approach is structural, not cosmetic. A browser automation script operates on the rendered page: it clicks, waits for DOM elements, and scrapes visible text. XianYuApis operates on the wire protocol underneath that page, speaking the WebSocket and HTTP calls the frontend itself makes.

That distinction has practical consequences. A browser-driven agent consumes a full browser process per session, is sensitive to layout changes, and reacts at the speed of rendering. A protocol-level client is lighter and sees messages as they arrive on the socket rather than after a re-render, which is why the README can describe a persistent listener with automatic token maintenance. On the other side, a browser script breaks when CSS selectors change; XianYuApis breaks when the sign algorithm or the Protobuf schema changes. Both are maintenance liabilities, but the second kind produces a harder failure to debug, because there is no page to look at when the socket goes quiet.

A third option is simply not automating: using Xianyu's own seller tools and answering messages by hand. For a seller with a handful of conversations a day, that is the correct answer, and no library changes it. XianYuApis only pays off when message volume exceeds what a person can answer, and when you are prepared to own a process that can fail silently.

Maintenance cost and what the release history suggests

The repository's last push is dated 2026-08-18, and the most recent releases are goofish_v1.0.1 on 2026-04-07 and goofish v1.0.0 on 2026-04-06. Two releases four months before the last commit, on a project whose core value is a reverse-engineered signature algorithm, tells you something about the maintenance rhythm. There is no changelog in the supplied material, so what changed between v1.0.0 and v1.0.1 is not documented here.

For an adopter, the recurring cost is not installing the library. It is monitoring whether the sign step still produces values the server accepts. Because the algorithm lives in a JavaScript file extracted from the web client, a frontend update on Goofish's side can invalidate it without any change to this repository. The README offers no guidance on detecting that condition or updating static/goofish_js_*.js. That work is undocumented and, based on the material available, unassisted.

There is also a licensing question layered on top of the technical one. The README states an MIT badge, the metadata says unknown, and the README separately carries a disclaimer asking that the project not be used for harmful content and offering to remove material on infringement request. That disclaimer is a request from the author, not a licence term. Treat the two as separate things and read the actual LICENSE file before depending on the MIT claim.

Who should build on this, and what to check first

XianYuApis is a reasonable starting point for a developer who wants to prototype an AI reply loop on Xianyu and is willing to run Python and Node.js together, paste a cookie into a source file, and write the agent logic inside handle_message. The README's own example does exactly that in a few lines, and the list of downstream projects shows the pattern has been reproduced by others.

It is the wrong tool for anyone who needs a supported integration. There is no versioned API contract, no documented error handling, no rate-limit guidance, and no statement about what happens when the WebSocket drops. A team that cannot tolerate an unexplained outage in a customer-facing inbox should not put this in front of buyers.

Before writing agent code, verify three things against the repository itself rather than the README. First, open the LICENSE file and confirm the MIT claim holds, since the metadata does not corroborate it. Second, inspect static/goofish_js_*.js and check whether the signature logic still matches what goofish.com currently sends, because that file is the single point of failure for the entire library. Third, read message/types.py to settle whether AudioContent is wired up, since the feature table and the file listing disagree. Those three checks take minutes and determine whether the rest of the work is worth starting.

Editorial conclusion

Adopt XianYuApis if you already run Python 3.9+ and Node.js 18+ side by side and you need a message transport layer, not a product. Do not adopt it if you need an SLA, a supported API contract, or any guarantee that the sign algorithm still matches Goofish's frontend next month. Before writing a single line of agent logic, confirm the repository actually ships the LICENSE file its README badge points to, and check whether the static/goofish_js_*.js signature bundle is current against the live site.

Official sources

1. cv-cat/XianYuApis on GitHub
2. Issues
3. README
4. Releases