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.
