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

> Learn how to authenticate for Xueqiu stock data in Agent Reach. This guide explains using the xq_a_token cookie for seamless API access. Get started now.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-07-04

---

**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`](https://github.com/Panniantong/Agent-Reach/blob/main/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:

```bash
agent-reach configure --from-browser chrome

```

This command invokes the extraction logic in [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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:

```bash
nano ~/.agent-reach/config.yaml

```

Insert or update the line:

```yaml
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:

```python
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:

```python
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:

```python
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`:

```python
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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xueqiu.py), with CLI extraction tools in [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.