How to Authenticate for Xueqiu Stock Data in Agent Reach: A Complete Guide

Agent Reach authenticates Xueqiu stock API requests using the xq_a_token cookie stored in ~/.agent-reach/config.yaml under the xueqiu_cookie key, which the XueqiuChannel class loads automatically from config, browser, or a minimal fallback.

Agent Reach provides programmatic access to Xueqiu.com (雪球), a major Chinese financial data platform, through the XueqiuChannel implementation. To access protected endpoints like hot posts or detailed user data, you must authenticate by providing a valid session cookie that the channel injects into every HTTP request.

How Xueqiu Authentication Works in Agent Reach

The authentication logic resides in agent_reach/channels/xueqiu.py. The XueqiuChannel class manages session state through a three-tier fallback system designed to obtain valid cookies with minimal user intervention.

Loading Cookies from Config

The primary authentication method reads a saved cookie string from the Agent Reach configuration file. When initialized, the channel calls _ensure_cookies(), which invokes _load_cookies_from_config() (lines 59-70) to parse the xueqiu_cookie value from ~/.agent-reach/config.yaml. This function splits the cookie string into individual name=value pairs and injects them into an internal http.cookiejar.CookieJar instance used for all subsequent requests.

Reading Cookies from Browser

If the configuration key is absent, the channel falls back to _load_cookies_from_browser() (lines 74-100). This function attempts to extract Chrome-style cookies for the domain .xueqiu.com using either the rookiepy or browser_cookie3 library. It specifically searches for the xq_a_token cookie required for authenticated endpoints. When found, the cookie is automatically injected into the jar without manual file editing.

Minimal Fallback for Public Endpoints

When neither config nor browser cookies are available, _ensure_cookies() executes a minimal fallback (lines 123-128) that makes a single GET request to https://xueqiu.com. This retrieves the anti-DDoS acw_tc cookie, which suffices for public APIs such as basic stock quotes, but will not grant access to authenticated features requiring xq_a_token. The _get_json method (lines 31-38) then attaches these cookies to all outgoing requests along with a mandatory Referer: https://xueqiu.com/ header.

Setting Up Xueqiu Authentication

You can provide the required cookie through three methods supported by the Agent Reach codebase.

Option 1: Automatic Browser Extraction (Recommended)

Use the built-in CLI tool to scan your local browser and automatically populate the configuration file:

agent-reach configure --from-browser chrome

This command invokes the extraction logic in agent_reach/cookie_extract.py (lines 285-289). When the scanner detects cookies for the xueqiu domain, it automatically writes the formatted string to the xueqiu_cookie key in your config. This is the most reliable method as it captures the current xq_a_token along with any associated session cookies.

Option 2: Manual Cookie Export

If you prefer manual control or the automatic extraction fails, export cookies directly from your browser:

1. Navigate to https://xueqiu.com and log in to your account.
2. Use a browser extension such as Cookie-Editor (available for Chrome/Firefox).
3. Click the extension icon, select Export → Header String.
4. Copy the resulting string (e.g., xq_a_token=YOUR_TOKEN; other=value...).

Add this string to your configuration file:

nano ~/.agent-reach/config.yaml

Insert or update the line:

xueqiu_cookie: "xq_a_token=YOUR_TOKEN; other=value..."

Option 3: Programmatic Configuration

For applications using Agent Reach as a library, set the cookie programmatically via the Config class before initializing the channel:

from agent_reach.config import Config

cfg = Config()
cfg.set("xueqiu_cookie", "xq_a_token=YOUR_TOKEN; other=value...")

The next time you instantiate XueqiuChannel(), it will read this value from the shared configuration instance.

Working with Authenticated Xueqiu Data

Once authenticated, the XueqiuChannel provides several methods for accessing stock data and social content.

Fetch Real-Time Stock Quotes

Retrieve current market data for specific securities using the authenticated session:

from agent_reach.channels.xueqiu import XueqiuChannel

channel = XueqiuChannel()
quote = channel.get_stock_quote("SH600519")  # Kweichow Moutai

print(quote)

This call uses _get_json internally, which automatically attaches the loaded cookies to the request headers.

Search for Stocks

Search the Xueqiu database by name or ticker symbol:

from agent_reach.channels.xueqiu import XueqiuChannel

channel = XueqiuChannel()
results = channel.search_stock("茅台", limit=5)

for r in results:
    print(f"{r['symbol']}: {r['name']} ({r['exchange']})")

While search functions primarily use public endpoints, the channel includes session cookies for consistency and rate-limit management.

Access Hot Posts (Authenticated)

Retrieve trending financial discussions and posts, which requires a valid xq_a_token:

from agent_reach.channels.xueqiu import XueqiuChannel

channel = XueqiuChannel()
hot_posts = channel.get_hot_posts(limit=10)

for post in hot_posts:
    print(f"{post['author']} – {post['title']}\n{post['url']}\n")

If the authentication cookie is missing or expired, the check() health method will return a warning status, and the API will return authentication errors.

Summary

• Authentication mechanism: Agent Reach uses the xq_a_token cookie from Xueqiu's domain (.xueqiu.com) to authenticate API requests.
• Configuration location: Store the cookie string under the xueqiu_cookie key in ~/.agent-reach/config.yaml.
• Loading order: The XueqiuChannel loads cookies from config first, then attempts browser extraction, and finally falls back to a minimal unauthenticated session.
• Implementation files: Core logic is in agent_reach/channels/xueqiu.py, with CLI extraction tools in agent_reach/cookie_extract.py (lines 285-289).
• CLI convenience: Use agent-reach configure --from-browser chrome to automatically extract and save cookies from your local browser.

Frequently Asked Questions

What is the xq_a_token cookie and why is it required?

The xq_a_token is Xueqiu's session authentication token. According to the source code in agent_reach/channels/xueqiu.py, this cookie is required to access protected endpoints such as user portfolios, hot posts, and certain detailed financial data. Without it, the channel can only access basic public quote data using the anti-DDoS acw_tc cookie obtained from the minimal fallback.

Can I use Agent Reach with Xueqiu without logging in?

Yes, but with limitations. As implemented in _ensure_cookies() (lines 123-128), the channel can operate in a minimal mode by visiting https://xueqiu.com to obtain basic cookies. However, this only supports public endpoints like simple stock quotes. Any method requiring authentication, such as get_hot_posts() or accessing user-specific data, will fail without the xq_a_token cookie.

Which browsers are supported for automatic cookie extraction?

The automatic extraction in agent_reach/cookie_extract.py supports Chrome-style browsers through the rookiepy or browser_cookie3 libraries. When you run agent-reach configure --from-browser chrome, the tool specifically scans for cookies associated with the .xueqiu.com domain in the browser's SQLite cookie store. Firefox and other Chromium-based browsers (Edge, Brave) may also work depending on the underlying library support.

How do I know if my authentication is working correctly?

The XueqiuChannel includes a check() method that validates the current session. If the xq_a_token cookie is valid and recognized by Xueqiu's servers, authenticated methods like get_hot_posts() will return data successfully. If authentication fails, these methods will return errors or empty results, and the health check will indicate a warning status regarding cookie validity.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}