Goofish (闲鱼 / Xianyu) is Alibaba's flagship C2C recommerce marketplace — processing over 100M+ monthly active buyers across vintage mirrorless cameras, PC GPUs, retro handhelds, road bikes, luxury handbags, and anime/ACG collectibles (guzi / 谷子). Because individual Chinese sellers price used gear for fast domestic turnover, street prices on Goofish routinely sit 20%–45% below eBay, Reverb, Mercari JP, or Chrono24.
Yet if you have ever tried building a Python deal monitor, price-comp dataset, or AI shopping agent for Goofish from outside mainland China, you hit four immediate engineering walls:
- Ephemeral Request Signing & Session Tokens: Goofish's web and mobile endpoints require short-lived cryptographic request signatures paired with rotating session tokens that expire rapidly.
- Alipay / +86 Real-Name Login Walls: Unauthenticated keyword search and seller-profile requests on standard web views immediately hit a mandatory Taobao/Alipay QR login gate requiring mainland +86 SMS or passport KYC verification.
- Aggressive Datacenter Anti-Bot Filtering: Standard cloud IPs (AWS, GCP, GitHub Actions, Hetzner) are immediately blocked or challenged with interactive verification sliders.
-
Opaque
m.tb.cnShare Snippets & Slang: Sellers share links as raw mobile text (【闲鱼】https://m.tb.cn/h.xxxx 点击链接直接打开), and listings use domain-specific Chinese shorthand (箱说全= full box & papers,无拆无修= unopened/unrepaired,个人闲置= personal seller,吧唧= anime tin badge) that literal English keyword searches miss completely.
In this guide, we will walk through how to query live Goofish listings, resolve m.tb.cn share links, compute CNY-to-USD markdowns, generate 1-click Superbuy / AllChinaBuy proxy checkout links, and audit seller Zhima Credit (芝麻信用) & buyer reviews using the open-source goofish-xianyu-api Python SDK and goofish-xianyu-mcp Model Context Protocol server — with zero Taobao/Alipay cookies.
Architecture & Realistic Capabilities
Instead of maintaining brittle local Playwright browsers, +86 SIM cards, and residential proxy pools, goofish-xianyu-api (zero third-party Python dependencies) and goofish-xianyu-mcp expose a typed client + local helpers (offline English-to-Chinese Xianyu slang glossary, itemId watchlist state deduplication, CNY-to-USD markdown math, and Zhima Credit scoring) backed by cloud HTTP endpoints:
| Module / Tool | Package | Key Capabilities |
|---|---|---|
GoofishClient.search_items / search_many
|
goofish-xianyu-api |
Single & multi-keyword search, cross-keyword itemId dedup, auto-pagination, only_new state file |
GoofishClient.get_item_detail / get_seller_*
|
goofish-xianyu-api |
m.tb.cn share-link resolution, seller Zhima Credit & KYC badges, onsale/sold comps, buyer reviews |
search_goofish_items & 4 Seller/Item MCP Tools |
goofish-xianyu-mcp |
Native stdio MCP server for Claude Desktop, Cursor, Windsurf, and VS Code |
What Works Without Login vs. Platform Boundaries
Before writing code, it helps to separate what public guest extraction reliably delivers from what requires a personal mobile app session:
-
Works Reliably Without Cookies:
- Live keyword search with CNY
price_min/price_max,personal_only(个人闲置),free_shipping(包邮), sort order (newest,price_asc,priceDrop,credit), and city region filters. - Multi-page Standby auto-pagination (
30items/page up to150items synchronously, or up to1,500items via batch fallback). - Full item detail resolution (description, HD image gallery, specs dictionary,
wantscount, city, condition tag) from numeric IDs,goofish.comURLs, or rawm.tb.cnmobile share text. - Seller Zhima Credit (
芝麻信用) tiers (极好,优秀,良好,中等,较差), biometric KYC verification badges (实人认证,实名认证), activeonsaleand historicalsoldcatalogs, and paginated buyer feedback reviews (all,negative_only,with_photos).
- Live keyword search with CNY
-
Upstream Platform Boundaries:
- Private buyer-seller DM chat messages, unmasked seller phone/Alipay identifiers, and direct order placement require an authenticated personal Goofish app account (or a cross-border purchasing agent such as Superbuy or AllChinaBuy).
Step 1: Configure Your API Environment Variable
Both goofish-xianyu-api and goofish-xianyu-mcp auto-detect credentials from your environment (APIFY_TOKEN, UNITBYTES_API_KEY, or RAPIDAPI_KEY; see package READMEs for token setup):
export APIFY_TOKEN="apify_api_YOUR_TOKEN"
# Also supports UNITBYTES_API_KEY or RAPIDAPI_KEY automatically
Step 2: Multi-Keyword Watchlist Sniper in Python (goofish-xianyu-api)
Install the typed Python SDK (Python 3.10+):
pip install goofish-xianyu-api
Offline English → Xianyu Slang Translation + Deduplicated Watchlist
goofish-xianyu-api ships with a curated offline English-to-Simplified-Chinese Xianyu glossary (translate_keyword, zero LLM calls), cross-keyword itemId deduplication (search_many), atomic local state persistence (only_new=True), and proxy-agent URL builders (build_proxy_agent_links):
from goofish_xianyu_api import (
GoofishClient,
analyze_resale_pricing,
build_proxy_agent_links,
translate_keyword,
)
# 1. Offline glossary preserves model numbers while translating Xianyu slang
print(translate_keyword("Sony A7C2 mirrorless camera box and papers"))
# -> "索尼 A7C2 微单相机 箱说全"
print(translate_keyword("Genshin Impact badge unopened"))
# -> "原神 吧唧 全新未拆封"
client = GoofishClient() # Reads APIFY_TOKEN from environment
# 2. Multi-keyword watchlist sniper (auto-paginates >30 items & deduplicates itemIds)
unseen_deals = client.search_many(
[
"Sony A7C2 mirrorless",
"Fujifilm X100VI box and papers",
"Nintendo Switch OLED",
],
max_items=45,
translate_keywords=True,
personal_only=True, # Exclude commercial storefronts (个人闲置)
free_shipping=True,
price_min=900,
price_max=13500,
sort_by="newest",
only_new=True, # Persist seen item IDs so cron runs emit only new drops
state_file="watchlist_seen.json",
)
for item in unseen_deals[:5]:
pricing = analyze_resale_pricing(item, cny_to_usd=0.138)
links = build_proxy_agent_links(item)
print(
f"[{item.get('matchedKeyword')}] {item['title']}\n"
f" Price: ¥{pricing.price_cny} (${pricing.price_usd}) | "
f"Markdown: -{pricing.discount_pct}% | Condition: {pricing.condition_normalized}\n"
f" Superbuy: {links.superbuy}\n"
f" AllChinaBuy: {links.allchinabuy}"
)
Step 3: Vet Seller Zhima Credit, Sold Comps & Negative Buyer Reviews
Cheap electronics or luxury pieces on C2C marketplaces require seller vetting before you submit an agent order. You can score a seller's Zhima Credit (芝麻信用), biometric KYC verification, historical sold count, and negative dispute reviews programmatically:
from goofish_xianyu_api import GoofishClient, assess_seller_trust
client = GoofishClient()
# Resolve a raw mobile share link first if you only have pasted text
item = client.get_item_detail("【闲鱼】https://m.tb.cn/h.5xyz123 点击链接直接打开")
seller_id = item.get("sellerId") or "2214891234567"
# Fetch seller profile + compute objective 0-100 trust assessment
profile = client.get_seller_profile(seller_id)
trust = assess_seller_trust(profile)
print(
f"Seller Trust: {trust.trust_score}/100 | "
f"Zhima Tier: {trust.zhima_tier} | "
f"KYC Verified: {trust.is_kyc_verified} | "
f"Risk: {trust.risk_level}"
)
print("Signals:", trust.signals)
# Inspect historical sold comps to check if seller is a genuine hobbyist or grey-market dealer
sold_history = client.get_seller_items(seller_id, status="sold", max_items=20)
print(f"Sampled {len(sold_history)} historical sold items")
# Pull negative buyer feedback specifically to catch refurbishment / dispute red flags
disputes = client.get_seller_reviews(
seller_id,
review_filter="negative_only",
max_reviews=20,
)
for rev in disputes:
print("Dispute review:", rev.get("content"))
Step 4: Terminal CLI Exports (json, jsonl, csv)
Installing goofish-xianyu-api also registers the goofish-xianyu (and goofish-scrape) CLI for one-liner CSV exports and cron scripts:
# Multi-keyword translated watchlist -> JSONL (only newly listed items)
goofish-xianyu --format jsonl search \
--keywords "Sony A7C2 mirrorless" "Pokemon card unopened" \
--translate \
--personal-only \
--max-items 40 \
--only-new ./seen_items.json
# Export personal-seller deals with USD markdowns & Superbuy columns to CSV
goofish-xianyu --format csv --output camera_deals.csv search "理光 GR3x 箱说全" --personal-only --max-items 30
Step 5: Connect Claude Desktop, Cursor & Windsurf via MCP
If you prefer researching secondhand comps conversationally inside Claude Desktop, Cursor, Windsurf, or VS Code Copilot, install the zero-dependency goofish-xianyu-mcp server in one command:
# Install into Cursor (~/.cursor/mcp.json)
npx -y goofish-xianyu-mcp --install cursor --token apify_api_YOUR_TOKEN
# Or install into Claude Desktop
npx -y goofish-xianyu-mcp --install claude --token apify_api_YOUR_TOKEN
Or add it manually to mcpServers:
{
"mcpServers": {
"goofish-xianyu": {
"command": "npx",
"args": ["-y", "goofish-xianyu-mcp"],
"env": {
"APIFY_TOKEN": "apify_api_YOUR_TOKEN"
}
}
}
}
Once connected, your AI assistant gains 5 live tools (search_goofish_items, get_goofish_item_detail, get_goofish_seller_profile, get_goofish_seller_reviews, and get_goofish_seller_items) — including multi-keyword keywords deduplication, auto-pagination up to 100 listings, offline translateKeywords slang conversion, and ready-to-click Superbuy/AllChinaBuy links.
Try prompting Claude or Cursor:
"Search Goofish personal sellers (
personalOnly=true,translateKeywords=true) acrosskeywords: ['Sony A7C2 mirrorless', 'Fujifilm X100VI box and papers']up to 40 items between ¥7,500 and ¥12,000. Filter out local-pickup-only posts, audit the top 2 sellers' Zhima Credit and negative buyer reviews, and give me Superbuy links."
Resources & Links
-
Python SDK (
PyPI): pypi.org/project/goofish-xianyu-api (pip install goofish-xianyu-api) -
MCP Server (
npm): npmjs.com/package/goofish-xianyu-mcp (npx -y goofish-xianyu-mcp) - Technical Documentation: unitbytes.com/actors/goofish-xianyu-search-scraper
Disclaimer: Independent integration powered by UnitBytes; not affiliated with or endorsed by Alibaba Group, 1688.com, or Goofish/Xianyu.
Top comments (0)