---
title: lianyanshe.com auth.md
agent_auth:
  skill: https://lianyanshe.com/auth.md
  protected_resource: https://lianyanshe.com/.well-known/oauth-protected-resource
  register_uri: https://lianyanshe.com/api/agent/register
  audience: public_read_agents_and_approved_operator_integrations
  public_read_access: anonymous
  self_service_registration: false
  registration_methods:
    - operator_out_of_band
  credential_method: bearer_header
---

# lianyanshe.com auth.md

Access policy for **https://lianyanshe.com**. The site is a public research and learning resource with public read APIs, one optional x402 aggregation product, operator-only data maintenance APIs, and optional browser login for people.

**Public read APIs currently require no credential.** Do not send an API key, wallet signature, or user cookie to public GET endpoints.

## Discover

Start with these machine-readable resources:

| Resource | Purpose |
|----------|---------|
| [`/api`](https://lianyanshe.com/api) | Current access state and primary documentation links |
| [`/.well-known/api-catalog`](https://lianyanshe.com/.well-known/api-catalog) | Public API and MCP inventory |
| [`/.well-known/ucp`](https://lianyanshe.com/.well-known/ucp) | UCP business profile for the real paid content product |
| [`/docs/api/openapi.json`](https://lianyanshe.com/docs/api/openapi.json) | OpenAPI 3.1 contract |
| [`/.well-known/oauth-protected-resource`](https://lianyanshe.com/.well-known/oauth-protected-resource) | Bearer challenge metadata and current provisioning state for operator routes |
| [`/.well-known/mcp/server-card.json`](https://lianyanshe.com/.well-known/mcp/server-card.json) | MCP service identity and capabilities |
| [`/llms.txt`](https://lianyanshe.com/llms.txt) | Content scope, appropriate uses, and citation rules |

`GET /api` remains a free discovery response with `access: "public-free"`. Its `commerce.active: true` field advertises the additive paid product at `GET /api/v1`; it does not make the public read APIs paid.

## Pick a method

Choose the least privileged method that matches the task:

| Need | Method | Availability |
|------|--------|--------------|
| Read public HTML or Markdown | Anonymous GET | Available |
| Read market, AI-cycle, stock, or holdings data | Anonymous GET | Available |
| Use MCP read tools | Anonymous MCP request | Available |
| Submit a site suggestion or cooperation inquiry | Anonymous POST from the contact page | Available; rate limited |
| Buy the one-call market + AI-cycle bundle | x402 v2 on Base | Available at `GET /api/v1`; 0.01 USDC |
| Update snapshots or trigger refresh jobs | Operator Bearer token | Private; no self-service enrollment |
| Maintain a human browser session | Google OAuth session cookie | Available to browser users |
| Purchase gated research reports | x402 entitlement | Inactive while the paid report catalog is empty |

Google browser login and the operator Bearer token are separate identities. A Google session never grants data-write permission.

## Register

No registration is needed for public reads or public MCP tools.

Agents cannot self-register for operator write access. The only supported registration method is **operator provisioning out of band**:

1. Send an access request to [lianyanshe@gmail.com](mailto:lianyanshe@gmail.com) with the organization, purpose, required endpoints, expected request volume, and an incident contact.
2. The site operator reviews the request manually. Access is not guaranteed.
3. If approved, the operator delivers a pre-shared Bearer token through a private channel and states the allowed routes.
4. The integration stores the token as a secret, sends it only in the `Authorization` header, and uses the same contact for rotation or revocation.

`GET /api/agent/register` is a read-only machine summary of this policy. It does not create an account or issue a credential. **Do not POST to it:** self-service registration, ID-JAG, verified-email registration, anonymous registration, claim ceremonies, and OAuth token exchange are not available.

Human users who want a browser session may start Google OAuth at `GET /api/auth/google`; Google handles account authentication and returns to the site callback.

## Claim

Public reads have nothing to claim: send the request anonymously.

Approved operator integrations receive credentials out of band from the site operator. This site is not an OAuth Authorization Server and does not advertise one in its Protected Resource Metadata. Never submit a token through a public form, issue tracker, URL query string, or chat transcript.

The real x402 product is `GET /api/v1`, a one-call JSON aggregation of the market dashboard and AI-cycle snapshot. An unpaid request returns HTTP 402 and a `PAYMENT-REQUIRED` header. Fulfill one advertised requirement, then retry the same URL with `PAYMENT-SIGNATURE`. The current requirement is 0.01 USDC on Base (`eip155:8453`). Discover the current contract from `GET /api/x402`; do not copy a cached wallet address or construct a payment for an unlisted path.

`GET /.well-known/ucp` returns the UCP business profile for this one real product and its x402 payment handler. It deliberately does not advertise standard cart, checkout, order, or paid-report capabilities because those flows are not implemented. Per-report claim routes remain dormant while the paid report catalog is empty; public report HTML stays free.

## Use the credential

For public reads:

```http
GET /api/dashboard/snapshot HTTP/1.1
Host: lianyanshe.com
Accept: application/json
```

For an approved operator route only:

```http
PUT /api/dashboard/snapshot HTTP/1.1
Host: lianyanshe.com
Authorization: Bearer <operator_token>
Content-Type: application/json

{
  "meta": {
    "schemaVersion": 2,
    "releaseVersion": "1.31.7",
    "writerCommit": "<40-character-git-commit>",
    "writeScope": "crypto",
    "pushSource": "approved-production-runner"
  },
  "macro": { "items": [] },
  "crypto": { "items": [] }
}
```

Keep Bearer tokens in a secret store or protected environment variable. Do not place them in source files, client-side JavaScript, analytics, logs, screenshots, URLs, or documentation. Send credentials only to `https://lianyanshe.com` and only over HTTPS.

The Bearer token alone is not sufficient for dashboard, options, or AI-cycle writes. Each approved writer must also provide the current production schema, release, exact Git commit, source, and write scope. The release must exactly match the currently deployed Worker: older jobs and newer, not-yet-deployed GitHub Actions are both rejected. HTTP `409 dashboard_writer_version_conflict` means the process is stale, ahead of production, or running outside the official production checkout; update or deploy the runner instead of retrying the same payload.

Approved writers may use the same Bearer token on a GET of a snapshot route to perform a strong post-write read. That read bypasses the public edge copy and is returned with `Cache-Control: no-store`; ordinary anonymous reads remain cached.

The main operator-only routes are snapshot writes and refresh jobs under `/api/dashboard`, `/api/ai-cycle`, and `/api/stockanalysis`, plus the local Hermes inbox at `GET /api/feedback/inbox`. The inbox token is never exposed to the contact page. The complete list and request bodies are defined by the OpenAPI contract.

## Errors

| Status | Meaning | Client action |
|--------|---------|---------------|
| `400` | Missing or invalid parameter/body | Correct the request; do not retry unchanged |
| `401` | Missing or invalid Bearer token | Stop and obtain a valid operator credential |
| `403` | Credential is not allowed for the operation | Stop; do not attempt to bypass the restriction |
| `409` | Authenticated writer is stale, untraceable, or outside its allowed data scope | Stop; run the job from the current official production checkout |
| `402` | A listed x402 product requires payment | Read `PAYMENT-REQUIRED`, pay one accepted option, and retry the same URL once |
| `404` | Route or resource is absent | Re-discover from `/api`, the API catalog, or the UCP profile |
| `429` | Request rate is too high | Back off and retry with jitter |
| `5xx` | Temporary service or upstream failure | Retry a limited number of times, then report it |

Protected Bearer routes may return:

```http
WWW-Authenticate: Bearer realm="lianyanshe", resource_metadata="https://lianyanshe.com/.well-known/oauth-protected-resource"
```

Treat the HTTP status and response body as the current truth. Do not assume a path is paid, authenticated, or writable merely because an older cached document mentioned it.

## Revocation

Operator tokens can be rotated or revoked by the site operator at any time. If a token may have leaked, stop using it and contact [lianyanshe@gmail.com](mailto:lianyanshe@gmail.com) immediately with the affected integration and approximate exposure time; never include the token itself.

Browser users can end their site session at `GET` or `POST /api/auth/logout` and can revoke the site's Google access from their Google account permissions.

The Agent Research Bundle is a paid one-request delivery rather than a login credential. Do not reuse a payment signature for unrelated paths. Future report entitlements, if activated, expire according to the resource-specific period; current public reports do not require one.

## Public read inventory

- `GET /api/dashboard/snapshot`, `/options`, and `/health`
- `GET /api/ai-cycle/snapshot`
- `GET /api/stockanalysis/snapshot`, `/live`, `/search`, `/kline`, `/events`, `/events/summary`, and `/feed` (`/live` returns full fundamentals only when previously published; otherwise price-only `no-data`)
- `GET /api/holdings/kline`
- `POST /api/feedback` for limited-length site suggestions and cooperation inquiries submitted from the contact page
- `POST /mcp` for the documented public MCP read tools
- Public site pages, `llms.txt`, sitemap, and supported HTML-to-Markdown responses

## Paid product inventory

- `GET /api/v1`: 0.01 USDC via x402 v2 on Base; returns the dashboard and AI-cycle snapshots in one response after settlement
- `GET /api/x402`: free product and protocol discovery
- `GET /.well-known/ucp`: free UCP service, capability, endpoint, and payment-handler discovery

## Contact

- Access and security: [lianyanshe@gmail.com](mailto:lianyanshe@gmail.com)
- Human-readable API guide: [https://lianyanshe.com/docs/api/](https://lianyanshe.com/docs/api/)
- Corrections and data issues: [https://lianyanshe.com/contact.html](https://lianyanshe.com/contact.html)